Provider

The Provider is an API from Starknet.js, that enables you to interact with StarkNet, without necessarily signing messages, e.g when performing read calls. You can read states without signing messages, but you cannot alter or modify the contract’s state.

Default Provider

Instantiation

Starknet.js library provides several options which should cover the use case of a vast majority but also includes a robust function for a more customized configuration if necessary. Instantiating a new Provider can be done with this single line of code:

new starknet.Provider(optionsOrProvider)

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

• options.rpc - Options for RPC provider

You could choose to instantiate using the default means, which automatically creates a Provider instance on StarkNet's alpha-goerli:

const provider = new starknet.Provider()

To instantiate using an RPC provider, you need to explicitly pass in the node_url:

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

Methods

Starknet.js provides you with a plethora of method calls when using the default provider:

1. provider.getChainId() => Promise < StarknetChainId >

Returns the chain Id for the current network.

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

Calls a function on the StarkNet contract.

Response

{
  result: string[];
}

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

Gets the block information.

Response​

{
  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;
}

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

Gets the contract class of the deployed contract.

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

Estimates fee for invoke transaction.

Response

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

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

Gets the status of a transaction.

Response

{
  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;
}

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

Gets the transaction information from a tx hash.

Response

{
  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;
}

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

Gets the nonce of the provided contractAddress.

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

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

10. provider.deployContract(payload [ , abi ]) => Promise < DeployContractResponse >

Deploys a contract on Starknet.

Response

{
  transaction_hash: string;
  contract_address: string;
};

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

Declare a contract on Starknet.

Response

{
  transaction_hash: string;
  class_hash: string;
};

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

Estimate fee for declare transaction.

Response

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

RPC Provider

Instantiation

An RPC (Remote procedure call) node enables users to make read and write calls to the blockchain. To instantiate an RPC provider: new starknet.RpcProvider(options) Where options can contain: options.nodeUrl - Starknet RPC node url options.headers - [Optional] custom fetch headers options.retries - [Optional] wait for transaction max retries

Example

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

Methods

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

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

2. provider.getChainId() => Promise < any >

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

4. provider.getBlockHashAndNumber() => Promise < BlockHashAndNumber >

Response​

{
  block_hash: BLOCK_HASH;
  block_number: BLOCK_NUMBER;
}

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

Response​

OPENRPC.BlockWithTxHashes

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

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

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

Gets the transaction count from a block.

9. provider.getBlockNumber() => Promise < number >

Gets the latest block number.

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

Gets the nonce of the provided contractAddress

11. provider.getPendingTransactions() => Promise < PendingTransactions >

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

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

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

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

Response​

OPENRPC.Transaction;

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

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

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

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

Response

overall_fee: BN;  
gas_consumed?: BN;  
gas_price?: BN;

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

Response​

overall_fee: BN;  
gas_consumed?: BN;  
gas_price?: BN;

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

Response​

transaction_hash: string;  
class_hash: string;

22. provider.deployContract(contract, constructorCalldata, addressSalt) => Promise < DeployContractResponse >

Response​

contract_address: string;  transaction_hash: string;

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

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

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

26. provider.getSyncingStats() => Promise < GetSyncingStatsResponse >

Gets the syncing status of the node.

Response​

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;
}

27. 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;
};

Response​

{
  events: StarknetEmittedEvent[];
  page_number: number;
  is_last_page: number;
}