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.sequencer - Options for sequencer provider
• 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()

Or you could explicitly specify a network using the network keyword:

const provider = new starknet.Provider({
  sequencer: {
    network: 'mainnet-alpha' // or 'goerli-alpha'
  }
})

Since using the network keyword is limited to just mainnet-alpha and goerli-alpha, Starknet.js also provides a means to connect to any custom network on StarkNet using the baseurl:

const provider = new starknet.Provider({
  sequencer: {
    baseUrl: 'https://alpha4.starknet.io',
    feederGatewayUrl: 'feeder_gateway',
    gatewayUrl: 'gateway',
  }
})

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

Sequencer Provider

The default provider from above is also a sequencer provider, but the sequencer provider extends the methods available in the default provider.

Instantiation

To instantiate a sequencer provider:

new starknet.SequencerProvider(optionsOrProvider)

Where the options just like the default provider, take in either the network keyword (if the network is mainnet-alpha or goerli-alpha) else a custom setup containing:

• 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

Example Here's a setup for goerli testnet-2:

const provider = new starknet.SequencerProvider({
  baseUrl: 'https://alpha4-2.starknet.io',
  feederGatewayUrl: 'feeder_gateway',
  gatewayUrl: 'gateway',
})

Methods

1. provider.getContractAddresses() => Promise < GetContractAddressesResponse >

Gets the smart contract address on the network.

Response

{
  Starknet: string;
  GpsStatementVerifier: string;
}

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

Gets the smart contract code.

Response

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

3. 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

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

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

Gets the status of a transaction.

Response

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

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

Gets the transaction trace from a tx hash.

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

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