Apibara Typescript SDK

API Reference

@apibara/protocol
@apibara/starknet

API Reference (legacy)

@apibara/protocol: v0.3
@apibara/starknet: v0.1

@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

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 bigint
FieldElement.toBigInt(encoded)


// converts the field element to hex
FieldElement.toHex(encoded)


// encodes the bigint into a field element
FieldElement.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);
}