Help us shape the future of Go! Take the 2026 Go Developer Survey

onchain

package
v0.0.8 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2026 License: AGPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package onchain executes verified, journaled EVM transaction templates.

Index

Constants

View Source 
const PrivyKernelImplementation = "0xd6CEDDe84be40893d153Be9d467CD6aD37875b28"

Privy's wallet_sendCalls delegates an EOA to this Kernel implementation. Kernel implementation used for Privy's EIP-7702 wallet delegation.

Variables

View Source 
var ErrBalance = errors.New("INSUFFICIENT_BALANCE")
View Source 
var ErrBatchUnavailable = errors.New("BATCH_UNAVAILABLE: EIP-7702 or deployed delegate unavailable")
View Source 
var ErrGas = errors.New("INSUFFICIENT_GAS")
View Source 
var ErrNoFill = errors.New("receipts show no fill to the recipient")

ErrNoFill reports receipts that do not show what the recipient received.

View Source 
var ErrNoRPC = errors.New("no RPC endpoint for chain")

ErrNoRPC reports a chain with no configured endpoint.

View Source 
var ErrNonceBeforeBlock = errors.New("nonce used before the batch was submitted")

ErrNonceBeforeBlock reports that a nonce was consumed before the batch's recorded start block, so that transaction cannot be the batch.

View Source 
var ErrNotBroadcast = errors.New("not broadcast")

ErrNotBroadcast wraps failures that provably happened before the current step was handed to Privy. Combined with the journal state it tells callers whether nothing (state "failed", no hashes) or only earlier, confirmed steps reached the chain.

View Source 
var ErrReceiptUpstream = errors.New("receipt lookup failed after broadcast; run status to retry")
View Source 
var ErrReverted = errors.New("transaction reverted")
View Source 
var ErrUnknown = errors.New("OUTCOME_UNKNOWN: reconcile transaction receipt; never resubmit")

Functions

func Allowed 

func Allowed(id uint64) bool

Allowed reports whether id is a plausible EVM chain ID. Real support is decided by the backend (active swap markets) and by RPCURL; every RPC response is also checked against eth_chainId.

func BatchAllowed 

func BatchAllowed(ctx context.Context, rpc codeReader, chain uint64, agent string) (bool, error)

BatchAllowed fails closed on RPC errors and checks the actual delegate code, including an already-delegated agent's target rather than assuming Kernel.

func BatchMatches 

func BatchMatches(in journal.OnchainIntent, tx *ChainTx) bool

BatchMatches reports whether an on-chain transaction is exactly the agent's batch: a zero-value self-call to execute(batch mode, abi.encode(Execution[])) whose decoded calls equal the journaled templates in order (target, value, calldata) with nothing extra.

func Hex 

func Hex(v *big.Int) string

func IsBatchNotMined 

func IsBatchNotMined(err error) bool

IsBatchNotMined reports a lookup that found no matching mined batch yet.

func LocateBatch 

func LocateBatch(ctx context.Context, in journal.OnchainIntent, b journal.Batch, locator BatchLocator) (string, error)

LocateBatch returns the hash of the mined agent transaction carrying the intent's batch, searching from the reserved nonce. errBatchNotMined means no matching transaction is mined yet; any other error is a lookup failure or a mismatch, both of which must leave the intent unresolved.

func Quantity 

func Quantity(s string) (*big.Int, error)

func RPCURL 

func RPCURL(getenv func(string) string, chain uint64) (string, error)

RPCURL requires OKU_RPC_URL_<CHAINID>. The chain-config networks package does not publish RPC endpoints.

func ReceiptWait 

func ReceiptWait(chain uint64, getenv func(string) string) time.Duration

ReceiptWait bounds how long submit waits for a receipt to reach the chain's confirmation depth: inclusion plus depth blocks with a 2x margin, at least two minutes.

func ValidAddress 

func ValidAddress(a string) bool

Types

type BatchLocator 

type BatchLocator interface {
	Nonces(ctx context.Context, chain uint64, sender string) (latest, pending uint64, err error)
	BlockNumber(ctx context.Context, chain uint64) (uint64, error)
	FindNonceTx(ctx context.Context, chain uint64, sender string, nonce, fromBlock uint64) (*ChainTx, error)
}

BatchLocator finds the agent's transaction at a nonce on chain.

type BatchSender 

type BatchSender interface {
	SendCalls(context.Context, string, uint64, []privy.Call) (string, error)
}

BatchSender submits an atomic wallet_sendCalls batch and returns Privy's transaction ID.

type ChainTx 

type ChainTx struct {
	Hash, From, To, Input, Value string
	Nonce                        uint64
}

ChainTx is the subset of an on-chain transaction used to verify a batch.

type Executor 

type Executor struct {
	// Getenv reads confirmation overrides when sizing receipt waits.
	Getenv   func(string) string
	RPC      RPC
	Sender   Sender
	Journal  Journal
	WalletID string
	Poll     time.Duration
}

func (Executor) Execute 

func (x Executor) Execute(ctx context.Context, in journal.OnchainIntent) error

Execute sends ordered already-verified templates, never retrying an ambiguous broadcast. Each hash is durably appended before the first receipt read. Every failure before a step is handed to Privy closes the intent as failed and is wrapped in ErrNotBroadcast; after a handoff, ambiguity stays unknown.

func (Executor) ExecuteBatch 

func (x Executor) ExecuteBatch(ctx context.Context, in journal.OnchainIntent, sender BatchSender, locator BatchLocator) error

ExecuteBatch sends every template as one atomic wallet_sendCalls batch (EIP-7702). Before the handoff it records the agent nonce and block, so the batch can be found on chain later; Privy returns no chain hash. Failures before the handoff close the intent (ErrNotBroadcast); afterwards the batch is located by nonce, its calldata is checked to contain every journaled call, and its receipt decides confirmed or failed.

func (Executor) ExecuteSequential 

func (x Executor) ExecuteSequential(ctx context.Context, in journal.OnchainIntent, start int) error

ExecuteSequential resumes only at a durably recorded boundary. A sending record with no confirmed cursor must not be replayed after a crash.

func (Executor) Wait 

func (x Executor) Wait(ctx context.Context, chain uint64, hash string) (bool, error)

func (Executor) WaitBatch 

func (x Executor) WaitBatch(ctx context.Context, in journal.OnchainIntent, b journal.Batch, locator BatchLocator) (string, error)

WaitBatch polls until the agent's batch transaction is mined and returns its hash. It never treats absence as failure.

type HTTPRPC 

type HTTPRPC struct {
	Client *http.Client
	Getenv func(string) string
}

HTTPRPC uses public chain endpoints unless OKU_RPC_URL_<CHAINID> overrides.

func (HTTPRPC) Balance 

func (r HTTPRPC) Balance(ctx context.Context, c uint64, a string) (*big.Int, error)

func (HTTPRPC) BlockNumber 

func (r HTTPRPC) BlockNumber(ctx context.Context, c uint64) (uint64, error)

BlockNumber returns the latest block number.

func (HTTPRPC) Call 

func (r HTTPRPC) Call(ctx context.Context, c uint64, to, data string) (*big.Int, error)

func (HTTPRPC) Code 

func (r HTTPRPC) Code(ctx context.Context, c uint64, address string) (string, error)

func (HTTPRPC) Estimate 

func (r HTTPRPC) Estimate(ctx context.Context, c uint64, from string, templates []journal.OnchainTemplate) (*big.Int, error)

func (HTTPRPC) FindNonceTx 

func (r HTTPRPC) FindNonceTx(ctx context.Context, c uint64, sender string, nonce, fromBlock uint64) (*ChainTx, error)

FindNonceTx returns sender's mined transaction with the given nonce, found by binary-searching the block where the account nonce passed it (from fromBlock). It returns nil when that nonce is not mined yet. Requires an RPC that serves historical account state for the searched range.

func (HTTPRPC) FullReceipt 

func (r HTTPRPC) FullReceipt(ctx context.Context, c uint64, hash string) (*TxReceipt, error)

FullReceipt returns the receipt of hash with its logs, nil if not mined.

func (HTTPRPC) GasPrice 

func (r HTTPRPC) GasPrice(ctx context.Context, c uint64) (*big.Int, error)

func (HTTPRPC) HasBaseFee 

func (r HTTPRPC) HasBaseFee(ctx context.Context, c uint64) (bool, error)

func (HTTPRPC) HasCode 

func (r HTTPRPC) HasCode(ctx context.Context, c uint64, address string) (bool, error)

HasCode reports whether address has deployed contract code.

func (HTTPRPC) Nonces 

func (r HTTPRPC) Nonces(ctx context.Context, c uint64, sender string) (uint64, uint64, error)

Nonces returns the agent's confirmed and pending transaction counts.

func (HTTPRPC) Receipt 

func (r HTTPRPC) Receipt(ctx context.Context, c uint64, hash string) (*bool, error)

func (HTTPRPC) TokenBalances 

func (r HTTPRPC) TokenBalances(ctx context.Context, chain uint64, wallet string, tokens []string) ([]*big.Int, error)

func (HTTPRPC) TokenDetails 

func (r HTTPRPC) TokenDetails(ctx context.Context, chain uint64, wallet string, tokens []string) ([]TokenMetadata, error)

func (HTTPRPC) VerifyBatchTransaction 

func (r HTTPRPC) VerifyBatchTransaction(ctx context.Context, in journal.OnchainIntent, b journal.Batch, hash string) error

VerifyBatchTransaction checks a user-supplied hash is the intent's batch.

func (HTTPRPC) VerifyTransaction 

func (r HTTPRPC) VerifyTransaction(ctx context.Context, chain uint64, hash, sender string, t journal.OnchainTemplate) error

VerifyTransaction rejects hashes that do not identify the exact journaled call.

type Journal 

type Journal interface {
	AdvanceOnchain(id, from, to, hash string) error
	SetOnchainBatch(id, state string, b journal.Batch) error
}

type Log 

type Log struct {
	Address string   `json:"address"`
	Topics  []string `json:"topics"`
	Data    string   `json:"data"`
}

Log is one receipt event.

type RPC 

type RPC interface {
	Balance(context.Context, uint64, string) (*big.Int, error)
	Call(context.Context, uint64, string, string) (*big.Int, error)
	GasPrice(context.Context, uint64) (*big.Int, error)
	Receipt(context.Context, uint64, string) (*bool, error)
}

RPC is the chain-read boundary. A missing receipt returns nil without error.

type Sender 

type Sender interface {
	SendTransaction(context.Context, string, privy.Transaction) (string, error)
}

type SwapFill 

type SwapFill struct {
	Received *big.Int
	Gas      *big.Int
	// Source is transfer_logs (ERC-20 Transfer events to the recipient) or
	// router_event (OkuRouter's amountOut, used for native output).
	Source string
}

SwapFill is what a swap's receipts show the recipient received.

func MeasureSwapFill 

func MeasureSwapFill(receipts []*TxReceipt, router, outToken, recipient string, native bool) (*SwapFill, error)

MeasureSwapFill reads the amount of outToken ("native" or an address) that recipient received from every successful receipt of a swap, and the total gas paid. router is the chain's OkuRouter.

type TokenMetadata 

type TokenMetadata struct {
	Address  string
	Symbol   string
	Decimals int
	Balance  *big.Int
}

type TxReceipt 

type TxReceipt struct {
	TransactionHash   string `json:"transactionHash"`
	Status            string `json:"status"`
	GasUsed           string `json:"gasUsed"`
	EffectiveGasPrice string `json:"effectiveGasPrice"`
	// L1Fee is the separately charged data fee of OP Stack chains.
	L1Fee string `json:"l1Fee"`
	Logs  []Log  `json:"logs"`
}

TxReceipt is the subset of a transaction receipt used to measure a fill.

func (*TxReceipt) Gas 

func (t *TxReceipt) Gas() (*big.Int, error)

Gas returns the native wei the transaction paid.

Source Files

View all Source files

Directories

Path Synopsis
Package onchaintest provides test helpers for onchain batch fixtures.
 Package onchaintest provides test helpers for onchain batch fixtures.

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.