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.

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.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.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.declareContract(payload) => Promise < DeclareContractResponse >

Declares a contract on Starknet.

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

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

Deploys a contract on Starknet.

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

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

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

SequencerProvider

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

or

  • options.network - Either 'mainnet-alpha' or 'goerli-alpha'

Example:

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

Methods

Gets the smart contract address on the network.

provider.getContractAddresses() => Promise < GetContractAddressesResponse >

GetContractAddressesResponse
{
Starknet: string;
GpsStatementVerifier: 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

Example:

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

Methods

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

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