accessor

package
v1.9.2 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: Apache-2.0, MIT Imports: 13 Imported by: 0

Documentation

Overview

Package accessor is Lantern's query layer over a trusted state root.

Every public method takes a TrustedRoot (or its StateRoot CID) and an address (or other key), returns the requested actor state plus a proof path that lets a third party re-verify the result.

The accessor is the only layer in Lantern that knows how to translate "what's f099's balance?" into a sequence of HAMT/AMT lookups. It does so using `go-state-types` actor codecs and Lantern's path-recording HAMT/AMT walkers in state/hamt and state/amt.

Provenance: structurally inspired by Lotus' chain/state/statetree.go and chain/actors/builtin/init/* loaders, but every method is reimplemented to use Lantern's BlockGetter abstraction (no IpldStore dependency). Lifted constants and the StateRoot tuple definition are tagged in-place.

Index

Constants

This section is empty.

Variables

View Source 
var ErrAddressNotFound = fmt.Errorf("address not found in init actor AddressMap")

ErrAddressNotFound is returned when an address is not in the Init actor AddressMap. This is normal for never-funded addresses on chain.

Functions

This section is empty.

Types

type Accessor 

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

Accessor is the public surface used by every RPC handler. It is goroutine- safe: each method captures the trusted-root pointer at entry and reads only via the supplied BlockGetter.

func New 

func New(tr *trustedroot.TrustedRoot, bg hamt.BlockGetter) *Accessor

New returns an Accessor bound to a TrustedRoot and a BlockGetter.

func (*Accessor) GetActor 

func (a *Accessor) GetActor(ctx context.Context, target addr.Address) (*Actor, []cid.Cid, error)

GetActor resolves `target` (any-protocol address) to its ID address via the Init actor, then walks the state-tree HAMT to the actor's state. Returns the Actor + the full proof path (state-root block + Init-actor HAMT path + state-tree HAMT path).

func (*Accessor) GetActorByID 

func (a *Accessor) GetActorByID(ctx context.Context, idAddr addr.Address) (*Actor, []cid.Cid, error)

GetActorByID is the ID-only fast path. Use it when you already have an ID address and want to skip the Init-actor resolve step.

func (*Accessor) LoadAccount 

func (a *Accessor) LoadAccount(ctx context.Context, target addr.Address) (actors.AccountState, []cid.Cid, error)

LoadAccount loads any account actor by address.

func (*Accessor) LoadDatacap 

func (a *Accessor) LoadDatacap(ctx context.Context) (actors.DatacapState, []cid.Cid, error)

LoadDatacap returns the datacap actor's state handle. Always at f07.

func (*Accessor) LoadInit 

func (a *Accessor) LoadInit(ctx context.Context) (actors.InitState, []cid.Cid, error)

LoadInit returns the init actor's state handle. Always at f01.

func (*Accessor) LoadMarket 

func (a *Accessor) LoadMarket(ctx context.Context) (actors.MarketState, []cid.Cid, error)

LoadMarket returns the market actor's state handle. Always at f05.

func (*Accessor) LoadMiner 

func (a *Accessor) LoadMiner(ctx context.Context, target addr.Address) (actors.MinerState, []cid.Cid, error)

LoadMiner resolves `target` to a miner actor and returns the versioned MinerState handle plus the proof path used to fetch the actor.

func (*Accessor) LoadMultisig 

func (a *Accessor) LoadMultisig(ctx context.Context, target addr.Address) (actors.MultisigState, []cid.Cid, error)

LoadMultisig loads any multisig actor by address.

func (*Accessor) LoadPaych 

func (a *Accessor) LoadPaych(ctx context.Context, target addr.Address) (actors.PaychState, []cid.Cid, error)

LoadPaych loads any payment-channel actor by address.

func (*Accessor) LoadPower 

func (a *Accessor) LoadPower(ctx context.Context) (actors.PowerState, []cid.Cid, error)

LoadPower returns the power actor's state handle. Always at f04.

func (*Accessor) LoadReward 

func (a *Accessor) LoadReward(ctx context.Context) (actors.RewardState, []cid.Cid, error)

LoadReward returns the reward actor's state handle. Always at f02.

func (*Accessor) LoadSystem 

func (a *Accessor) LoadSystem(ctx context.Context) (actors.SystemState, []cid.Cid, error)

LoadSystem returns the system actor's state handle. Always at f00.

func (*Accessor) LoadVerifreg 

func (a *Accessor) LoadVerifreg(ctx context.Context) (actors.VerifregState, []cid.Cid, error)

LoadVerifreg returns the verifreg actor's state handle. Always at f06.

func (*Accessor) LookupID 

func (a *Accessor) LookupID(ctx context.Context, target addr.Address) (addr.Address, []cid.Cid, error)

LookupID resolves an address to its ID-address. ID addresses pass through unchanged (with no proof needed beyond the bound TrustedRoot).

func (*Accessor) MarketDealRaw 

func (a *Accessor) MarketDealRaw(ctx context.Context, dealID uint64) ([]byte, []cid.Cid, error)

MarketDealRaw looks up the deal proposal bytes for a given deal ID by walking the StorageMarket actor's Proposals AMT.

Layout: Market actor (singleton f05) → MarketState → Proposals (AMT root) → DealProposal at index dealID.

func (*Accessor) MessageReceiptByIndex 

func (a *Accessor) MessageReceiptByIndex(ctx context.Context, idx uint64) (*Receipt, []cid.Cid, error)

MessageReceiptByIndex fetches receipt N from the ParentMessageReceipts AMT bound to the TrustedRoot. N is the position within the tipset's merged message list.

func (*Accessor) Rebind 

func (a *Accessor) Rebind(bg hamt.BlockGetter)

Rebind swaps the BlockGetter in place while PRESERVING accessor configuration (notably the head-state provider). Used when a later wiring step replaces the block source (e.g. after Bitswap comes up).

Callers must not rebuild the accessor with New in that case: doing so drops the head-state provider and silently re-pins state reads to the boot trusted-root (the lantern#87 regression this method prevents).

func (*Accessor) Registry 

func (a *Accessor) Registry() *actors.Registry

Registry returns the actor-code registry used by the loaders.

func (*Accessor) SetHeadStateProvider 

func (a *Accessor) SetHeadStateProvider(fn func() (cid.Cid, bool))

SetHeadStateProvider wires an optional live-head state-root provider. When set, state reads resolve against the provider's state root instead of the frozen boot trusted-root, so the accessor follows the chain. Pass nil to revert to boot-anchored reads. Safe to call once at wiring time.

func (*Accessor) TrustedRoot 

func (a *Accessor) TrustedRoot() *trustedroot.TrustedRoot

TrustedRoot returns the bound root.

type Actor 

type Actor struct {
	Code             cid.Cid
	Head             cid.Cid
	Nonce            uint64
	Balance          big.Int
	DelegatedAddress *addr.Address // nil for non-EVM (non-f4) actors
}

Actor is the runtime representation of an on-chain actor. It corresponds to ActorV5 in go-state-types/builtin/actor_tree.go.

func DecodeActor 

func DecodeActor(raw []byte) (*Actor, error)

DecodeActor parses a HAMT-leaf bytes blob into an Actor.

type MarketDeal 

type MarketDeal struct {
	Raw    []byte // full CBOR-encoded DealProposal; caller can re-decode
	DealID uint64
}

MarketDeal is a structural reflection of `market.DealProposal`. Decoding the full proposal is delegated to go-state-types when the caller wants strict types; this struct surfaces the most commonly used fields.

type Receipt 

type Receipt struct {
	ExitCode   int64
	Return     []byte
	GasUsed    int64
	EventsRoot *cid.Cid // nil if not present or null
}

Receipt is the per-message execution receipt stored in the AMT rooted at TrustedRoot.ParentMessageReceipts.

Layout (from go-state-types/abi.MessageReceipt with EventsRoot optional): 

[exitCode int, return bytes, gasUsed int64, eventsRoot? cid|null]

Network version 18+ adds the optional EventsRoot pointer.

type StateRoot 

type StateRoot struct {
	Version StateTreeVersion
	Actors  cid.Cid // top-level state-tree HAMT root, keyed by ID-address
	Info    cid.Cid // miscellaneous chain info; not currently used
}

StateRoot is the value stored at a state-root CID for version 1+. (Version 0 stored the actors HAMT CID directly with no wrapper.)

func DecodeStateRoot 

func DecodeStateRoot(raw []byte) (*StateRoot, error)

DecodeStateRoot parses the raw IPLD-DAG-CBOR bytes of a state-root block. Returns an error if the bytes don't conform to the documented layout.

Layout: 3-element CBOR array [uint version, cid-link actors, cid-link info].

type StateTreeVersion 

type StateTreeVersion uint64

StateTreeVersion is the on-chain state-tree version. Filecoin currently runs at version 5 (since network version 18, the FVM Stable Memory rollout). 

const (
	StateTreeVersion0 StateTreeVersion = 0
	StateTreeVersion1 StateTreeVersion = 1
	StateTreeVersion2 StateTreeVersion = 2
	StateTreeVersion3 StateTreeVersion = 3
	StateTreeVersion4 StateTreeVersion = 4
	StateTreeVersion5 StateTreeVersion = 5
)

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.