Skip to main content
Version: 4.17.1

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.

Default Provider​

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_GOERLI 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_GOERLI
  }
})

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_GOERLI'.

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.

SequencerProvider​

On top of methods found in the Default Provider section, SequencerProvider has some additional ones you can use.

Creating an instance​

new starknet.SequencerProvider(optionsOrProvider)

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

  • options.baseUrl - Base URL of the network
  • options.feederGatewayUrl - Feeder Gateway Endpoint of the network
  • options.gatewayUrl - Gateway Endpoint
  • options.headers - [Optional] custom fetch headers

or

  • options.network - NetworkName
  • options.headers - [Optional] custom fetch headers

Example:

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

Methods​

getContractAddresses()​

provider.getContractAddresses() => Promise < GetContractAddressesResponse >

Gets the smart contract address on the network.

GetContractAddressesResponse​
{
  Starknet: string;
  GpsStatementVerifier: string;
}

getCode()​

provider.getCode(contractAddress, blockIdentifier) => Promise < GetCodeResponse >

Gets the smart contract address on the network.

GetCodeResponse​
{
  bytecode: string[];
  abi: Abi;
}

estimateMessageFee()​

provider.estimateMessageFee(CallL1Handler, blockIdentifier) => Promise < EstimateFeeResponse >

Estimate fee for sending a message to L1.

CallL1Handler​
type CallL1Handler = {
  from_address: getDecimalString(from_address),
  to_address: getHexString(to_address),
  entry_point_selector: getSelector(entry_point_selector),
  payload: getHexStringArray(payload),
};

###### _EstimateFeeResponse_

```typescript
{
  overall_fee: number;
  gas_price: number;
  gas_usage: number;
  unit: string;
}

getTransactionStatus()​

provider.getTransactionStatus(txHash) => Promise < GetTransactionStatusResponse >

Gets the status of a transaction.

GetTransactionStatusResponse​
{
  tx_status: 'NOT_RECEIVED' | 'RECEIVED' | 'PENDING' | 'ACCEPTED_ON_L2' | 'ACCEPTED_ON_L1' | 'REJECTED';
  block_hash: string;
  tx_failure_reason?: {
    tx_id: number;
    code: string;
    error_message: string;
  }
}

getTransactionTrace()​

provider.getTransactionTrace(txHash) => Promise < GetTransactionTraceResponse >

Gets the transaction trace from a tx hash.

GetTransactionTraceResponse​
{
  validate_invocation?: FunctionInvocation;
  function_invocation?: FunctionInvocation;
  fee_transfer_invocation?: FunctionInvocation;
  signature: Signature;
}

{
  FunctionInvocation: {
    caller_address: string;
    contract_address: string;
    calldata: {
      [inputName: string]: string | string[] | { type: 'struct'; [k: string]: BigNumberish };
    };
    call_type?: string;
    class_hash?: string;
    selector?: string;
    entry_point_type?: EntryPointType;
    result: Array<any>;
    execution_resources: ExecutionResources;
    internal_calls: Array<FunctionInvocation>;
    events: Array<any>;
    messages: Array<any>;
  };
}

RpcProvider​

Creating an instance​

new starknet.RpcProvider(options)

  • options.nodeUrl - Starknet RPC node url
  • options.headers - [Optional] custom fetch headers
  • options.retries - [Optional] wait for transaction max retries
  • options.blockIdentifier - [Optional] default value set to 'latest'

Example:

const provider = new starknet.RpcProvider({
  nodeUrl: 'URL_TO_STARKNET_RPC_NODE',
})

Methods​

fetch()​

provider.fetch(method: any, params: any) => Promise < any >

Generic method for users to be able to experiment with RPC methods.

getChainId()​

provider.getChainId() => Promise < any >

getBlock()​

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

getBlockHashAndNumber()​

provider.getBlockHashAndNumber() => Promise < BlockHashAndNumber >

BlockHashAndNumber​
{
  block_hash: BLOCK_HASH;
  block_number: BLOCK_NUMBER;
}

getBlockWithTxHashes()​

provider.getBlockWithTxHashes(blockIdentifier) => Promise < GetBlockWithTxHashesResponse >

GetBlockWithTxHashesResponse​
OPENRPC.BlockWithTxHashes

getBlockWithTxs()​

provider.getBlockWithTxs(blockIdentifier) => Promise < GetBlockWithTxs >

GetBlockWithTxs​
OPENRPC.BlockWithTxs

getClassHashAt()​

provider.getClassHashAt(blockIdentifier) => Promise < ContractAddress >

getTransactionCount()​

provider.getTransactionCount(blockIdentifier) => Promise < number >

Gets the transaction count from a block.

getBlockNumber()​

provider.getBlockNumber() => Promise < number >

Gets the latest block number.

getPendingTransactions()​

provider.getPendingTransactions() => Promise < PendingTransactions >

PendingTransactions​
OPENRPC.PendingTransactions;

getStateUpdate()​

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

StateUpdate​
OPENRPC.StateUpdate;

getStorageAt()​

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

getTransaction()​

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

getTransactionByHash()​

provider.getTransactionByHash(txHash) => Promise < GetTransactionByHashResponse >

GetTransactionByHashResponse​
OPENRPC.Transaction;

getTransactionByBlockIdAndIndex()​

provider.getTransactionByBlockIdAndIndex(blockIdentifier, index) => Promise < GetTransactionByBlockIdAndIndex >

GetTransactionByBlockIdAndIndex​
OPENRPC.Transaction;

getTransactionReceipt()​

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

getClass()​

provider.getClass(classHash) => Promise < ContractClass >

ContractClass​
OPENRPC.ContractClass;

getClassAt()​

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

ContractClass​
OPENRPC.ContractClass;

getInvokeEstimateFee()​

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

EstimateFeeResponse​
  overall_fee: BN;
  gas_consumed?: BN;
  gas_price?: BN;

getDeclareEstimateFee()​

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

EstimateFeeResponse​
  overall_fee: BN;
  gas_consumed?: BN;
  gas_price?: BN;

declareContract()​

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

DeclareContractResponse​
  transaction_hash: string;
  class_hash: string;

callContract()​

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

getContractAddresses()​

provider.traceTransaction(transactionHash) => Promise < Trace >

Trace​
OPENRPC.Trace;

traceBlockTransactions()​

provider.traceBlockTransactions(blockHash) => Promise < Traces >

Traces​
OPENRPC.Traces;

getSyncingStats()​

provider.getSyncingStats() => Promise < GetSyncingStatsResponse >

Gets syncing status of the node.

GetSyncingStatsResponse​
boolean |
{
  starting_block_hash: string;
  starting_block_num: string;
  current_block_hash: string;
  current_block_num: string;
  highest_block_hash: string;
  highest_block_num: string;
}

getEvents()​

provider.getEvents(eventFilter) => Promise < GetEventsResponse >

Gets all the events filtered

EventFilter​
type EventFilter = {
  fromBlock: string;
  toBlock: string;
  address: string;
  keys: string[];
  page_size: number;
  page_number: number;
};
GetEventsResponse​
{
  events: StarknetEmittedEvent[];
  page_number: number;
  is_last_page: number;
}