Skip to main content
Version: Next

Provider

The Provider API allows you to interact with the Starknet network, without signing transactions or messages.

Typically, these are read calls on the blockchain.

Creating an instance

new starknet.Provider(optionsOrProvider)

The options for the provider depend on the network. The structure of the options object is:

  • options.sequencer - Options for sequencer provider
  • options.rpc - Options for RPC provider

The easiest way to get started is:

const provider = new starknet.Provider()

The above snippet creates a Starknet Provider instance with testnet SN_GOERLI2 network.

However, if you want to use mainnet SN_MAIN or explicitly declare the network, you can use:

const provider = new starknet.Provider({
sequencer: {
network: NetworkName.SN_MAIN // or NetworkName.SN_GOERLI2
}
})

If you want more control:

const provider = new starknet.Provider({
sequencer: {
baseUrl: BaseUrl.SN_GOERLI,
feederGatewayUrl: 'feeder_gateway',
gatewayUrl: 'gateway',
}
})

These are also the default options for the Provider constructor with network: 'SN_GOERLI2'.

Note

network argument should work in most cases. If you want to use the sequencer argument with baseUrl, you will not be able to use the network field in the object.

Methods

getChainId()

provider.getChainId() => Promise < StarknetChainId >

Returns the chain Id for the current network.


callContract()

provider.callContract(call [ , blockIdentifier ]) => Promise < CallContractResponse >

Calls a function on the Starknet contract.

The call object structure:

  • call.contractAddress - Address of the contract
  • call.entrypoint - Entrypoint of the call (method name)
  • call.calldata - Payload for the invoking method
CallContractResponse
{
result: string[];
}

getBlock()

provider.getBlock(blockIdentifier) => Promise < GetBlockResponse >

Gets the block information.

GetBlockResponse
{
accepted_time: number;
block_hash: string;
block_number: number;
gas_price: string;
new_root: string;
old_root?: string;
parent_hash: string;
sequencer: string;
status: 'NOT_RECEIVED' | 'RECEIVED' | 'PENDING' | 'ACCEPTED_ON_L2' | 'ACCEPTED_ON_L1' | 'REJECTED';
transactions: Array<string>;
starknet_version?: string;
}

getClassAt()

provider.getClassAt(contractAddress, blockIdentifier) => Promise < ContractClass >

Gets the contract class of the deployed contract.

ContractClass
{
program: CompressedProgram;
entry_points_by_type: EntryPointsByType;
abi?: Abi;
}

getInvokeEstimateFee()

provider.getInvokeEstimateFee(invocationWithTxType, invocationDetails, blockIdentifier) => Promise < EstimateFeeResponse >

Estimate fee for invoke transaction.

EstimateFeeResponse
{
overall_fee: BN;
gas_consumed?: BN;
gas_price?: BN;
}

getNonceForAddress()

provider.getNonceForAddress(contractAddress, blockIdentifier) => Promise < BigNumberish >

Gets the nonce of the provided contractAddress. This was renamed from getNonce to getNonceForAddress to avoid confusion when inheriting an Account from the Provider class.


getStorageAt()

provider.getStorageAt(contractAddress, key, blockIdentifier) => Promise < string >

Gets the contract's storage variable at a specific key.


getTransactionReceipt()

provider.getTransactionReceipt(txHash) => Promise < GetTransactionReceiptResponse >

Gets the status of a transaction.

GetTransactionReceiptResponse
{
transaction_hash: string;
status: 'NOT_RECEIVED' | 'RECEIVED' | 'PENDING' | 'ACCEPTED_ON_L2' | 'ACCEPTED_ON_L1' | 'REJECTED';
actual_fee?: string;
status_data?: string;
messages_sent?: Array<MessageToL1>;
events?: Array<Event>;
l1_origin_message?: MessageToL2;
}

getTransaction()

provider.getTransaction(txHash) => Promise < GetTransactionResponse >

Gets the transaction information from a tx hash.

GetTransactionResponse
{
transaction_hash: string;
version?: string;
signature?: Signature;
max_fee?: string;
nonce?: string;
contract_address?: string;
entry_point_selector?: string;
calldata?: RawCalldata;
contract_class?: ContractClass;
sender_address?: string;
}

declareContract()

provider.declareContract(transaction, details) => Promise < DeclareContractResponse >

Declare a contract on Starknet.

DeclareContractResponse
{
transaction_hash: string;
class_hash: string;
};

getDeclareEstimateFee()

provider.getDeclareEstimateFee(transaction, details, blockIdentifier) => Promise < EstimateFeeResponse >

Estimate fee for declare transaction.

EstimateFeeResponse
{
overall_fee: BN;
gas_consumed?: BN;
gas_price?: BN;
};

waitForTransaction()

provider.waitForTransaction(txHash [ , options]) => Promise < GetTransactionReceiptResponse >

Wait for the transaction to be accepted on L2 or L1.


getStarkName()

provider.getStarkName(address, StarknetIdContract) => Promise<string | Error>

Gets starknet.id stark name with the address provided

The StarknetIdContract argument can be undefined, if it is, the function will automatically use official starknet id contracts of your network.

Returns directly a string (Example: vitalik.stark).


getAddressFromStarkName()

provider.getAddressFromStarkName(name, StarknetIdContract) => Promise<string | Error>

Gets account address with the starknet id stark name.

The StarknetIdContract argument can be undefined, if it is, the function will automatically use official starknet id contracts of your network.

Returns directly the address in a string (Example: 0xff...34).


getStateUpdate()

provider.getStateUpdate(blockIdentifier) => Promise < StateUpdateResponse >

Gets the state changes in a specific block

StateUpdateResponse
{
block_hash: string;
new_root: string;
old_root: string;
state_diff: {
storage_diffs: Array<StorageDiffItem>;
declared_contract_hashes: Array<string>;
deployed_contracts: Array<DeployedContractItem>;
nonces: Array<Nonces>;
};
};