@apibara/starknet
This package contains the StarkNet streams Protobuf definitions. Use this package to decode data received by one of the StarkNet streams.
Installation#
Install the package from npm:
npm add @apibara/starknet
yarn install @apibara/starknet
pnpm add @apibara/starknet
FieldElement#
The Apibara stream encodes StarkNet field elements (also known as felts) into 4 uint64 numbers. The SDK provides helper functions to convert from this representation into Javascript's bigint
.
import { FieldElement } from '@apibara/starknet'// converts the encoded value to bigintFieldElement.toBigInt(encoded)// converts the field element to hexFieldElement.toHex(encoded)// encodes the bigint into a field elementFieldElement.fromBigInt(encoded)
Filter#
The Filter
object is used to request specific data to an Apibara stream. The
SDK contains an helper module to construct filters. You can find more about
filters in the StarkNet section.
import { Filter } from '@apibara/starknet'const filter = Filter.create().withHeader().addEvent((ev) => ev.withFromAddress(myAddress).withKeys([transferEvent])).encode()
create
#
Returns a new FilterBuilder
.
FilterBuilder
#
This class is used to build a filter.
withHeader
Include block headers.
addTransaction
Add one transaction filter. The method accepts a callback invoked with one TransactionFilter
parameter.
Example
Filter.create().addTransaction(tx => tx.deploy().withClassHash(myClassHash))
addEvent
Add one event filter. The method accepts a callback invoked with one EventFilter
parameter.
Example
Filter.create().addEvent(ev => ev.withFromAddress(myAddress))
addMessage
Add one L2 to L1 message filter. The method accepts a callback invoked with one L2ToL1MessageFilter
parameter.
Example
Filter.create().addMessage(msg => msg.withToAddress(myAddress))
withStateUpdate
Add state update data. The method accepts a callback invoked with one StateUpdateFilter
parameter.
Example
Filter.create().withStateUpdate((su) => su.addStorageDiff((st) => st.withContractAddress(address)))
encode
Returns the filter in encoded form, ready to be added to a request.
TransactionFilter
#
The transaction filter is used to filter StarkNet transactions.
any
Include any transaction.
invokeV0
Returns a InvokeV0TransactionFilter
to further filter invoke V0 transactions.
invokeV1
Returns a InvokeV1TransactionFilter
to further filter invoke V1 transactions.
deploy
Returns a DeployTransactionFilter
to further filter deploy transactions.
declare
Returns a DeclareTransactionFilter
to further filter declare transactions.
l1Handler
Returns a L1HandlerTransactionFilter
to further filter declare transactions.
deployAccount
Returns a DeployAccountTransactionFilter
to further filter deploy account transactions.
InvokeV0TransactionFilter
#
withContractAddress
Filter by contract address.
withEntryPointSelector
Filter by entry point selector.
withCalldata
Filter by call data prefix.
InvokeV1TransactionFilter
#
withSenderAddress
Filter by sender address.
withCalldata
Filter by call data prefix.
DeployTransactionFilter
#
withContractAddressSalt
Filter by contract address salt.
withClassHash
Filter by class hash.
withConstructorCalldata
Filter by constructor call data prefix.
DeclareTransactionFilter
#
withSenderAddress
Filter by sender address.
withClassHash
Filter by class hash.
L1HandlerTransactionFilter
#
withContractAddress
Filter by contract address.
withEntryPointSelector
Filter by entry point selector.
withCalldata
Filter by call data prefix.
DeployAccountTransactionFilter
#
withContractAddressSalt
Filter by contract address salt.
withClassHash
Filter by class hash.
withConstructorCalldata
Filter by constructor call data prefix.
EventFilter
#
withFromAddress
Filter by address emitting the event.
withKeys
Filter by event keys prefix. Usually, the key is the Pedersen hash of the event name.
withData
Filter by data prefix.
L2ToL1MessageFilter
#
withToAddress
Filter by destination address.
withPayload
Filter by payload prefix.
StateUpdateFilter
#
addStorageDiff
Add one storage diff filter. The method accepts a callback invoked with one StorageDiffFilter
parameter.
Example
const filter = Filter.create().withStateUpdate(su =>su.addStorageDiff(diff => diff.withContractAddress(myAddress)))
addDeclaredContract
Add one declared contract filter. The method accepts a callback invoked with one DeclaredContractFilter
parameter.
Example
const filter = Filter.create().withStateUpdate(su =>su.addDeclaredContract(decl => decl.withClassHash(myHash)))
addDeployedContract
Add one deployed contract filter. The method accepts a callback invoked with one DeployedContractFilter
parameter.
Example
const filter = Filter.create().withStateUpdate(su =>su.addDeployedContract(dep => dep.withClassHash(myHash)))
addNonceUpdate
Add one nonce updated filter. The method accepts a callback invoked with one NonceUpdateFilter
parameter.
Example
const filter = Filter.create().withStateUpdate(su =>su.addNonceUpdate(nonce => nonce.withContractAddress(myAddress)))
StorageDiffFilter
#
withContractAddress
Filter by contract address.
DeclaredContractFilter
#
withClassHash
Filter by class hash.
DeployedContractFilter
#
withContractAddress
Filter by contract address.
withClassHash
Filter by class hash.
NonceUpdateFilter
#
withContractAddress
Filter by contract address.
withNonce
Filter by nonce.
Block data#
Each batch item contains the requested block data. The Typescript definitions are automatically generated from the Protobuf definition.
import { v1alpha2 } from '@apibara/starknet'
The Block
type can be used to parse a StarkNet block from the raw byte content.
for await (const message of client) {if (message.data?.data) {for (let item of message.data.data) {// block is `v1alpha2.IBlock`const block = v1alpha2.Block.decode(item)}}}
IBlock
#
interface IBlock {/** Block status */status?: (BlockStatus|null);/** Block header */header?: (IBlockHeader|null);/** Block transactions */transactions?: (ITransactionWithReceipt[]|null);/** Block stateUpdate */stateUpdate?: (IStateUpdate|null);/** Block events */events?: (IEventWithTransaction[]|null);/** Block l2ToL1Messages */l2ToL1Messages?: (IL2ToL1MessageWithTransaction[]|null);}
IBlockHeader
#
interface IBlockHeader {/** BlockHeader blockHash */blockHash?: (IFieldElement|null);/** BlockHeader parentBlockHash */parentBlockHash?: (IFieldElement|null);/** BlockHeader blockNumber */blockNumber?: (number|Long|null);/** BlockHeader sequencerAddress */sequencerAddress?: (IFieldElement|null);/** BlockHeader newRoot */newRoot?: (IFieldElement|null);/** BlockHeader timestamp */timestamp?: (google.protobuf.ITimestamp|null);}
BlockStatus
#
enum BlockStatus {BLOCK_STATUS_UNSPECIFIED = 0,BLOCK_STATUS_PENDING = 1,BLOCK_STATUS_ACCEPTED_ON_L2 = 2,BLOCK_STATUS_ACCEPTED_ON_L1 = 3,BLOCK_STATUS_REJECTED = 4}
ITransactionWithReceipt
#
interface ITransactionWithReceipt {/** TransactionWithReceipt transaction */transaction?: (ITransaction|null);/** TransactionWithReceipt receipt */receipt?: (ITransactionReceipt|null);}
ITransaction
#
interface ITransaction {/** Transaction meta */meta?: (ITransactionMeta|null);/** Transaction invokeV0 */invokeV0?: (IInvokeTransactionV0|null);/** Transaction invokeV1 */invokeV1?: (IInvokeTransactionV1|null);/** Transaction deploy */deploy?: (IDeployTransaction|null);/** Transaction declare */declare?: (IDeclareTransaction|null);/** Transaction l1Handler */l1Handler?: (IL1HandlerTransaction|null);/** Transaction deployAccount */deployAccount?: (IDeployAccountTransaction|null);}
ITransactionMeta
#
interface ITransactionMeta {/** TransactionMeta hash */hash?: (IFieldElement|null);/** TransactionMeta maxFee */maxFee?: (IFieldElement|null);/** TransactionMeta signature */signature?: (IFieldElement[]|null);/** TransactionMeta nonce */nonce?: (IFieldElement|null);/** TransactionMeta version */version?: (number|Long|null);}
IInvokeTransactionV0
#
interface IInvokeTransactionV0 {/** InvokeTransactionV0 contractAddress */contractAddress?: (IFieldElement|null);/** InvokeTransactionV0 entryPointSelector */entryPointSelector?: (IFieldElement|null);/** InvokeTransactionV0 calldata */calldata?: (IFieldElement[]|null);}
IInvokeTransactionV1
#
interface IInvokeTransactionV1 {/** InvokeTransactionV1 senderAddress */senderAddress?: (IFieldElement|null);/** InvokeTransactionV1 calldata */calldata?: (IFieldElement[]|null);}
IDeployTransaction
#
interface IDeployTransaction {/** DeployTransaction constructorCalldata */constructorCalldata?: (IFieldElement[]|null);/** DeployTransaction contractAddressSalt */contractAddressSalt?: (IFieldElement|null);/** DeployTransaction classHash */classHash?: (IFieldElement|null);}
IDeclareTransaction
#
interface IDeclareTransaction {/** DeclareTransaction classHash */classHash?: (IFieldElement|null);/** DeclareTransaction senderAddress */senderAddress?: (IFieldElement|null);}
IL1HandlerTransaction
#
interface IL1HandlerTransaction {/** L1HandlerTransaction contractAddress */contractAddress?: (IFieldElement|null);/** L1HandlerTransaction entryPointSelector */entryPointSelector?: (IFieldElement|null);/** L1HandlerTransaction calldata */calldata?: (IFieldElement[]|null);}
IDeployAccountTransaction
#
interface IDeployAccountTransaction {/** DeployAccountTransaction constructorCalldata */constructorCalldata?: (IFieldElement[]|null);/** DeployAccountTransaction contractAddressSalt */contractAddressSalt?: (IFieldElement|null);/** DeployAccountTransaction classHash */classHash?: (IFieldElement|null);}
ITransactionReceipt
#
interface ITransactionReceipt {/** TransactionReceipt transactionHash */transactionHash?: (IFieldElement|null);/** TransactionReceipt transactionIndex */transactionIndex?: (number|Long|null);/** TransactionReceipt actualFee */actualFee?: (IFieldElement|null);/** TransactionReceipt l2ToL1Messages */l2ToL1Messages?: (IL2ToL1Message[]|null);/** TransactionReceipt events */events?: (IEvent[]|null);}
IL2ToL1MessageWithTransaction
#
interface IL2ToL1MessageWithTransaction {/** L2ToL1MessageWithTransaction transaction */transaction?: (ITransaction|null);/** L2ToL1MessageWithTransaction receipt */receipt?: (ITransactionReceipt|null);/** L2ToL1MessageWithTransaction message */message?: (IL2ToL1Message|null);}
IL2ToL1Message
#
interface IL2ToL1Message {/** L2ToL1Message toAddress */toAddress?: (IFieldElement|null);/** L2ToL1Message payload */payload?: (IFieldElement[]|null);}
IEventWithTransaction
#
interface IEventWithTransaction {/** EventWithTransaction transaction */transaction?: (ITransaction|null);/** EventWithTransaction receipt */receipt?: (ITransactionReceipt|null);/** EventWithTransaction event */event?: (IEvent|null);}
IEvent
#
interface IEvent {/** Event fromAddress */fromAddress?: (IFieldElement|null);/** Event keys */keys?: (IFieldElement[]|null);/** Event data */data?: (IFieldElement[]|null);}
IStateUpdate
#
interface IStateUpdate {/** StateUpdate newRoot */newRoot?: (IFieldElement|null);/** StateUpdate oldRoot */oldRoot?: (IFieldElement|null);/** StateUpdate stateDiff */stateDiff?: (IStateDiff|null);}
IStateDiff
#
interface IStateDiff {/** StateDiff storageDiffs */storageDiffs?: (IStorageDiff[]|null);/** StateDiff declaredContracts */declaredContracts?: (IDeclaredContract[]|null);/** StateDiff deployedContracts */deployedContracts?: (IDeployedContract[]|null);/** StateDiff nonces */nonces?: (INonceUpdate[]|null);}
IStorageDiff
#
interface IStorageDiff {/** StorageDiff contractAddress */contractAddress?: (IFieldElement|null);/** StorageDiff storageEntries */storageEntries?: (IStorageEntry[]|null);}
IStorageEntry
#
interface IStorageEntry {/** StorageEntry key */key?: (IFieldElement|null);/** StorageEntry value */value?: (IFieldElement|null);}
IDeclaredContract
#
interface IDeclaredContract {/** DeclaredContract classHash */classHash?: (IFieldElement|null);}
IDeployedContract
#
interface IDeployedContract {/** DeployedContract contractAddress */contractAddress?: (IFieldElement|null);/** DeployedContract classHash */classHash?: (IFieldElement|null);}
INonceUpdate
#
interface INonceUpdate {/** NonceUpdate contractAddress */contractAddress?: (IFieldElement|null);/** NonceUpdate nonce */nonce?: (IFieldElement|null);}