Skip to main content

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 goerli-alpha network.

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

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

If you want more control:

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

These are also the default options for the Provider constructor with network: 'goerli-alpha'.

Note

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

Methods


provider.getChainId() => Promise < StarknetChainId >

Returns the chain Id for the current network.


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

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

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

Gets the contract class of the deployed contract.

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

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

Estimate fee for invoke transaction.

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

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

Gets the nonce of the provided contractAddress.


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

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


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

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

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

Deploys a contract on Starknet.

DeployContractResponse
{
transaction_hash: string;
contract_address: string;
};

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

Declare a contract on Starknet.

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

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

Estimate fee for declare transaction.

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

provider.waitForTransaction(txHash [ , retryInterval]) => Promise < void >

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 - Either 'mainnet-alpha' or 'goerli-alpha'
  • options.headers - [Optional] custom fetch headers

Example:

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

Methods


provider.getContractAddresses() => Promise < GetContractAddressesResponse >

Gets the smart contract address on the network.

GetContractAddressesResponse
{
Starknet: string;
GpsStatementVerifier: string;
}

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

Gets the smart contract address on the network.

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

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

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

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

Example:

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

Methods


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

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


provider.getChainId() => Promise < any >


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


provider.getBlockHashAndNumber() => Promise < BlockHashAndNumber >

BlockHashAndNumber
{
block_hash: BLOCK_HASH;
block_number: BLOCK_NUMBER;
}

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

GetBlockWithTxHashesResponse
OPENRPC.BlockWithTxHashes

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

GetBlockWithTxs
OPENRPC.BlockWithTxs

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


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

Gets the transaction count from a block.


provider.getBlockNumber() => Promise < number >

Gets the latest block number.


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

Gets the nonce of the provided contractAddress


provider.getPendingTransactions() => Promise < PendingTransactions >

PendingTransactions
OPENRPC.PendingTransactions;

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

StateUpdate
OPENRPC.StateUpdate;

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


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


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

GetTransactionByHashResponse
OPENRPC.Transaction;

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

GetTransactionByBlockIdAndIndex
OPENRPC.Transaction;

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


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

ContractClass
OPENRPC.ContractClass;

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

ContractClass
OPENRPC.ContractClass;

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

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

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

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

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

DeclareContractResponse
  transaction_hash: string;
class_hash: string;

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

DeployContractResponse
  contract_address: string;
transaction_hash: string;

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


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

Trace
OPENRPC.Trace;

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

Traces
OPENRPC.Traces;

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

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