caigo

package module
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: 17 Imported by: 1

README

Golang Library for StarkNet

Go Reference test

Caigo is an MIT-licensed Go library for interacting with StarkNet.

Getting Started

Run Examples

starkcurve

cd examples/curve
go mod tidy
go run main.go

starknet contract

cd examples/contract
go mod tidy
go run main.go

starknet account

cd examples/account
go mod tidy
go run main.go

RPC

Caigo RPC implements the StarkNet RPC Spec:

Method Implemented (*)
starknet_getBlockByHash ✔
starknet_getBlockByNumber ✔
starknet_getTransactionByHash ✔
starknet_getTransactionReceipt ✔
starknet_getClass ✔
starknet_getClassHashAt ✔
starknet_getClassAt ✔
starknet_call ✔
starknet_blockNumber ✔
starknet_chainId ✔
starknet_syncing ✔
starknet_getEvents ✔
starknet_addInvokeTransaction ✔
starknet_addDeployTransaction ✔
starknet_addDeclareTransaction ✔
starknet_estimateFee ✔
starknet_getBlockTransactionCountByHash ✔
starknet_getBlockTransactionCountByNumber ✔
starknet_getTransactionByBlockNumberAndIndex ✔
starknet_getTransactionByBlockHashAndIndex ✔
starknet_getStorageAt ✔
starknet_getNonce ✔
starknet_getStateUpdate ✔
*starknet_traceBlockTransactions ❌
*starknet_traceTransaction ❌

(*) some methods are not implemented because they are not yet available from eqlabs/pathfinder.

Run Tests

go test -v ./...

Run RPC Tests

go test -v ./rpc -env [mainnet|devnet|testnet|mock]

Run Benchmarks

go test -bench=.

Compatibility and stability

Caigo is currently under active development and will under go breaking changes until the initial stable(v1.0.0) release. The example directories and *_test.go files should always be applicable for the latest commitment on the main branch. NOTE: examples and tests may be out of sync with tagged versions and pkg.go.dev documentation

Issues

If you find an issue/bug or have a feature request please submit an issue here Issues

Contributing

If you are looking to contribute, please head to the Contributing section.

Documentation

Index

Constants

View Source 
const (
	TRANSACTION_PREFIX      = "invoke"
	EXECUTE_SELECTOR        = "__execute__"
	CONTRACT_ADDRESS_PREFIX = "STARKNET_CONTRACT_ADDRESS"
)

Variables

View Source 
var (
	ErrUnsupportedAccount = errors.New("unsupported account implementation")
	MAX_FEE, _            = big.NewInt(0).SetString("0x20000000000", 0)
)
View Source 
var PedersenParamsRaw []byte

Functions

func DivMod 

func DivMod(n, m, p *big.Int) *big.Int

Finds a nonnegative integer 0 <= x < p such that (m * x) % p == n

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/math_utils.py)

func FmtKecBytes 

func FmtKecBytes(in *big.Int, rolen int) (buf []byte)

format the bytes in Keccak hash

func MaskBits 

func MaskBits(mask, wordSize int, slice []byte) (ret []byte)

mask excess bits

func MerkleHash 

func MerkleHash(x, y *big.Int) (*big.Int, error)

func ProofMerklePath 

func ProofMerklePath(root *big.Int, leaf *big.Int, path []*big.Int) bool

Types

type Account 

type Account struct {
	AccountAddress string
	// contains filtered or unexported fields
}

func NewGatewayAccount 

func NewGatewayAccount(private, address string, provider *gateway.GatewayProvider, options ...AccountOptionFunc) (*Account, error)

func NewRPCAccount 

func NewRPCAccount[Provider *rpcv01.Provider | *rpcv02.Provider](private, address string, provider Provider, options ...AccountOptionFunc) (*Account, error)

func (*Account) Call 

func (account *Account) Call(ctx context.Context, call types.FunctionCall) ([]string, error)

func (*Account) EstimateFee 

func (account *Account) EstimateFee(ctx context.Context, calls []types.FunctionCall, details types.ExecuteDetails) (*types.FeeEstimate, error)

func (*Account) Execute 

func (account *Account) Execute(ctx context.Context, calls []types.FunctionCall, details types.ExecuteDetails) (*types.AddInvokeTransactionOutput, error)

func (*Account) Nonce 

func (account *Account) Nonce(ctx context.Context) (*big.Int, error)

func (*Account) Sign 

func (account *Account) Sign(msgHash *big.Int) (*big.Int, *big.Int, error)

func (*Account) TransactionHash 

func (account *Account) TransactionHash(calls []types.FunctionCall, details types.ExecuteDetails) (*big.Int, error)

type AccountOption 

type AccountOption struct {
	AccountPlugin AccountPlugin
	// contains filtered or unexported fields
}

func AccountVersion0 

func AccountVersion0(string, string) (AccountOption, error)

func AccountVersion1 

func AccountVersion1(string, string) (AccountOption, error)

type AccountOptionFunc 

type AccountOptionFunc func(string, string) (AccountOption, error)

type AccountPlugin 

type AccountPlugin interface {
	PluginCall(calls []types.FunctionCall) (types.FunctionCall, error)
}

type CurveOption 

type CurveOption interface {
	// contains filtered or unexported methods
}

func WithConstants 

func WithConstants(paramsPath ...string) CurveOption

functions that require pedersen hashes must be run on a curve initialized with constant points

type Definition 

type Definition struct {
	Name string
	Type string
}

type Domain 

type Domain struct {
	Name    string
	Version string
	ChainId string
}

func (Domain) FmtDefinitionEncoding 

func (dm Domain) FmtDefinitionEncoding(field string) (fmtEnc []*big.Int)

encoding definition for standard StarkNet Domain messages

type FixedSizeMerkleTree 

type FixedSizeMerkleTree struct {
	Leaves   []*big.Int
	Branches [][]*big.Int
	Root     *big.Int
}

func NewFixedSizeMerkleTree 

func NewFixedSizeMerkleTree(leaves ...*big.Int) (*FixedSizeMerkleTree, error)

func (*FixedSizeMerkleTree) Proof 

func (mt *FixedSizeMerkleTree) Proof(leaf *big.Int) ([]*big.Int, error)

type ProviderType 

type ProviderType string
const (
	ProviderRPCv01  ProviderType = "rpcv01"
	ProviderRPCv02  ProviderType = "rpcv02"
	ProviderGateway ProviderType = "gateway"
)

type StarkCurve 

type StarkCurve struct {
	*elliptic.CurveParams
	EcGenX           *big.Int
	EcGenY           *big.Int
	MinusShiftPointX *big.Int
	MinusShiftPointY *big.Int
	Max              *big.Int
	Alpha            *big.Int
	ConstantPoints   [][]*big.Int
}

Returned stark curve includes several values above and beyond what the 'elliptic' interface calls for to facilitate common starkware functions 

var Curve StarkCurve

func (StarkCurve) Add 

func (sc StarkCurve) Add(x1, y1, x2, y2 *big.Int) (x, y *big.Int)

Gets two points on an elliptic curve mod p and returns their sum. Assumes affine form (x, y) is spread (x1 *big.Int, y1 *big.Int)

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/math_utils.py)

func (StarkCurve) ComputeHashOnElements 

func (sc StarkCurve) ComputeHashOnElements(elems []*big.Int) (hash *big.Int, err error)

Hashes the contents of a given array with its size using a golang Pedersen Hash implementation.

(ref: https://github.com/starkware-libs/cairo-lang/blob/13cef109cd811474de114925ee61fd5ac84a25eb/src/starkware/cairo/common/hash_state.py#L6)

func (StarkCurve) Double 

func (sc StarkCurve) Double(x1, y1 *big.Int) (x, y *big.Int)

Doubles a point on an elliptic curve with the equation y^2 = x^3 + alpha*x + beta mod p. Assumes affine form (x, y) is spread (x1 *big.Int, y1 *big.Int)

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/math_utils.py)

func (StarkCurve) EcMult 

func (sc StarkCurve) EcMult(m, x1, y1 *big.Int) (x, y *big.Int)

Multiplies by m a point on the elliptic curve with equation y^2 = x^3 + alpha*x + beta mod p. Assumes affine form (x, y) is spread (x1 *big.Int, y1 *big.Int) and that 0 < m < order(point).

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/math_utils.py)

func (StarkCurve) GenerateSecret 

func (sc StarkCurve) GenerateSecret(msgHash, privKey, seed *big.Int) (secret *big.Int)

implementation based on https://github.com/codahale/rfc6979/blob/master/rfc6979.go for the specification, see https://tools.ietf.org/html/rfc6979#section-3.2

func (StarkCurve) GetRandomPrivateKey 

func (sc StarkCurve) GetRandomPrivateKey() (priv *big.Int, err error)

obtain random primary key on stark curve NOTE: to be used for testing purposes

func (StarkCurve) GetYCoordinate 

func (sc StarkCurve) GetYCoordinate(starkX *big.Int) *big.Int

Given the x coordinate of a stark_key, returns a possible y coordinate such that together the point (x,y) is on the curve. Note: the real y coordinate is either y or -y.

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/signature.py)

func (StarkCurve) HashElements 

func (sc StarkCurve) HashElements(elems []*big.Int) (hash *big.Int, err error)

Hashes the contents of a given array using a golang Pedersen Hash implementation.

(ref: https://github.com/seanjameshan/starknet.js/blob/main/src/utils/ellipticCurve.ts)

func (StarkCurve) InvModCurveSize 

func (sc StarkCurve) InvModCurveSize(x *big.Int) *big.Int

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/math_utils.py)

func (StarkCurve) IsOnCurve 

func (sc StarkCurve) IsOnCurve(x, y *big.Int) bool

func (StarkCurve) MimicEcMultAir 

func (sc StarkCurve) MimicEcMultAir(mout, x1, y1, x2, y2 *big.Int) (x *big.Int, y *big.Int, err error)

Computes m * point + shift_point using the same steps like the AIR and throws an exception if and only if the AIR errors.

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/signature.py)

func (StarkCurve) PedersenHash 

func (sc StarkCurve) PedersenHash(elems []*big.Int) (hash *big.Int, err error)

Provides the pedersen hash of given array of big integers. NOTE: This function assumes the curve has been initialized with contant points

(ref: https://github.com/seanjameshan/starknet.js/blob/main/src/utils/ellipticCurve.ts)

func (StarkCurve) PrivateToPoint 

func (sc StarkCurve) PrivateToPoint(privKey *big.Int) (x, y *big.Int, err error)

obtain public key coordinates from stark curve given the private key

func (StarkCurve) ScalarBaseMult 

func (sc StarkCurve) ScalarBaseMult(k []byte) (x, y *big.Int)

func (StarkCurve) ScalarMult 

func (sc StarkCurve) ScalarMult(x1, y1 *big.Int, k []byte) (x, y *big.Int)

func (StarkCurve) Sign 

func (sc StarkCurve) Sign(msgHash, privKey *big.Int, seed ...*big.Int) (x, y *big.Int, err error)

Signs the hash value of contents with the provided private key. Secret is generated using a golang implementation of RFC 6979. Implementation does not yet include "extra entropy" or "retry gen".

(ref: https://datatracker.ietf.org/doc/html/rfc6979)

func (StarkCurve) Verify 

func (sc StarkCurve) Verify(msgHash, r, s, pubX, pubY *big.Int) bool

Verifies the validity of the stark curve signature given the message hash, and public key (x, y) coordinates used to sign the message.

(ref: https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/signature.py)

type StarkCurvePayload 

type StarkCurvePayload struct {
	License        []string     `json:"_license"`
	Comment        string       `json:"_comment"`
	FieldPrime     *big.Int     `json:"FIELD_PRIME"`
	FieldGen       int          `json:"FIELD_GEN"`
	EcOrder        *big.Int     `json:"EC_ORDER"`
	Alpha          int64        `json:"ALPHA"`
	Beta           *big.Int     `json:"BETA"`
	ConstantPoints [][]*big.Int `json:"CONSTANT_POINTS"`
}

struct definition for parsing 'pedersen_params.json' 

var PedersenParams StarkCurvePayload

type TypeDef 

type TypeDef struct {
	Encoding    *big.Int
	Definitions []Definition
}

type TypedData 

type TypedData struct {
	Types       map[string]TypeDef
	PrimaryType string
	Domain      Domain
	Message     TypedMessage
}

func NewTypedData 

func NewTypedData(types map[string]TypeDef, pType string, dom Domain) (td TypedData, err error)

'typedData' interface for interacting and signing typed data in accordance with https://github.com/0xs34n/starknet.js/tree/develop/src/utils/typedData

func (TypedData) EncodeType 

func (td TypedData) EncodeType(inType string) (enc string, err error)

func (TypedData) GetMessageHash 

func (td TypedData) GetMessageHash(account *big.Int, msg TypedMessage, sc StarkCurve) (hash *big.Int, err error)

(ref: https://github.com/0xs34n/starknet.js/blob/767021a203ac0b9cdb282eb6d63b33bfd7614858/src/utils/typedData/index.ts#L166)

func (TypedData) GetTypeHash 

func (td TypedData) GetTypeHash(inType string) (ret *big.Int, err error)

func (TypedData) GetTypedMessageHash 

func (td TypedData) GetTypedMessageHash(inType string, msg TypedMessage, sc StarkCurve) (hash *big.Int, err error)

type TypedMessage 

type TypedMessage interface {
	FmtDefinitionEncoding(string) []*big.Int
}

Source Files

View all Source files

Directories

Path Synopsis
examples
contract Module
curve Module
plugins
xsessions

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.