types

Documentation

Overview

Package types holds shared SDK domain types used across service packages.

Boundary discipline:

• Only pure data types (structs, named primitives) and sentinel errors belong here.
• No business logic, no helpers, no service glue.
• Imports stay minimal and must not include service packages, because service imports from types must remain acyclic.

This package exists so every service can share the same vocabulary (WriteResult, BigInt, ...) without cross-importing each other's service package.

Stability

0.x phase: public API may change between minor releases. Contract uint256 identifiers are exposed as BigInt; field and parameter names carry the domain meaning.

Index

• Variables
• type BigInt
  • func BigIntFromBig(v *big.Int) (BigInt, error)
  • func NewBigInt(v uint64) BigInt
  • func ParseBigInt(s string) (BigInt, error)
  • func (id BigInt) Big() *big.Int
  • func (id BigInt) Bytes32() [32]byte
  • func (id BigInt) Cmp(other BigInt) int
  • func (id BigInt) Copy() BigInt
  • func (id BigInt) Equal(other BigInt) bool
  • func (id BigInt) IsZero() bool
  • func (id BigInt) MarshalJSON() ([]byte, error)
  • func (id BigInt) MarshalText() ([]byte, error)
  • func (id BigInt) String() string
  • func (id BigInt) Uint64() (uint64, bool)
  • func (id *BigInt) UnmarshalJSON(data []byte) error
  • func (id *BigInt) UnmarshalText(text []byte) error
• type ChainID
  • func (c ChainID) BigInt() *big.Int
  • func (c ChainID) Int64() int64
  • func (c ChainID) IsValid() bool
• type Epoch
• type ListOptions
  • func (o ListOptions) Validate() error
• type WriteResult

Variables

var ErrInvalidListOptions = errors.New("invalid list options")

ErrInvalidListOptions is returned when ListOptions values are out of range. It is exposed so callers can assert on the class of error without depending on a specific service package.

var ErrTxFailed = txutil.ErrTxFailed

ErrTxFailed is the canonical sentinel reported when a transaction is mined but its receipt status is not successful (reverted or out-of-gas on-chain). Use errors.Is to match errors returned by any state-changing call in the SDK.

Service packages (payments, sessionkey, ...) expose aliases to this sentinel for backward compatibility; they are all the same error value.

Types

type BigInt

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

BigInt holds a uint256 value used by on-chain identifiers.

func BigIntFromBig

func BigIntFromBig(v *big.Int) (BigInt, error)

BigIntFromBig returns a BigInt after validating that v is a uint256.

func NewBigInt

func NewBigInt(v uint64) BigInt

NewBigInt returns a BigInt from a uint64 value.

func ParseBigInt

func ParseBigInt(s string) (BigInt, error)

ParseBigInt parses a decimal uint256.

func (BigInt) Big

func (id BigInt) Big() *big.Int

Big returns a defensive copy of id.

func (BigInt) Bytes32

func (id BigInt) Bytes32() [32]byte

Bytes32 returns id as a 32-byte big-endian uint256 value.

func (BigInt) Cmp

func (id BigInt) Cmp(other BigInt) int

Cmp compares id and other.

func (BigInt) Copy

func (id BigInt) Copy() BigInt

Copy returns an independent copy of id.

func (BigInt) Equal

func (id BigInt) Equal(other BigInt) bool

Equal reports whether id and other hold the same numeric value.

func (BigInt) IsZero

func (id BigInt) IsZero() bool

IsZero reports whether id is zero.

func (BigInt) MarshalJSON

func (id BigInt) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (BigInt) MarshalText

func (id BigInt) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (BigInt) String

func (id BigInt) String() string

String returns the decimal form of id.

func (BigInt) Uint64

func (id BigInt) Uint64() (uint64, bool)

Uint64 returns id as uint64 when it fits.

func (*BigInt) UnmarshalJSON

func (id *BigInt) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*BigInt) UnmarshalText

func (id *BigInt) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type ChainID

type ChainID int64

ChainID is an EIP-155 chain identifier exposed at the SDK public boundary instead of the bare *big.Int used by go-ethereum. The newtype keeps callers honest about units (raw uint256 chain ids fit easily in int64 for every deployed EVM chain) and avoids silently accepting mutable *big.Int pointers across package boundaries.

The zero value is not a valid chain id; use IsValid to check.

func (ChainID) BigInt

func (c ChainID) BigInt() *big.Int

BigInt returns a freshly-allocated *big.Int for consumers (contract bindings, EIP-712 domain separators) that still require the legacy representation. The returned pointer is owned by the caller.

func (ChainID) Int64

func (c ChainID) Int64() int64

Int64 returns the chain id as an int64.

func (ChainID) IsValid

func (c ChainID) IsValid() bool

IsValid reports whether the chain id is a positive EIP-155 identifier.

type Epoch

type Epoch uint64

Epoch is a Filecoin chain epoch number. Zero is the valid "indefinite" sentinel in several warm-storage fields.

type ListOptions

type ListOptions struct {
	Offset uint64
	Limit  uint64
}

ListOptions configures a paginated list call.

Limit must be > 0. The zero value is rejected as a programming error: different services/contracts disagree on what "Limit == 0" means (some treat it as "all remaining", others as a default page size), so callers must be explicit.

When you want to iterate every record regardless of page size, use the service's IterateAll* method instead of trying to encode "no cap" via ListOptions.

func (ListOptions) Validate

func (o ListOptions) Validate() error

Validate returns ErrInvalidListOptions when Limit is not > 0.

type WriteResult

type WriteResult struct {
	Hash    common.Hash
	Receipt *ethtypes.Receipt
}

WriteResult is returned by every state-changing call in the SDK.

Hash is always populated when WriteResult is non-nil — it is set as soon as the transaction is broadcast. Receipt is populated only when the call was made with a wait option (e.g. WithWait(timeout)) and the transaction was mined (successfully or reverted) before the timeout elapsed.

Error semantics (observe WriteResult and err together):

• WriteResult == nil, err != nil: pre-broadcast failure (validation, signing, or broadcast itself failed). The transaction was never submitted to the chain and it is safe to retry with fresh state.
• WriteResult != nil, err == nil: transaction was broadcast successfully. Without a wait option, Receipt is nil. With a wait option, Receipt is non-nil and Status == 1 (successful execution).
• WriteResult != nil, err != nil, Receipt == nil: the wait timed out before a terminal receipt was returned, or receipt lookup failed. This includes both "not mined yet" and "already mined, but the configured confirmation count has not been satisfied yet". Hash is valid; callers can keep polling by Hash.
• WriteResult != nil, err != nil, Receipt != nil: transaction was mined but execution reverted. err wraps ErrTxFailed (use errors.Is). Receipt carries the failed status and any logs emitted before revert.