rpcv01

package
v0.0.0-...-00a565c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2023 License: MIT Imports: 9 Imported by: 0

README

RPC implementation

Caigo RPC implementation provides the RPC API to perform operations with StarkNet. It is currently being tested and maintained up-to-date with Pathfinder and relies on go-ethereum to provide the JSON RPC 2.0 client implementation.

If you need Caigo to support another API, open an issue on the project.

Testing the RPC API

To test the RPC API, you should simply go the the rpc directory and run go test like below:

cd rpc
go test -v .

We provide an additional -env flag to go test so that you can choose the environment you want to test. For instance, if you plan to test with the testnet, run:

cd rpc
go test -env testnet -v .

Supported environments are mock, testnet and mainnet. The support for devnet is planned but might require some dedicated condition since it is empty.

If you plan to specify an alternative URL to test the environment, you can set the INTEGRATION_BASE environment variable. In addition, tests load .env.${env}, and .env before relying on the environment variable. So for instanve if you want the URL to change only for the testnet environment, you could add the line below in .env.testnet:

INTEGRATION_BASE=http://localhost:9546

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidBlockID = errors.New("invalid blockid")
View Source 
var ErrNotImplemented = errors.New("not implemented")

Functions

This section is empty.

Types

type AddDeclareTransactionOutput 

type AddDeclareTransactionOutput struct {
	TransactionHash string `json:"transaction_hash"`
	ClassHash       string `json:"class_hash"`
}

AddDeclareTransactionOutput provides the output for AddDeclareTransaction.

type AddDeployTransactionOutput 

type AddDeployTransactionOutput struct {
	TransactionHash string `json:"transaction_hash"`
	ContractAddress string `json:"contract_address"`
}

AddDeployTransactionOutput provides the output for AddDeployTransaction.

type Block 

type Block struct {
	BlockHeader
	Status BlockStatus `json:"status"`
	// Transactions The hashes of the transactions included in this block
	Transactions Transactions `json:"transactions"`
}

type BlockHashAndNumberOutput 

type BlockHashAndNumberOutput struct {
	BlockNumber uint64 `json:"block_number,omitempty"`
	BlockHash   string `json:"block_hash,omitempty"`
}

BlockHashAndNumberOutput is a struct that is returned by BlockHashAndNumber.

type BlockHeader 

type BlockHeader struct {
	// BlockHash The hash of this block
	BlockHash types.Hash `json:"block_hash"`
	// ParentHash The hash of this block's parent
	ParentHash types.Hash `json:"parent_hash"`
	// BlockNumber the block number (its height)
	BlockNumber uint64 `json:"block_number"`
	// NewRoot The new global state root
	NewRoot string `json:"new_root"`
	// Timestamp the time in which the block was created, encoded in Unix time
	Timestamp uint64 `json:"timestamp"`
	// SequencerAddress the StarkNet identity of the sequencer submitting this block
	SequencerAddress string `json:"sequencer_address"`
}

type BlockID 

type BlockID struct {
	Number *uint64     `json:"block_number,omitempty"`
	Hash   *types.Hash `json:"block_hash,omitempty"`
	Tag    string      `json:"block_tag,omitempty"`
}

BlockID is a struct that is used to choose between different search types.

func WithBlockHash 

func WithBlockHash(h ctypes.Hash) BlockID

func WithBlockNumber 

func WithBlockNumber(n uint64) BlockID

func WithBlockTag 

func WithBlockTag(tag string) BlockID

func (BlockID) MarshalJSON 

func (b BlockID) MarshalJSON() ([]byte, error)

type BlockStatus 

type BlockStatus string
const (
	BlockStatus_Pending      BlockStatus = "PENDING"
	BlockStatus_AcceptedOnL2 BlockStatus = "ACCEPTED_ON_L2"
	BlockStatus_AcceptedOnL1 BlockStatus = "ACCEPTED_ON_L1"
	BlockStatus_Rejected     BlockStatus = "REJECTED"
)

func (BlockStatus) MarshalJSON 

func (bs BlockStatus) MarshalJSON() ([]byte, error)

func (*BlockStatus) UnmarshalJSON 

func (bs *BlockStatus) UnmarshalJSON(data []byte) error

type CommonTransaction 

type CommonTransaction struct {
	TransactionHash types.Hash      `json:"transaction_hash,omitempty"`
	Type            TransactionType `json:"type,omitempty"`
	// MaxFee maximal fee that can be charged for including the transaction
	MaxFee string `json:"max_fee,omitempty"`
	// Version of the transaction scheme
	Version types.NumAsHex `json:"version"`
	// Signature
	Signature []string `json:"signature,omitempty"`
	// Nonce
	Nonce string `json:"nonce,omitempty"`
}

type CommonTransactionReceipt 

type CommonTransactionReceipt struct {
	TransactionHash types.Hash `json:"transaction_hash"`
	// ActualFee The fee that was charged by the sequencer
	ActualFee   string                 `json:"actual_fee"`
	Status      types.TransactionState `json:"status"`
	BlockHash   types.Hash             `json:"block_hash"`
	BlockNumber uint64                 `json:"block_number"`
	Type        TransactionType        `json:"type,omitempty"`
}

func (CommonTransactionReceipt) Hash 

func (tr CommonTransactionReceipt) Hash() types.Hash

type ContractNonce 

type ContractNonce struct {
	// ContractAddress is the address of the contract
	ContractAddress types.Hash `json:"contract_address"`
	// Nonce is the nonce for the given address at the end of the block"
	Nonce string `json:"nonce"`
}

ContractNonce is a the updated nonce per contract address

type ContractStorageDiffItem 

type ContractStorageDiffItem struct {
	// ContractAddress is the contract address for which the state changed
	Address string `json:"address"`

	// Key returns the key of the changed value
	Key string `json:"key"`
	// Value is the new value applied to the given address
	Value string `json:"value"`
}

ContractStorageDiffItem is a change in a single storage item

type DeclareTransactionReceipt 

type DeclareTransactionReceipt struct {
	CommonTransactionReceipt
}

DeclareTransactionReceipt Declare Transaction Receipt

type DeclareTxn 

type DeclareTxn struct {
	CommonTransaction

	// ClassHash the hash of the declared class
	ClassHash string `json:"class_hash"`

	// SenderAddress the address of the account contract sending the declaration transaction
	SenderAddress string `json:"sender_address"`
}

func (DeclareTxn) Hash 

func (tx DeclareTxn) Hash() types.Hash

type DeclaredContractItem 

type DeclaredContractItem struct {
	// ClassHash the hash of the contract code
	ClassHash string `json:"class_hash"`
}

DeclaredContractItem A new contract declared as part of the new state

type DeployAccountTxn 

type DeployAccountTxn struct {
	CommonTransaction
	// ClassHash The hash of the deployed contract's class
	ClassHash string `json:"class_hash"`

	// ContractAddressSalt The salt for the address of the deployed contract
	ContractAddressSalt string `json:"contract_address_salt"`

	// ConstructorCalldata The parameters passed to the constructor
	ConstructorCalldata []string `json:"constructor_calldata"`
}

DeployTxn The structure of a deploy transaction. Note that this transaction type is deprecated and will no longer be supported in future versions

func (DeployAccountTxn) Hash 

func (tx DeployAccountTxn) Hash() types.Hash

type DeployTransactionReceipt 

type DeployTransactionReceipt struct {
	CommonTransactionReceipt
	// ContractAddress The address of the deployed contract
	ContractAddress string `json:"contract_address"`
}

DeployTransactionReceipt Deploy Transaction Receipt

type DeployTxn 

type DeployTxn struct {
	CommonTransaction
	// ClassHash The hash of the deployed contract's class
	ClassHash string `json:"class_hash"`

	// ContractAddress The address of the deployed contract
	ContractAddress string `json:"contract_address"`

	// ContractAddressSalt The salt for the address of the deployed contract
	ContractAddressSalt string `json:"contract_address_salt"`

	// ConstructorCalldata The parameters passed to the constructor
	ConstructorCalldata []string `json:"constructor_calldata"`
}

DeployTxn The structure of a deploy transaction. Note that this transaction type is deprecated and will no longer be supported in future versions

func (DeployTxn) Hash 

func (tx DeployTxn) Hash() types.Hash

type DeployedContractItem 

type DeployedContractItem struct {
	// ContractAddress is the address of the contract
	Address string `json:"address"`
	// ClassHash is the hash of the contract code
	ClassHash string `json:"class_hash"`
}

DeployedContractItem A new contract deployed as part of the new state

type EmittedEvent 

type EmittedEvent struct {
	Event
	BlockHash       types.Hash `json:"block_hash"`
	BlockNumber     uint64     `json:"block_number"`
	TransactionHash types.Hash `json:"transaction_hash"`
}

type Event 

type Event struct {
	FromAddress types.Hash `json:"from_address"`
	Keys        []string   `json:"keys"`
	Data        []string   `json:"data"`
}

type EventFilter 

type EventFilter struct {
	FromBlock BlockID    `json:"from_block"`
	ToBlock   BlockID    `json:"to_block,omitempty"`
	Address   types.Hash `json:"address,omitempty"`
	// Keys the values used to filter the events
	Keys []string `json:"keys,omitempty"`

	PageSize   uint64 `json:"page_size,omitempty"`
	PageNumber uint64 `json:"page_number"`
}

type EventsOutput 

type EventsOutput struct {
	Events     []EmittedEvent `json:"events"`
	PageNumber uint64         `json:"page_number"`
	IsLastPage bool           `json:"is_last_page"`
}

type InvokeTransactionReceipt 

type InvokeTransactionReceipt struct {
	CommonTransactionReceipt
	// ActualFee The fee that was charged by the sequencer
	InvokeTransactionReceiptProperties `json:",omitempty"`
}

InvokeTransactionReceipt Invoke Transaction Receipt

type InvokeTransactionReceiptProperties 

type InvokeTransactionReceiptProperties struct {
	MessageSent []MsgToL1 `json:"messages_sent,omitempty"`
	// A list of events assocuated with the Invoke Transaction
	Events []Event `json:"events,omitempty"`
}

type InvokeTxn 

type InvokeTxn interface{}

type InvokeTxnDuck 

type InvokeTxnDuck struct {
	AccountAddress     types.Hash `json:"account_address"`
	ContractAddress    types.Hash `json:"contract_address"`
	EntryPointSelector string     `json:"entry_point_selector"`
}

InvokeTxnDuck is a type used to understand the Invoke Version

type InvokeTxnV0 

type InvokeTxnV0 struct {
	CommonTransaction
	ContractAddress    types.Hash `json:"contract_address"`
	EntryPointSelector string     `json:"entry_point_selector"`

	// Calldata The parameters passed to the function
	Calldata []string `json:"calldata"`
}

func (InvokeTxnV0) Hash 

func (tx InvokeTxnV0) Hash() types.Hash

type InvokeTxnV1 

type InvokeTxnV1 struct {
	CommonTransaction
	InvokeV1
}

func (InvokeTxnV1) Hash 

func (tx InvokeTxnV1) Hash() types.Hash

type InvokeV0 

type InvokeV0 types.FunctionCall

InvokeV0 version 0 invoke transaction

type InvokeV1 

type InvokeV1 struct {
	SenderAddress types.Hash `json:"sender_address"`
	// Calldata The parameters passed to the function
	Calldata []string `json:"calldata"`
}

InvokeV1 version 1 invoke transaction

type L1HandlerTransactionReceipt 

type L1HandlerTransactionReceipt struct {
	CommonTransactionReceipt
}

L1HandlerTransactionReceipt L1 Handler Transaction Receipt

type L1HandlerTxn 

type L1HandlerTxn struct {
	TransactionHash types.Hash      `json:"transaction_hash,omitempty"`
	Type            TransactionType `json:"type,omitempty"`
	// Version of the transaction scheme
	Version types.NumAsHex `json:"version"`
	// Nonce
	Nonce string `json:"nonce,omitempty"`
	// MaxFee maximal fee that can be charged for including the transaction
	MaxFee string `json:"max_fee,omitempty"`
	// Signature
	Signature          []string   `json:"signature,omitempty"`
	ContractAddress    types.Hash `json:"contract_address"`
	EntryPointSelector string     `json:"entry_point_selector"`

	// Calldata The parameters passed to the function
	Calldata []string `json:"calldata"`
}

func (L1HandlerTxn) Hash 

func (tx L1HandlerTxn) Hash() types.Hash

type MsgToL1 

type MsgToL1 struct {
	// ToAddress The target L1 address the message is sent to
	ToAddress string `json:"to_address"`
	//Payload  The payload of the message
	Payload []string `json:"payload"`
}

type Provider 

type Provider struct {
	// contains filtered or unexported fields
}

Provider provides the provider for caigo/rpc implementation.

func NewProvider 

func NewProvider(c *rpc.Client) *Provider

NewProvider creates a *Provider from an existing `go-ethereum/rpc` *Client.

func (*Provider) AddDeclareTransaction 

func (provider *Provider) AddDeclareTransaction(ctx context.Context, contractClass ctypes.ContractClass, version string) (*AddDeclareTransactionOutput, error)

AddDeclareTransaction submits a new class declaration transaction.

func (*Provider) AddDeployTransaction 

func (provider *Provider) AddDeployTransaction(ctx context.Context, salt string, inputs []string, contractClass ctypes.ContractClass) (*AddDeployTransactionOutput, error)

AddDeployTransaction allows to declare a class and instantiate the associated contract in one command. This function will be deprecated and replaced by AddDeclareTransaction to declare a class, followed by AddInvokeTransaction to instantiate the contract. For now, it remains the only way to deploy an account without being charged for it.

func (*Provider) AddInvokeTransaction 

func (provider *Provider) AddInvokeTransaction(ctx context.Context, call ctypes.FunctionCall, signature []string, maxFee string, version string, nonce *big.Int) (*ctypes.AddInvokeTransactionOutput, error)

AddInvokeTransaction estimates the fee for a given StarkNet transaction.

func (*Provider) BlockHashAndNumber 

func (provider *Provider) BlockHashAndNumber(ctx context.Context) (*BlockHashAndNumberOutput, error)

BlockHashAndNumber gets block information given the block number or its hash.

func (*Provider) BlockNumber 

func (provider *Provider) BlockNumber(ctx context.Context) (uint64, error)

BlockNumber gets the most recent accepted block number.

func (*Provider) BlockTransactionCount 

func (provider *Provider) BlockTransactionCount(ctx context.Context, blockID BlockID) (uint64, error)

BlockTransactionCount gets the number of transactions in a block

func (*Provider) BlockWithTxHashes 

func (provider *Provider) BlockWithTxHashes(ctx context.Context, blockID BlockID) (Block, error)

BlockWithTxHashes gets block information given the block id.

func (*Provider) BlockWithTxs 

func (provider *Provider) BlockWithTxs(ctx context.Context, blockID BlockID) (interface{}, error)

BlockWithTxs get block information with full transactions given the block id.

func (*Provider) Call 

func (provider *Provider) Call(ctx context.Context, call ctypes.FunctionCall, block BlockID) ([]string, error)

Call a starknet function without creating a StarkNet transaction.

func (*Provider) ChainID 

func (provider *Provider) ChainID(ctx context.Context) (string, error)

ChainID retrieves the current chain ID for transaction replay protection.

func (*Provider) Class 

func (provider *Provider) Class(ctx context.Context, classHash string) (*types.ContractClass, error)

Class gets the contract class definition associated with the given hash.

func (*Provider) ClassAt 

func (provider *Provider) ClassAt(ctx context.Context, blockID BlockID, contractAddress types.Hash) (*types.ContractClass, error)

ClassAt get the contract class definition at the given address.

func (*Provider) ClassHashAt 

func (provider *Provider) ClassHashAt(ctx context.Context, blockID BlockID, contractAddress types.Hash) (*string, error)

ClassHashAt gets the contract class hash for the contract deployed at the given address.

func (*Provider) EstimateFee 

func (provider *Provider) EstimateFee(ctx context.Context, request types.FunctionInvoke, blockID BlockID) (*types.FeeEstimate, error)

EstimateFee estimates the fee for a given StarkNet transaction.

func (*Provider) Events 

func (provider *Provider) Events(ctx context.Context, filter EventFilter) (*EventsOutput, error)

Events returns all events matching the given filter

func (*Provider) Nonce 

func (provider *Provider) Nonce(ctx context.Context, contractAddress types.Hash) (*string, error)

Nonce returns the Nonce of a contract

func (*Provider) StateUpdate 

func (provider *Provider) StateUpdate(ctx context.Context, blockID BlockID) (*StateUpdateOutput, error)

StateUpdate gets the information about the result of executing the requested block.

func (*Provider) StorageAt 

func (provider *Provider) StorageAt(ctx context.Context, contractAddress types.Hash, key string, blockID BlockID) (string, error)

StorageAt gets the value of the storage at the given address and key.

func (*Provider) Syncing 

func (provider *Provider) Syncing(ctx context.Context) (*SyncResponse, error)

Syncing checks the syncing status of the node.

func (*Provider) TraceBlockTransactions 

func (provider *Provider) TraceBlockTransactions(ctx context.Context, hash string) error

not implemented for testing yet

func (*Provider) TransactionByBlockIdAndIndex 

func (provider *Provider) TransactionByBlockIdAndIndex(ctx context.Context, blockID BlockID, index uint64) (Transaction, error)

TransactionByBlockIdAndIndex Get the details of the transaction given by the identified block and index in that block. If no transaction is found, null is returned.

func (*Provider) TransactionByHash 

func (provider *Provider) TransactionByHash(ctx context.Context, hash types.Hash) (Transaction, error)

TransactionByHash gets the details and status of a submitted transaction.

func (*Provider) TransactionReceipt 

func (provider *Provider) TransactionReceipt(ctx context.Context, transactionHash types.Hash) (TransactionReceipt, error)

TxnReceipt gets the transaction receipt by the transaction hash.

func (*Provider) TransactionTrace 

func (provider *Provider) TransactionTrace(ctx context.Context, hash string) error

not implemented for testing yet

func (*Provider) WaitForTransaction 

func (provider *Provider) WaitForTransaction(ctx context.Context, transactionHash types.Hash, pollInterval time.Duration) (types.TransactionState, error)

WaitForTransaction waits for the transaction to succeed or fail

type StateDiff 

type StateDiff struct {
	// StorageDiffs list storage changes
	StorageDiffs []ContractStorageDiffItem `json:"storage_diffs"`
	// Contracts list new contracts added as part of the new state
	DeclaredContracts []DeclaredContractItem `json:"declared_contracts"`
	// Nonces provides the updated nonces per contract addresses
	DeployedContracts []DeployedContractItem `json:"deployed_contracts"`
	// Nonces provides the updated nonces per contract addresses
	Nonces []ContractNonce `json:"nonces"`
}

StateDiff is the change in state applied in this block, given as a mapping of addresses to the new values and/or new contracts.

type StateUpdateOutput 

type StateUpdateOutput struct {
	// BlockHash is the block identifier,
	BlockHash types.Hash `json:"block_hash"`
	// NewRoot is the new global state root.
	NewRoot string `json:"new_root"`
	// OldRoot is the previous global state root.
	OldRoot string `json:"old_root"`
	// AcceptedTime is when the block was accepted on L1.
	AcceptedTime int `json:"accepted_time,omitempty"`
	// StateDiff is the change in state applied in this block, given as a
	// mapping of addresses to the new values and/or new contracts.
	StateDiff StateDiff `json:"state_diff"`
}

type StorageEntry 

type StorageEntry struct {
}

StorageEntry The changes in the storage of the contract

type SyncResponse 

type SyncResponse struct {
	StartingBlockHash string `json:"starting_block_hash"`
	StartingBlockNum  string `json:"starting_block_num"`
	CurrentBlockHash  string `json:"current_block_hash"`
	CurrentBlockNum   string `json:"current_block_num"`
	HighestBlockHash  string `json:"highest_block_hash"`
	HighestBlockNum   string `json:"highest_block_num"`
}

SyncResponse is the Starknet RPC type returned by the Syncing method.

type Transaction 

type Transaction interface {
	Hash() types.Hash
}

type TransactionHash 

type TransactionHash struct {
	TransactionHash types.Hash `json:"transaction_hash"`
}

func (TransactionHash) Hash 

func (tx TransactionHash) Hash() types.Hash

func (TransactionHash) MarshalJSON 

func (tx TransactionHash) MarshalJSON() ([]byte, error)

func (*TransactionHash) UnmarshalJSON 

func (tx *TransactionHash) UnmarshalJSON(input []byte) error

type TransactionReceipt 

type TransactionReceipt interface {
	Hash() types.Hash
}

type TransactionType 

type TransactionType string
const (
	TransactionType_Declare       TransactionType = "DECLARE"
	TransactionType_Deploy        TransactionType = "DEPLOY"
	TransactionType_DeployAccount TransactionType = "DEPLOY_ACCOUNT"
	TransactionType_Invoke        TransactionType = "INVOKE"
	TransactionType_L1Handler     TransactionType = "L1_HANDLER"
)

func (TransactionType) MarshalJSON 

func (tt TransactionType) MarshalJSON() ([]byte, error)

func (*TransactionType) UnmarshalJSON 

func (tt *TransactionType) UnmarshalJSON(data []byte) error

type Transactions 

type Transactions []Transaction

func (*Transactions) UnmarshalJSON 

func (txns *Transactions) UnmarshalJSON(data []byte) error

type UnknownTransaction 

type UnknownTransaction struct{ Transaction }

func (*UnknownTransaction) UnmarshalJSON 

func (txn *UnknownTransaction) UnmarshalJSON(data []byte) error

type UnknownTransactionReceipt 

type UnknownTransactionReceipt struct{ TransactionReceipt }

func (*UnknownTransactionReceipt) UnmarshalJSON 

func (tr *UnknownTransactionReceipt) UnmarshalJSON(data []byte) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.