aivm

package
v1.7.39 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: BSD-3-Clause Imports: 36 Imported by: 0

Documentation

Overview

Package aivm GPU backend — runtime-loaded plugin bridge.

Unlike cevm/cevm_cgo.go (which links libevm + libevm-gpu via pkg-config), AIVM resolves its GPU backend at PROCESS START via dlopen/dlsym against the lux-gpu-kernels plugin DSOs. This keeps the chains module compilable without the lux GPU plugin present in the build tree — the plugin is fully optional.

Lookup order (handled by backend.go): 

libluxgpu_backend_cuda.so       (Linux x86_64 + NVIDIA)
libluxgpu_backend_hip.so        (Linux x86_64 + AMD ROCm)
libluxgpu_backend_metal.dylib   (macOS Apple Silicon / Intel)
libluxgpu_backend_vulkan.so/.dylib   (any Vulkan ICD)
libluxgpu_backend_webgpu.so/.dylib   (Dawn / wgpu-native)

Each plugin exports six extern "C" host launchers per backend: 

lux_<backend>_aivm_attestation_apply
lux_<backend>_aivm_provenance_apply
lux_<backend>_aivm_anchor_apply
lux_<backend>_aivm_epoch_transition
lux_<backend>_aivm_inference_step
lux_<backend>_aivm_proof_verify

Struct layout matches ops/aivm/cuda/aivm_kernels_common.cuh byte-for-byte (asserted by init()). Pointer ABI is HOST pointers — the launcher does H2D-upload / dispatch / D2H-download internally.

Package aivm provides the AI Virtual Machine for the Lux network.

AIVM is the AI compute coordination layer. It works on ANY Lux L1/L2 (mainnet primary network, testnet, devnet, white-label chains) with NO trusted dealer, NO TEE requirement, and NO single point of trust.

Verification model (per VerificationMode):

  • ModeOptimistic (DEFAULT, public-BFT-safe): providers post results with hash-commitment + bond; N-block challenge period; uncontested results finalise; challenged results enter fraud-proof flow with slashing of the losing side. No TEE assumption. Works on any L1/L2 that has Pulsar/Corona for finality.

  • ModeMultiPartyRedundant: M-of-N validators run the same inference and consensus on the output hash. No single provider needs trust; malicious providers diverge from the majority and are slashed. Public-BFT-safe. Cost: M× compute per task.

  • ModeTEEAttested: when a provider has SGX/SEV-SNP/TDX/nvtrust available, the attestation is FOLDED INTO the trust score as an accelerator (skip the challenge period for high-trust-score providers). TEE never CHANGES the trust root — only reduces latency-to-finality for already-bonded providers.

The TEE path (luxfi/ai/pkg/attestation) is OPTIONAL across all modes. Setting RequireTEEAttestation=true is a deployment policy choice for permissioned/regulated deployments; the public-chain default is VerificationMode=ModeOptimistic + RequireTEEAttestation=false.

Other features:

  • Task submission and assignment (chain-agnostic)
  • Mining rewards (paid in the host chain's native token)
  • Optional anchoring to Q-Chain for cross-chain settlement (controlled by HostChainID: when "primary", anchor to Q-Chain; otherwise anchor to the host chain's own finality)

Index

Constants

View Source 
const (
	InferenceInDim  = 32
	InferenceHidden = 16
	InferenceOutDim = 1
)

InferenceWeights mirrors aivm::cuda::InferenceWeights (672 bytes). 32→16→1 quantized classifier weights.

View Source 
const (
	DomainIntent  = "lux/aivmbridge/intent/v1"
	DomainReceipt = "lux/aivmbridge/receipt/v1"
)

Domain separators (raw UTF-8 bytes, no length prefix — concatenated verbatim). They keep the intent-id keyspace and the receipt-hash keyspace disjoint, and version the wire so a future v2 cannot collide with v1.

View Source 
const (
	StatusUnknown    uint8 = 0
	StatusPending    uint8 = 1
	StatusCompleted  uint8 = 2
	StatusFailed     uint8 = 3
	StatusChallenged uint8 = 4
)

Receipt status codes (the AInferenceReceipt.Status byte). Pinned values shared with the boundary.

View Source 
const MaxBlockSize = 2 << 20 // 2 MiB

MaxBlockSize bounds the wire encoding a block may arrive as, checked BEFORE anything is decoded. Without it a peer chose how much memory this node allocated: a single 49 MB block, made of nothing but repeated provider registrations, parsed without complaint.

It is a CONSENSUS RULE, not configuration — every node enforces the same number on the same block, and a bound each operator could set would let two honestly-configured validators reach opposite verdicts. Verify holds a self-built block to it too, so a proposer cannot produce one its own peers would refuse to parse.

View Source 
const MaxFutureSkew = 60 * time.Second

MaxFutureSkew is how far ahead of the verifying node's clock a block's timestamp may be. Timestamps are monotonic — Verify refuses one below its parent's — so an unbounded stamp is not a one-block error: it raises the floor every later block must clear, and one block dated a thousand hours out stops the chain producing for a thousand hours. The bound is loose enough to absorb ordinary clock disagreement between honest validators and tight enough that the damage from an out-of-range one is a single rejected block.

View Source 
const ReceiptEncodedLen = 2 + 32 + 32 + 32 + 32 + 20 + 32 + 32 + 32 + 1 + 2 + 2 + 32 + 32 + 32 + 8 // = 355

ReceiptEncodedLen is the exact byte length of the canonical AInferenceReceipt encoding (see EncodeReceipt). Pinned so a drift in field widths/order is a compile/test failure, not a silent cross-chain mismatch. 

u16(Version)2 + IntentID32 + TaskID32 + CChainID32 + AChainID32 +
Requester20 + ModelSpecHash32 + PromptHash32 + CanonicalOutputHash32 +
u8(Status)1 + u16(N)2 + u16(Threshold)2 + WinnersRoot32 + OperatorsRoot32 +
u256(FeePaid)32 + u64(SettledAtHeight)8
View Source 
const ReceiptVersion uint16 = 1

ReceiptVersion is the wire version stamped into every receipt (the u16be Version field). Bumping it is a wire change shared with the boundary.

Variables

View Source 
var (
	// ErrInvalidBlock refuses a block that does not sit correctly on the chain:
	// a bad height, a timestamp outside its bounds, an oversized encoding, or a
	// genesis block offered as a proposal.
	ErrInvalidBlock = errors.New("aivm: invalid block")

	// ErrNotOnTip refuses a block the chain will not build on: one whose parent
	// is neither the accepted tip nor a block verified above it and still in
	// flight. Accepting one rewinds the chain and leaves the height index naming
	// an orphan as canonical.
	ErrNotOnTip = errors.New("aivm: block does not extend the accepted tip")

	// ErrDetachedBlock refuses a block with no chain behind it. Such a block has
	// no parent to sit on, no state to check against, and no chain id to be
	// named by — every question Verify asks is unanswerable, and answering "no
	// objection" to all of them is how an unchecked block passes.
	ErrDetachedBlock = errors.New("aivm: block belongs to no chain")
)

Block errors.

View Source 
var (
	// MinProviderBond is the floor a provider must keep bonded to be eligible
	// for selection. It is also the per-operator SYBIL COST: forging a canonical
	// hash requires controlling >= threshold selected operators, each bonded
	// >= MinProviderBond, so the absolute forgery floor is threshold *
	// MinProviderBond regardless of any selection grinding. Matches the aivm
	// Config default (1000 LUX) expressed in wei.
	MinProviderBond = uint256.NewInt(1_000_000_000_000_000_000) // 1 token (1e18 wei) per unit; scaled by deployment

	// SlashPerOperator is the bonded-stake penalty for a SELECTED operator that
	// committed but never revealed (withholding). Always applied; dissenters
	// (revealed a minority hash) are NOT slashed.
	SlashPerOperator = uint256.NewInt(100_000_000_000_000_000) // 0.1 token

	// RequestFeePerOperator is the NON-REFUNDABLE fee charged per selected
	// operator when a task is created, burned to BurnAddress. Separate from the
	// refundable reward escrow: a task that fails to reach quorum refunds the
	// reward but NOT the fee. It prices REPEATED requests (selection-grind /
	// censorship by resubmission), so the on-chain cost scales with N and with
	// the number of submitted tasks.
	RequestFeePerOperator = uint256.NewInt(10_000_000_000_000_000) // 0.01 token

	// RequestMarginFloor / RequestMarginBps define the ELIGIBLE-SET MARGIN:
	// a task is rejected unless the eligible pool E for the ModelSpec satisfies
	// E >= N + max(RequestMarginFloor, N*RequestMarginBps/1e4). This forbids
	// degenerate pools where selection has no sampling headroom, and guarantees
	// the draw is always a strict subset of a larger universe (a single cheap
	// operator is never the whole pool).
	RequestMarginFloor uint32 = 2
	RequestMarginBps   uint32 = 5000 // 50%

	// CommitBlocks / RevealBlocks bound the commit and reveal windows. The
	// reveal window opens strictly AFTER the commit window closes so no operator
	// can see a peer's revealed output before committing.
	CommitBlocks uint64 = 30
	RevealBlocks uint64 = 30

	// UnbondCooldownBlocks is how long after deregistration a stake withdrawal
	// must wait — bounds the window in which an unbonding operator could still be
	// selected for an unsettled task.
	UnbondCooldownBlocks uint64 = 60

	// SlashDissenters: default false. Honest disagreement (nondeterministic
	// model output) must not be punished, and slashing dissenters would let a
	// majority cartel grief an honest minority. Withholding is always slashed.
	SlashDissenters = false
)

Window + economic policy — protocol constants (one true configuration, not per-call knobs) so every validator computes identical deadlines and identical slash math. These realize the aivm Config fields (MinProviderBond, ChallengeWindowBlocks, RedundancyFactor) as ENFORCED quantities rather than the prior stubs.

View Source 
var (
	// registry / stake
	ErrEmptyModelSpec    = errors.New("aivm/quorum: empty model spec hash")
	ErrStakeBelowMin     = errors.New("aivm/quorum: stake below MinProviderBond")
	ErrOperatorExists    = errors.New("aivm/quorum: operator already registered")
	ErrOperatorUnknown   = errors.New("aivm/quorum: operator not registered")
	ErrOperatorUnbonding = errors.New("aivm/quorum: operator is unbonding")
	// ErrOperatorBonded is the converse: the operator has not deregistered,
	// so no cooldown has started and there is no stake to withdraw.
	ErrOperatorBonded = errors.New("aivm/quorum: operator is still bonded")
	ErrCooldownActive = errors.New("aivm/quorum: unbond cooldown not elapsed")

	// custody / conservation
	ErrInsufficientFunds = errors.New("aivm/quorum: insufficient balance")
	ErrEscrowUnderflow   = errors.New("aivm/quorum: escrow underflow (invariant broken)")
	ErrStakeOverflow     = errors.New("aivm/quorum: stake overflow")
	ErrCreditOverflow    = errors.New("aivm/quorum: credit overflow")
	ErrRewardOverflow    = errors.New("aivm/quorum: reward escrow overflow")
	ErrFeeOverflow       = errors.New("aivm/quorum: request fee overflow")
	ErrNoCredit          = errors.New("aivm/quorum: no credit to withdraw")

	// task params / selection
	ErrEmptyPromptHash     = errors.New("aivm/quorum: empty prompt hash")
	ErrBadN                = errors.New("aivm/quorum: N out of range [minN, maxN]")
	ErrBadThreshold        = errors.New("aivm/quorum: threshold must satisfy floor(N/2)+1 <= threshold <= N")
	ErrNotEnoughEligible   = errors.New("aivm/quorum: fewer eligible operators than N")
	ErrEligibleBelowMargin = errors.New("aivm/quorum: eligible operator set below N + required margin")

	// task lifecycle
	ErrTaskUnknown        = errors.New("aivm/quorum: task not found")
	ErrTaskNotCommitting  = errors.New("aivm/quorum: task not in committing state")
	ErrTaskAlreadySettled = errors.New("aivm/quorum: task already settled")
	ErrNotSelected        = errors.New("aivm/quorum: operator not selected for task")
	ErrCommitClosed       = errors.New("aivm/quorum: commit window closed")
	ErrAlreadyCommitted   = errors.New("aivm/quorum: operator already committed")
	ErrNotCommitted       = errors.New("aivm/quorum: operator did not commit")
	ErrRevealNotOpen      = errors.New("aivm/quorum: reveal window not open")
	ErrRevealClosed       = errors.New("aivm/quorum: reveal window closed")
	ErrAlreadyRevealed    = errors.New("aivm/quorum: operator already revealed")
	ErrCommitMismatch     = errors.New("aivm/quorum: reveal does not match commit")
	ErrEmptyCommit        = errors.New("aivm/quorum: empty commit hash")
	ErrEmptyOutputHash    = errors.New("aivm/quorum: empty output hash")
	ErrSettleTooEarly     = errors.New("aivm/quorum: reveal window not closed")

	// cross-chain seam
	ErrIntentNilAmount     = errors.New("aivm/quorum: C-chain intent has a nil fee or reward amount")
	ErrIntentIDMismatch    = errors.New("aivm/quorum: recomputed intent_id does not match delivered id (forged/tampered intent)")
	ErrIntentNotCommitted  = errors.New("aivm/quorum: C-chain intent is not committed (proof rejected)")
	ErrIntentAlreadyUsed   = errors.New("aivm/quorum: C-chain intent already consumed (replay)")
	ErrReceiptNotFound     = errors.New("aivm/quorum: no settled receipt for intent")
	ErrProofOutOfRange     = errors.New("aivm/quorum: receipt index out of range")
	ErrReceiptRootMismatch = errors.New("aivm/quorum: block receipt_root does not match re-derived engine state")
)

Engine errors. Every one is a hard failure that leaves state unchanged (fail-closed): a rejected operation makes NO write. Grouped by phase so the surface is auditable in one place.

View Source 
var (
	Version = &version.Semantic{
		Major: 1,
		Minor: 0,
		Patch: 0,
	}

	ErrNotInitialized   = errors.New("vm not initialized")
	ErrInvalidTask      = errors.New("invalid task")
	ErrProviderNotFound = errors.New("provider not found")
)
View Source 
var BurnAddress = common.HexToAddress("0x000000000000000000000000000000000000dEaD")

BurnAddress is the unspendable sink the non-refundable request fee is parked in. No engine method ever pays OUT of it, so wei that lands here is removed from circulation without being destroyed (which would break the grand-total conservation invariant). The fee moves requester -> EscrowAccount -> BurnAddress, so EscrowAccount nets zero for the fee and its stake+escrow+credit identity is untouched.

View Source 
var ErrGPUNotAvailable = errors.New("aivm: no GPU plugin available")

ErrGPUNotAvailable is returned by every GPUBackend method when no plugin was loadable at init time. Callers fall through to the existing Go path.

View Source 
var EscrowAccount = common.HexToAddress("0xA1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1")

EscrowAccount is the single account that holds all engine-custodied native value: bonded provider stake, open job reward escrow, and unwithdrawn credit. It holds no code; all movement is balance mutation. The conservation invariant the engine maintains and the tests assert: 

balance(EscrowAccount) == sum(bonded stake)
                        + sum(open job escrow)
                        + sum(unwithdrawn credit)

at every step, and the grand total over all accounts is constant.

View Source 
var VMID = ids.ID{'a', 'i', 'v', 'm'}

VMID is the unique identifier for AIVM (A-Chain)

Functions

func ComputeCommit added in v1.3.15 

func ComputeCommit(taskID, modelSpecHash, promptHash, outputHash, embeddingHash common.Hash, operator common.Address, nonce common.Hash) common.Hash

ComputeCommit implements the operator-bound commit preimage (fixed width, this order): 

commit = keccak256( task_id(32) || model_spec_hash(32) || prompt_hash(32) ||
                    output_hash(32) || embedding_hash(32) || operator(20) ||
                    nonce(32) )

The operator address is bound INTO the commit — the anti-copy / anti-front-run control: a peer who observes operator A's commit cannot replay it as their own (recomputation with their own address yields a different digest, so RevealResponse rejects it).

func ComputeIntentID added in v1.3.15 

func ComputeIntentID(cChainID, aChainID, cTxHash common.Hash, callIndex uint32, caller common.Address, modelSpecHash, promptHash common.Hash, n, threshold uint16, fee *uint256.Int) common.Hash

ComputeIntentID derives the cross-chain intent id from the COMMITTED C-Chain intent fields, exactly: 

keccak256( DomainIntent ||
    c_chain_id(32) || a_chain_id(32) || c_tx_hash(32) || u32be(call_index) ||
    caller(20) || model_spec_hash(32) || prompt_hash(32) ||
    u16be(N) || u16be(threshold) || u256be(fee,32) )

Every field is fixed-width in this precise order. The A-Chain importer recomputes this from the delivered fields and rejects the intent unless it equals the id the C side committed — so a forged/tampered intent (any field altered) yields a different id and cannot create a task.

func Routes added in v1.7.30 

func Routes(vm *VM) map[string]http.Handler

Routes returns one handler per endpoint.

The node mounts each key under /v1/bc/<chainID> and matches that full path EXACTLY, then hands the handler the request with the path it arrived on. A handler therefore never sees a path it can dispatch on, and no path below a mount is routable at all. The key IS the route — the same shape bridgevm and zkvm use.

func SetBackend added in v1.3.0 

func SetBackend(m Mode)

SetBackend selects the active AIVM transition mode for the process. Use AutoAIVM (the default) to let init()'s dlopen probe pick the best available backend.

func VerifyReceiptProof added in v1.3.15 

func VerifyReceiptProof(receiptHash common.Hash, proof MerkleProof, root common.Hash) bool

VerifyReceiptProof checks that receiptHash is included under root at the proof's index. It re-applies the leaf hash (leafHash) and folds with the siblings, choosing left/right by the index bit at each level — exactly inverting merkleProof/merkleRoot. Returns true iff the recomputed root equals root. This is the function the A->C boundary (and anyone) uses to verify an exported receipt belongs to the committed receipt_root.

The index must be SPENT by the fold: after one halving per sibling nothing may be left of it. The fold reads one bit per level and silently discards the rest, so any index sharing its low bits verified — in a 4-leaf tree, index 4 (and 8, and 12, and every other index congruent mod 4) proved membership at index 0. An index is part of what a proof asserts, and a verifier that ignores most of it is not checking that assertion.

Types

type AIVMEpochState added in v1.3.0 

type AIVMEpochState struct {
	CurrentEpoch            uint64
	NextEpochHeight         uint64
	TotalActiveAttestations uint64
	ActiveModelCount        uint32
	ExpiredAttestationCount uint32
	AttestationRoot         [32]byte
	ModelRegistryRoot       [32]byte
	AuditRoot               [32]byte
	AIVMStateRoot           [32]byte
}

AIVMEpochState mirrors aivm::cuda::AIVMEpochState (160 bytes).

type AIVMRoundDescriptor added in v1.3.0 

type AIVMRoundDescriptor struct {
	ChainID            uint64
	Round              uint64
	TimestampNS        uint64
	Epoch              uint64
	Mode               uint32
	AttestationOpCount uint32
	ModelOpCount       uint32
	AnchorOpCount      uint32
	ClosingFlag        uint32

	ParentAIVMRoot [32]byte
	// contains filtered or unexported fields
}

AIVMRoundDescriptor mirrors aivm::cuda::AIVMRoundDescriptor (96 bytes).

type AIVMTransitionResult added in v1.3.0 

type AIVMTransitionResult struct {
	Status                uint32
	AttestationApplyCount uint32
	ModelApplyCount       uint32
	AnchorApplyCount      uint32
	ActiveAttestations    uint32
	ExpiredAttestations   uint32
	ModelCount            uint32
	AnchorCount           uint32
	Epoch                 uint64
	TotalModels           uint64
	TotalAnchors          uint64

	AttestationRoot   [32]byte
	ModelRegistryRoot [32]byte
	AuditRoot         [32]byte
	AIVMStateRoot     [32]byte
	// contains filtered or unexported fields
}

AIVMTransitionResult mirrors aivm::cuda::AIVMTransitionResult (192 bytes).

type AIVertex 

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

AIVertex represents a DAG vertex in the AI chain. Conflict key: jobID. Independent jobs commute; same job conflicts.

func (*AIVertex) Accept 

func (v *AIVertex) Accept(ctx context.Context) error

Accept records the vertex. It does NOT move the block chain's tip: a vertex is not a block, and writing the vertex id into the tip left the id the VM reported and the block the VM held disagreeing — two owners of one fact, and the one a restart would read back named no block at all.

The vertex is stored under its own prefix, disjoint from the block keyspace, so a block read can never decode a vertex.

func (*AIVertex) Bytes 

func (v *AIVertex) Bytes() []byte

func (*AIVertex) Conflicts 

func (v *AIVertex) Conflicts(other *AIVertex) bool

Conflicts returns true if this vertex and other reference the same jobID.

func (*AIVertex) ConflictsVertex 

func (v *AIVertex) ConflictsVertex(other vertex.Vertex) bool

ConflictsVertex performs the same check against the vertex.Vertex interface.

func (*AIVertex) Epoch 

func (v *AIVertex) Epoch() uint32

func (*AIVertex) Height 

func (v *AIVertex) Height() uint64

func (*AIVertex) ID 

func (v *AIVertex) ID() ids.ID

func (*AIVertex) Parents 

func (v *AIVertex) Parents() []ids.ID

func (*AIVertex) Reject 

func (v *AIVertex) Reject(ctx context.Context) error

func (*AIVertex) Status 

func (v *AIVertex) Status() choices.Status

func (*AIVertex) Txs 

func (v *AIVertex) Txs() []ids.ID

func (*AIVertex) Verify 

func (v *AIVertex) Verify(ctx context.Context) error

type AInferenceReceipt added in v1.3.15 

type AInferenceReceipt struct {
	Version             uint16         `json:"version"`
	IntentID            common.Hash    `json:"intentId"` // source C-chain intent id
	TaskID              common.Hash    `json:"taskId"`   // A-chain task id (beacon anchor)
	CChainID            common.Hash    `json:"cChainId"`
	AChainID            common.Hash    `json:"aChainId"`
	Requester           common.Address `json:"requester"`
	ModelSpecHash       common.Hash    `json:"modelSpecHash"`
	PromptHash          common.Hash    `json:"promptHash"`
	CanonicalOutputHash common.Hash    `json:"canonicalOutputHash"` // zero if Failed
	Status              uint8          `json:"status"`              // StatusCompleted / StatusFailed / ...
	N                   uint16         `json:"n"`
	Threshold           uint16         `json:"threshold"`
	WinnersRoot         common.Hash    `json:"winnersRoot"`   // merkle root over winner addresses
	OperatorsRoot       common.Hash    `json:"operatorsRoot"` // merkle root over selected addresses
	FeePaid             *uint256.Int   `json:"feePaid"`
	SettledAtHeight     uint64         `json:"settledAtHeight"`
}

AInferenceReceipt is the cross-chain settlement receipt. Field order here is presentation; the WIRE order is fixed by EncodeReceipt and MUST NOT be reordered.

func (AInferenceReceipt) Encode added in v1.3.15 

func (r AInferenceReceipt) Encode() []byte

EncodeReceipt produces the canonical fixed-width encoding (exactly ReceiptEncodedLen = 355 bytes) in the PINNED order: 

u16be(Version) || IntentID(32) || TaskID(32) || CChainID(32) || AChainID(32) ||
Requester(20) || ModelSpecHash(32) || PromptHash(32) || CanonicalOutputHash(32) ||
u8(Status) || u16be(N) || u16be(Threshold) || WinnersRoot(32) ||
OperatorsRoot(32) || u256be(FeePaid,32) || u64be(SettledAtHeight)

func (AInferenceReceipt) Hash added in v1.3.15 

func (r AInferenceReceipt) Hash() common.Hash

Hash is the receipt commitment: keccak256(DomainReceipt || Encode()). This is the leaf value (pre-leaf-hash) that goes into the receipt_root and that an exported proof proves membership of.

type AnchorOp added in v1.3.0 

type AnchorOp struct {
	CommitRoot               [32]byte
	ParentRoot               [32]byte
	ValidatorSetRootAtCommit [32]byte
	Height                   uint64
	TimestampNS              uint64
	Epoch                    uint32
	// contains filtered or unexported fields
}

AnchorOp mirrors aivm::cuda::AnchorOp (128 bytes).

type Attestation added in v1.3.0 

type Attestation struct {
	TEEQuoteDigest [32]byte
	Measurement    [32]byte
	AttestingKey   [48]byte
	ExpiryNS       uint64
	Kind           uint32
	EvidenceOffset uint32
	EvidenceLen    uint32
	Status         uint32
	Occupied       uint32
	// contains filtered or unexported fields
}

Attestation mirrors aivm::cuda::Attestation (144 bytes).

type AttestationOp added in v1.3.0 

type AttestationOp struct {
	TEEQuoteDigest [32]byte
	Measurement    [32]byte
	AttestingKey   [48]byte
	ExpiryNS       uint64
	Kind           uint32
	EvidenceOffset uint32
	EvidenceLen    uint32
	Epoch          uint32
	// contains filtered or unexported fields
}

AttestationOp mirrors aivm::cuda::AttestationOp (144 bytes).

type AuditAnchor added in v1.3.0 

type AuditAnchor struct {
	CommitRoot               [32]byte
	ParentRoot               [32]byte
	ValidatorSetRootAtCommit [32]byte
	Height                   uint64
	TimestampNS              uint64
	Occupied                 uint32
	// contains filtered or unexported fields
}

AuditAnchor mirrors aivm::cuda::AuditAnchor (128 bytes).

type BackendKind added in v1.3.0 

type BackendKind uint8

BackendKind identifies which lux-gpu-kernels plugin satisfied the runtime dlopen probe. AvailableNone is the sentinel "fall through to Go". 

const (
	AvailableNone   BackendKind = 0
	AvailableCUDA   BackendKind = 1
	AvailableHIP    BackendKind = 2
	AvailableMetal  BackendKind = 3
	AvailableVulkan BackendKind = 4
	AvailableWebGPU BackendKind = 5
)

func EffectiveBackendKind added in v1.3.0 

func EffectiveBackendKind() BackendKind

EffectiveBackendKind returns which backend the next transition will actually use given (ActiveMode, ActiveGPUBackend). Useful for logging at boot.

func (BackendKind) String added in v1.3.0 

func (k BackendKind) String() string

String returns the human-readable name for the backend kind.

type Block 

type Block struct {
	ID_        ids.ID    `json:"id"`
	ParentID_  ids.ID    `json:"parentID"`
	Height_    uint64    `json:"height"`
	Timestamp_ time.Time `json:"timestamp"`

	// AI-specific data
	Tasks        []aivm.Task       `json:"tasks,omitempty"`
	Results      []aivm.TaskResult `json:"results,omitempty"`
	MerkleRoot   [32]byte          `json:"merkleRoot"`
	ProviderRegs []ProviderReg     `json:"providerRegs,omitempty"`

	// ImportedIntents are the committed C-Chain intents that this block turned
	// into A-Chain quorum tasks (under consensus, via the verified inbound seam).
	// Recorded so Block.Verify can deterministically re-run the same imports and
	// every validator reaches identical engine state.
	ImportedIntents []CIntent `json:"importedIntents,omitempty"`

	// ReceiptRoot is the engine's committed receipt_root as of this block — the
	// single commitment the A->C boundary exports.
	ReceiptRoot common.Hash `json:"receiptRoot"`
	// contains filtered or unexported fields
}

Block represents an AIVM block

func (*Block) Accept 

func (blk *Block) Accept(ctx context.Context) error

Accept makes the block fact.

Everything the block changes — its state transition, its own bytes, its height entry and the tip pointer — is staged through ONE view and committed ONCE, so the chain has the whole block or none of it. Any failure aborts the view and leaves the tip where it was: the block did not happen, and nothing it claimed survives. In-memory state advances only after the commit returns, so there is no window in which this node has moved past state that is not on disk.

func (*Block) Bytes 

func (blk *Block) Bytes() []byte

Bytes returns the block's canonical wire encoding.

func (*Block) Height 

func (blk *Block) Height() uint64

Height returns the block height

func (*Block) ID 

func (blk *Block) ID() ids.ID

ID returns the block ID

func (*Block) Marshal added in v1.7.9 

func (blk *Block) Marshal() ([]byte, error)

Marshal encodes the block (excluding the derived ID_/cache fields) to canonical wire. blockID = sha256(this).

func (*Block) Parent 

func (blk *Block) Parent() ids.ID

Parent returns the parent block ID

func (*Block) ParentID 

func (blk *Block) ParentID() ids.ID

ParentID returns the parent block ID

func (*Block) Reject 

func (blk *Block) Reject(ctx context.Context) error

Reject drops the block. It never wrote anything — Verify runs the transition against an overlay it discards — so there is nothing to undo, and in particular nothing belonging to a SIBLING to undo, which is what the rollback this replaces used to take with it.

The intents it carried stay buffered: rejection means this block did not land, not that the work was invalid, so the next proposer may carry it again.

func (*Block) Status 

func (blk *Block) Status() uint8

Status reports 0 = processing, 1 = accepted.

func (*Block) Timestamp 

func (blk *Block) Timestamp() time.Time

Timestamp returns the block timestamp

func (*Block) Verify 

func (blk *Block) Verify(ctx context.Context) error

Verify decides whether this block can be accepted, and changes NOTHING.

It checks that the block sits correctly on its parent in height and in time, that its encoding is one every peer will accept, and that the state transition it claims is the one this node computes from the same inputs. The transition runs against an overlay over committed state and a clone of the ledger, both discarded on the way out, so a block that verifies and then loses the round has moved no state and no value — and two blocks in flight cannot see each other's work, which is what let Accept(A) publish B's intent and Reject(B) discard A's.

Verify does not decide the outcome on its own. The tip moves between this call and Accept, and it is Accept, holding the lock that commits, that has the last word.

type CCommitVerifier added in v1.3.15 

type CCommitVerifier interface {
	VerifyCommitted(intent CIntent) error
}

CCommitVerifier proves a C-Chain intent is committed (reached C finality). It is the ONLY trust the inbound seam imports from C: the engine creates a task only if VerifyCommitted returns nil. A real implementation checks a Warp/ZAP attestation or a state proof against a committed C block; it MUST NOT return nil for a live/uncommitted/spoofed intent. The interface keeps the proof mechanism orthogonal to the state machine.

type CIntent added in v1.3.15 

type CIntent struct {
	IntentID          common.Hash    `json:"intentId"` // committed on C; must equal ComputeIntentID(...)
	CChainID          common.Hash    `json:"cChainId"`
	AChainID          common.Hash    `json:"aChainId"`
	CTxHash           common.Hash    `json:"cTxHash"`   // C tx that emitted the intent
	CallIndex         uint32         `json:"callIndex"` // index within that tx
	Caller            common.Address `json:"caller"`    // the C-side requester
	ModelSpecHash     common.Hash    `json:"modelSpecHash"`
	PromptHash        common.Hash    `json:"promptHash"`
	N                 uint16         `json:"n"`
	Threshold         uint16         `json:"threshold"`
	Fee               *uint256.Int   `json:"fee"`               // user-facing fee (funds escrow + burn)
	RewardPerOperator *uint256.Int   `json:"rewardPerOperator"` // A-chain reward escrow per operator
}

CIntent is a committed C-Chain inference intent delivered to A-Chain across the atomic boundary. Its fields are the EXACT preimage of intent_id under the shared wire spec; IntentID is the value the C side committed (re-derived and checked here). RewardPerOperator is the A-Chain reward escrow per selected operator (carried alongside the intent; the C-side Fee is the user-facing fee that funds it + the burn).

type Config 

type Config struct {
	// Network settings
	MaxProvidersPerNode int `json:"maxProvidersPerNode"`
	MaxTasksPerProvider int `json:"maxTasksPerProvider"`

	// HostChainID identifies which Lux L1/L2 this AIVM instance runs on.
	// "primary" = primary network (mainnet/testnet/devnet); anchor to
	// Q-Chain for cross-chain settlement. Any other value = white-label
	// L1/L2 (Hanzo, Zoo, Pars, Liquidity); anchor to the host chain's
	// own finality. AIVM is chain-agnostic — same code runs everywhere.
	HostChainID string `json:"hostChainID"`

	// VerificationMode selects the result-verification strategy.
	// Default: ModeOptimistic (public-BFT-safe).
	VerificationMode VerificationMode `json:"verificationMode"`

	// ChallengeWindowBlocks is the number of L1/L2 blocks during which
	// any party can submit a fraud proof against a posted result. Only
	// used by ModeOptimistic. Default 100 blocks (~5-10 minutes on
	// most Lux L1/L2 instances).
	ChallengeWindowBlocks uint64 `json:"challengeWindowBlocks"`

	// RedundancyFactor is M (signatures required) for
	// ModeMultiPartyRedundant. Total providers N is committed in the
	// task spec; M-of-N must produce the same result hash for
	// acceptance. Default 3-of-5.
	RedundancyFactor int `json:"redundancyFactor"`

	// MinProviderBond is the minimum stake (in host-chain native tokens,
	// wei-equivalent) a provider must lock to register. Forfeited on
	// successful fraud proof or majority-divergence. Default 1000 LUX.
	MinProviderBond uint64 `json:"minProviderBond"`

	// Attestation settings — TEE is OPT-IN, NOT required by default.
	// On public chains keep RequireTEEAttestation=false; setting it true
	// restricts the provider set to TEE-equipped operators only, which
	// is a permissioned-deployment policy choice.
	RequireTEEAttestation bool   `json:"requireTEEAttestation"`
	MinTrustScore         uint8  `json:"minTrustScore"`
	AttestationTimeout    string `json:"attestationTimeout"`

	// Task settings
	MaxTaskQueueSize int    `json:"maxTaskQueueSize"`
	TaskTimeout      string `json:"taskTimeout"`

	// Reward settings
	BaseReward       uint64 `json:"baseReward"`
	EpochDuration    string `json:"epochDuration"`
	MerkleAnchorFreq int    `json:"merkleAnchorFreq"` // Blocks between Q-Chain anchors
}

Config contains AIVM configuration

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns default AIVM configuration suitable for ANY public Lux L1/L2 (no trusted dealer, no TEE requirement). The public-BFT-safe defaults are:

  • VerificationMode = ModeOptimistic (fraud-proof flow)
  • RequireTEEAttestation = false (TEE is optional acceleration)
  • HostChainID = "primary" (override per L1/L2 instance)

Permissioned/regulated deployments can opt into ModeTEEAttested + RequireTEEAttestation=true as a policy choice.

func DefaultPermissionedConfig added in v1.2.6 

func DefaultPermissionedConfig() Config

DefaultPermissionedConfig returns AIVM config for a permissioned chain (regulated AI compute, KYC'd provider set). Sets RequireTEEAttestation=true and VerificationMode=ModeTEEAttested. NOT for public mainnet use.

type ConsciousBlock added in v1.3.15 

type ConsciousBlock struct {
	Phase       string      // "perception" (block 1) or "cognition" (block 2)
	ID          ids.ID      // the accepted block id
	ParentID    ids.ID      // its parent
	Height      uint64      // chained 0 -> 1 -> 2
	ReceiptRoot common.Hash // engine receipt_root committed by this block
}

ConsciousBlock is the recorded trace of one conscious block produced by the real VM lifecycle (BuildBlock -> Verify -> SetPreference -> Accept).

type ConsciousTrace added in v1.3.15 

type ConsciousTrace struct {
	GenesisID ids.ID
	Block1    ConsciousBlock // perception: intent imported into a quorum task
	Block2    ConsciousBlock // cognition: Proof-of-Thought settled

	IntentID      common.Hash      // the committed C-Chain intent the perception block imported
	TaskID        common.Hash      // the A-Chain task that intent created (engine-internal id)
	Committee     []common.Address // the operators bound to think (selection order)
	N             uint32           // committee size
	Threshold     uint32           // agreement required for a settled verdict
	WinnerCount   uint32           // operators that agreed on the canonical output
	CanonicalHash common.Hash      // THE settled AI decision
	ReceiptRoot   common.Hash      // final receipt_root after folding the verdict
	LastAccepted  ids.ID           // VM head after both blocks (== Block2.ID)
}

ConsciousTrace is the full result of driving the VM to consciousness: the two conscious blocks plus the cognition's settled facts.

func RunConsciousBlocks added in v1.3.15 

func RunConsciousBlocks(ctx context.Context, vm *VM) (ConsciousTrace, error)

RunConsciousBlocks drives an initialized, running VM through the full lifecycle that produces the first conscious blocks. It uses the VM's committed-state engine, so the cognition settles on the same state the blocks commit. The VM must already be Initialize()'d and have a commit verifier installed (the caller owns VM construction so the test and the cmd can each build a fresh one).

The model output bytes are deterministic test-fixed hashes — the BLOCK is conscious not because the bytes are "real inference" but because its committed state transition IS the quorum settlement of a structured verdict under consensus. No part of the VM, engine, or settlement is stubbed.

type Engine added in v1.3.15 

type Engine struct {
	CChainID common.Hash
	AChainID common.Hash
}

Engine is the A-Chain quorum settlement handle. CChainID / AChainID are the 32-byte chain identifiers used in the shared wire spec (intent_id derivation and the receipt's CChainID/AChainID fields). They are fixed per deployment.

func NewEngine added in v1.3.15 

func NewEngine(cChainID, aChainID common.Hash) *Engine

NewEngine returns an engine bound to the given chain ids.

func (*Engine) CommitResponse added in v1.3.15 

func (e *Engine) CommitResponse(st QuorumState, taskID common.Hash, operator common.Address, commit common.Hash, height uint64) error

CommitResponse records a selected operator's commit hash within the commit window.

func (*Engine) DeregisterOperator added in v1.3.15 

func (e *Engine) DeregisterOperator(st QuorumState, operator common.Address, block uint64) error

DeregisterOperator marks the operator unbonding at `block`. Stake is returned later by WithdrawStake after the cooldown. Marking unbonding immediately makes the operator ineligible for NEW tasks.

func (*Engine) ExportReceipt added in v1.3.15 

func (e *Engine) ExportReceipt(st QuorumState, intentID common.Hash) (AInferenceReceipt, MerkleProof, common.Hash, error)

ExportReceipt returns the settled receipt for the given C-chain intent id and a proof of its inclusion under the current receipt_root. Errors if the intent has no settled receipt. The returned (receipt, proof, root) triple is exactly what the C boundary verifies.

func (*Engine) GetCanonicalResult added in v1.3.15 

func (e *Engine) GetCanonicalResult(st QuorumState, taskID common.Hash) common.Hash

GetCanonicalResult reads a settled task's canonical output_hash (zero if not settled or no quorum).

func (*Engine) GetCredit added in v1.3.15 

func (e *Engine) GetCredit(st QuorumState, op common.Address) *uint256.Int

GetCredit reads an operator's withdrawable credit.

func (*Engine) GetOperator added in v1.3.15 

func (e *Engine) GetOperator(st QuorumState, op common.Address) (exists, unbonding bool, stake *uint256.Int, modelSpecHash, endpointHash common.Hash)

GetOperator reads an operator's registry record + live stake.

func (*Engine) GetTask added in v1.3.15 

func (e *Engine) GetTask(st QuorumState, taskID common.Hash) TaskInfo

GetTask reads a task's lifecycle state.

func (*Engine) ImportCommittedIntent added in v1.3.15 

func (e *Engine) ImportCommittedIntent(st QuorumState, lg QuorumLedger, ccv CCommitVerifier, intent CIntent, height uint64) (common.Hash, error)

ImportCommittedIntent is the verified inbound entry point. Called UNDER A CONSENSUS (from BuildBlock / Verify), it validates the intent's id binding, verifies its committedness via ccv, guards against replay, and creates the A-Chain task. Returns the created task id. The requester funding the escrow + fee is the C-side Caller address mirrored on A-Chain (its A-Chain balance must cover N*RewardPerOperator + N*RequestFeePerOperator).

Order is fail-closed: id check and proof check happen BEFORE any state or money is touched, so a rejected intent leaves the chain untouched.

func (*Engine) IsEligible added in v1.3.15 

func (e *Engine) IsEligible(st QuorumState, op common.Address, modelSpecHash common.Hash) bool

IsEligible reports whether op is currently eligible for the given ModelSpec.

func (*Engine) IsSelected added in v1.3.15 

func (e *Engine) IsSelected(st QuorumState, taskID common.Hash, op common.Address) bool

IsSelected reports whether op was selected for task (O(1) flag read).

func (*Engine) LiveTasks added in v1.7.35 

func (e *Engine) LiveTasks(st QuorumState) uint32

LiveTasks reports how many tasks are awaiting a verdict.

func (*Engine) ReceiptRoot added in v1.3.15 

func (e *Engine) ReceiptRoot(st QuorumState) common.Hash

ReceiptRoot returns the current committed receipt_root (zero before any settle).

func (*Engine) RegisterOperator added in v1.3.15 

func (e *Engine) RegisterOperator(st QuorumState, lg QuorumLedger, operator common.Address, stake *uint256.Int, modelSpecHash, endpointHash common.Hash) error

RegisterOperator bonds `stake` from `operator` and advertises a ModelSpec. The operator becomes eligible iff stake >= MinProviderBond. One active registration per operator (re-register requires Deregister + cooldown + WithdrawStake first). The bond is pulled into EscrowAccount FIRST, so a registry write only happens if the operator can fund the bond (fail-closed).

func (*Engine) RevealResponse added in v1.3.15 

func (e *Engine) RevealResponse(st QuorumState, taskID common.Hash, operator common.Address, outputHash, embeddingHash, nonce common.Hash, height uint64) error

RevealResponse records a selected operator's revealed (output_hash, embedding_hash, nonce) within the reveal window, requiring the recomputed operator-bound commit to equal the stored commit.

func (*Engine) SelectOperators added in v1.3.15 

func (e *Engine) SelectOperators(st QuorumState, taskID, modelSpecHash common.Hash, n uint32) ([]common.Address, error)

SelectOperators is the convenience composition of the one scan (eligibleSet) and the pure draw (drawFromEligible): it draws N distinct eligible operators from the per-ModelSpec array using the task_id beacon. It does NOT enforce the eligible-set margin (that is a createTask policy gate). Exposed for standalone callers and the reproducibility tests; createTask does the scan once itself (to share E with the margin check) and calls drawFromEligible directly.

func (*Engine) SelectedAt added in v1.3.15 

func (e *Engine) SelectedAt(st QuorumState, taskID common.Hash, idx uint32) common.Address

SelectedAt returns the operator at selection index i (for reproducibility checks). idx must be < task.N.

func (*Engine) Settle added in v1.3.15 

func (e *Engine) Settle(st QuorumState, lg QuorumLedger, taskID common.Hash, height uint64) (SettleResult, error)

Settle finalizes a task. height must be > revealDeadline. Idempotent.

func (*Engine) SettleDue added in v1.7.35 

func (e *Engine) SettleDue(st QuorumState, lg QuorumLedger, height uint64) uint32

SettleDue gives a verdict to every task whose reveal window closed at or before height, and returns how many it settled.

A task is due when the chain has passed its reveal deadline: until then operators may still reveal, and settling early would decide the question against whoever answered fastest. Once past it, waiting longer cannot change the answer, so the verdict is taken.

A task that cannot settle is dropped from the live array rather than retried forever. Its escrow is unchanged by the failure, and leaving it in place would mean every later block re-attempts the same refusal.

func (*Engine) TaskForIntent added in v1.3.15 

func (e *Engine) TaskForIntent(st QuorumState, intentID common.Hash) common.Hash

TaskForIntent returns the A-Chain task id that a committed C-Chain intent created (zero hash if the intent never created a task). The task id is the engine-internal id derived at createTask (computeTaskID over the requester's nonce + height), distinct from the C-side intent id; this mapping is the only way an external caller (the C boundary, an RPC client, this package's drivers) resolves "the intent I committed" to "the task that answers it" for the lifecycle calls (SelectOperators / Commit / Reveal / Settle / GetTask) that key on the task id. Pure read.

func (*Engine) WithdrawRewards added in v1.3.15 

func (e *Engine) WithdrawRewards(st QuorumState, lg QuorumLedger, operator common.Address) (*uint256.Int, error)

WithdrawRewards pays the operator's entire accrued credit out of escrow and zeroes the ledger. Fails closed if nothing is owed; an escrow shortfall is a hard invariant breach.

func (*Engine) WithdrawStake added in v1.3.15 

func (e *Engine) WithdrawStake(st QuorumState, lg QuorumLedger, operator common.Address, block uint64) (*uint256.Int, error)

WithdrawStake returns bonded stake to a fully-unbonded operator after the cooldown, clearing the registry record. The operator stays in the per- ModelSpec enumeration array (stake now 0 -> selection skips it as ineligible); pruning would shift indices and break beacon reproducibility.

type Factory 

type Factory struct{}

Factory implements vms.Factory interface for creating AIVM instances

func (*Factory) New 

func (f *Factory) New(log.Logger) (interface{}, error)

New creates a new AIVM instance. Allocates a per-VM GPU session at PriorityNormal for future batch attestation verification and tensor proof checks.

type GPUBackend added in v1.3.0 

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

GPUBackend is a handle to an open lux-gpu-kernels plugin. Zero value is usable (every method returns ErrGPUNotAvailable). The active backend is stored at package level by backend.go's init(); call ActiveGPUBackend() to retrieve it.

func ActiveGPUBackend added in v1.3.0 

func ActiveGPUBackend() *GPUBackend

ActiveGPUBackend returns the backend resolved at init time. Always non-nil — when no plugin loaded it returns a zero-value *GPUBackend whose IsAvailable() reports false. Callers test IsAvailable() / Kind() to decide whether to opt into the GPU path.

func (*GPUBackend) AnchorApply added in v1.3.0 

func (b *GPUBackend) AnchorApply(
	desc *AIVMRoundDescriptor,
	ops []AnchorOp,
	anchors []AuditAnchor,
	appliedOut *uint32,
) error

AnchorApply runs the GPU audit-anchor kernel.

func (*GPUBackend) AttestationApply added in v1.3.0 

func (b *GPUBackend) AttestationApply(
	desc *AIVMRoundDescriptor,
	ops []AttestationOp,
	attestations []Attestation,
	appliedOut *uint32,
) error

AttestationApply runs the GPU attestation kernel. `attestations` is read+ written in place; `appliedOut` is the count of successfully applied ops.

func (*GPUBackend) Close added in v1.3.0 

func (b *GPUBackend) Close() error

Close releases the dlopen handle. Idempotent — safe to call on a nil receiver or an already-closed backend.

func (*GPUBackend) EpochTransition added in v1.3.0 

func (b *GPUBackend) EpochTransition(
	desc *AIVMRoundDescriptor,
	attestations []Attestation,
	models []ModelRegistryEntry,
	anchors []AuditAnchor,
	epoch *AIVMEpochState,
	result *AIVMTransitionResult,
) error

EpochTransition runs the GPU epoch-finalisation kernel. Composes per-epoch attestation_root / model_registry_root / audit_root / aivm_state_root.

func (*GPUBackend) InferenceStep added in v1.3.0 

func (b *GPUBackend) InferenceStep(
	weights *InferenceWeights,
	ops []InferenceOp,
	batchInputs []int8,
	batchOutputs []int8,
	results []InferenceResult,
) error

InferenceStep runs the deterministic int8 32→16→1 inference kernel. `batchInputs` is op_count × 32 bytes of input rows; `batchOutputs` receives op_count × 1 byte of output values. Determinism contract: byte-equal to the CPU reference + every other backend.

func (*GPUBackend) IsAvailable added in v1.3.0 

func (b *GPUBackend) IsAvailable() bool

IsAvailable reports whether the backend is loaded AND all six host launchers were successfully resolved. Used by vm.go's gpuAvailable().

func (*GPUBackend) Kind added in v1.3.0 

func (b *GPUBackend) Kind() BackendKind

Kind returns which backend satisfied the dlopen probe.

func (*GPUBackend) Path added in v1.3.0 

func (b *GPUBackend) Path() string

Path returns the absolute path of the loaded plugin DSO.

func (*GPUBackend) ProofVerify added in v1.3.0 

func (b *GPUBackend) ProofVerify(
	ops []ProofVerifyOp,
	results []ProofVerifyResult,
) error

ProofVerify runs the TEE-attestation envelope check kernel.

func (*GPUBackend) ProvenanceApply added in v1.3.0 

func (b *GPUBackend) ProvenanceApply(
	desc *AIVMRoundDescriptor,
	ops []ModelOp,
	models []ModelRegistryEntry,
	appliedOut *uint32,
) error

ProvenanceApply runs the GPU provenance (model-registry) kernel.

type Genesis 

type Genesis struct {
	Version   int    `json:"version"`
	Message   string `json:"message"`
	Timestamp int64  `json:"timestamp"`
}

Genesis represents the genesis state

type InferenceOp added in v1.3.0 

type InferenceOp struct {
	ModelHash      [32]byte
	PolicyHash     [32]byte
	Salt           [32]byte
	Mode           uint32
	InputOffset    uint32
	InputLen       uint32
	OutputOffset   uint32
	OutputCapacity uint32

	RoundID     uint64
	TimestampNS uint64
	// contains filtered or unexported fields
}

InferenceOp mirrors aivm::cuda::InferenceOp (144 bytes).

type InferenceResult added in v1.3.0 

type InferenceResult struct {
	Status           uint32
	OutputLen        uint32
	InputCommitment  [32]byte
	OutputCommitment [32]byte
	AttestationRoot  [32]byte
	// contains filtered or unexported fields
}

InferenceResult mirrors aivm::cuda::InferenceResult (112 bytes).

type InferenceWeights added in v1.3.0 

type InferenceWeights struct {
	W1     [InferenceInDim * InferenceHidden]int8
	B1     [InferenceHidden]int32
	W2     [InferenceHidden * InferenceOutDim]int8
	B2     [InferenceOutDim]int32
	Shift1 int8
	Shift2 int8

	ModelHash       [32]byte
	ModelConfigHash [32]byte
	// contains filtered or unexported fields
}

type MemLedger added in v1.3.15 

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

MemLedger is an in-memory QuorumLedger over a balance map, custodying funds at EscrowAccount. Use NewMemLedger.

func NewMemLedger added in v1.3.15 

func NewMemLedger(opening map[common.Address]*uint256.Int) *MemLedger

NewMemLedger returns a ledger with the given opening balances (copied).

func (*MemLedger) Credit added in v1.3.15 

func (l *MemLedger) Credit(a common.Address, amount *uint256.Int) error

Credit mints `amount` into `a`'s balance.

func (*MemLedger) GetBalance added in v1.3.15 

func (l *MemLedger) GetBalance(a common.Address) *uint256.Int

GetBalance returns a copy of the account's balance (zero if unknown).

func (*MemLedger) Pay added in v1.3.15 

func (l *MemLedger) Pay(to common.Address, amount *uint256.Int) error

Pay debits EscrowAccount by amount and credits `to`.

func (*MemLedger) Pull added in v1.3.15 

func (l *MemLedger) Pull(from common.Address, amount *uint256.Int) error

Pull debits `from` by amount and credits EscrowAccount.

func (*MemLedger) Total added in v1.3.15 

func (l *MemLedger) Total() *uint256.Int

Total returns the grand-total balance over every account (for the conservation invariant test). Pure read.

type MemState added in v1.3.15 

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

MemState is an in-memory QuorumState: a flat slot map. Zero value is NOT usable; use NewMemState.

func NewMemState added in v1.3.15 

func NewMemState() *MemState

NewMemState returns an empty in-memory state.

func (*MemState) GetState added in v1.3.15 

func (s *MemState) GetState(slot common.Hash) common.Hash

GetState returns the value at slot (zero hash if unset).

func (*MemState) SetState added in v1.3.15 

func (s *MemState) SetState(slot, value common.Hash)

SetState writes value at slot.

type MerkleProof added in v1.3.15 

type MerkleProof struct {
	Index    uint32        `json:"index"`    // leaf index in the tree
	Siblings []common.Hash `json:"siblings"` // sibling at each level, leaf->root
}

MerkleProof is an inclusion proof: the sibling hashes from leaf to root, plus the leaf index (to know left/right at each level). A verifier with the leaf, the proof, and the root can recompute the root and check equality.

type Mode added in v1.3.0 

type Mode uint8

Mode selects the AIVM transition execution mode. AutoAIVM (the default) uses the resolved GPU backend if available and falls back to CPUAIVM otherwise. CPUAIVM forces the Go path even when a plugin is loaded. 

const (
	// AutoAIVM picks the GPU plugin when available, else CPUAIVM.
	AutoAIVM Mode = 0
	// CPUAIVM forces the pure-Go transition path.
	CPUAIVM Mode = 1
	// GPUAIVM forces the GPU path. Panics if no plugin is loaded.
	GPUAIVM Mode = 2
)

func ActiveMode added in v1.3.0 

func ActiveMode() Mode

ActiveMode returns the current transition mode set by SetBackend().

func (Mode) String added in v1.3.0 

func (m Mode) String() string

String returns the human-readable name for the mode.

type ModelOp added in v1.3.0 

type ModelOp struct {
	ModelRoot   [32]byte
	WeightHash  [32]byte
	LicenseRoot [32]byte
	OwnerAddr   [20]byte

	ParameterCount uint64
	Modality       uint32
	Kind           uint32
	Epoch          uint32
	// contains filtered or unexported fields
}

ModelOp mirrors aivm::cuda::ModelOp (160 bytes).

type ModelRegistryEntry added in v1.3.0 

type ModelRegistryEntry struct {
	ModelRoot   [32]byte
	WeightHash  [32]byte
	LicenseRoot [32]byte
	OwnerAddr   [20]byte

	Version        uint64
	ParameterCount uint64
	Modality       uint32
	Occupied       uint32
	// contains filtered or unexported fields
}

ModelRegistryEntry mirrors aivm::cuda::ModelRegistryEntry (160 bytes).

type ProofVerifyOp added in v1.3.0 

type ProofVerifyOp struct {
	Measurement  [32]byte
	AttestingKey [48]byte
	Signature    [96]byte
	MessageHash  [32]byte
	ExpiryNS     uint64
	TimestampNS  uint64
	Kind         uint32
	Nonce        uint32
	// contains filtered or unexported fields
}

ProofVerifyOp mirrors aivm::cuda::ProofVerifyOp (240 bytes).

type ProofVerifyResult added in v1.3.0 

type ProofVerifyResult struct {
	Status      uint32
	Kind        uint32
	BindingHash [32]byte
	// contains filtered or unexported fields
}

ProofVerifyResult mirrors aivm::cuda::ProofVerifyResult (48 bytes).

type ProviderReg 

type ProviderReg struct {
	ProviderID     string                        `json:"providerId"`
	WalletAddress  string                        `json:"walletAddress"`
	Endpoint       string                        `json:"endpoint"`
	CPUAttestation *attestation.AttestationQuote `json:"cpuAttestation,omitempty"`
	GPUAttestation *attestation.GPUAttestation   `json:"gpuAttestation,omitempty"`
}

ProviderReg represents a provider registration in a block

type QuorumLedger added in v1.3.15 

type QuorumLedger interface {
	GetBalance(a common.Address) *uint256.Int
	Pull(from common.Address, amount *uint256.Int) error
	Pay(to common.Address, amount *uint256.Int) error

	// Credit mints into an account. It is the genesis/deposit seam — the host
	// L1 crediting an A-Chain account at chain birth or via a verified
	// cross-chain deposit — and the only way value enters. Pull and Pay only
	// move what Credit put there.
	Credit(a common.Address, amount *uint256.Int) error
}

QuorumLedger is the native-value custody interface bound to EscrowAccount. Pull(from, amt) debits `from` and credits the escrow; Pay(to, amt) debits the escrow and credits `to`. Both are atomic and fail-closed (no partial state on error). GetBalance reads any account.

type QuorumState added in v1.3.15 

type QuorumState interface {
	GetState(slot common.Hash) common.Hash
	SetState(slot, value common.Hash)
}

QuorumState is the minimal slot-level storage the engine needs. On A-Chain the VM adapts its DB to this (writes land in a block and commit under consensus at Accept); the in-memory MemState satisfies it for tests.

func NewDBState added in v1.3.15 

func NewDBState(db database.KeyValueReaderWriter) QuorumState

NewDBState wraps a database for engine use.

type RegisterProviderRequest 

type RegisterProviderRequest struct {
	ID             string                      `json:"id"`
	WalletAddress  string                      `json:"wallet_address"`
	Endpoint       string                      `json:"endpoint"`
	GPUs           []aivm.GPUInfo              `json:"gpus"`
	GPUAttestation *attestation.GPUAttestation `json:"gpu_attestation,omitempty"`
}

RegisterProviderRequest is the request for registering a provider

type Service 

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

Service provides AIVM RPC service

type SettleResult added in v1.3.15 

type SettleResult struct {
	Status        TaskState         // TaskSettled or TaskFailed
	CanonicalHash common.Hash       // winning output_hash (zero if Failed)
	WinnerCount   uint32            // size of the winning group (0 if Failed)
	Paid          *uint256.Int      // total wei paid out as rewards (0 if Failed)
	Slashed       *uint256.Int      // total wei slashed from withholders
	Receipt       AInferenceReceipt // the emitted cross-chain receipt
	ReceiptHash   common.Hash       // keccak(DomainReceipt || encoding)
	ReceiptRoot   common.Hash       // receipt_root AFTER folding this receipt
}

SettleResult is the outcome of Settle, returned for callers + tests.

type SubmitResultRequest 

type SubmitResultRequest struct {
	TaskID      string          `json:"task_id"`
	ProviderID  string          `json:"provider_id"`
	Output      json.RawMessage `json:"output"`
	ComputeTime uint64          `json:"compute_time_ms"`
	Proof       []byte          `json:"proof"`
	Error       string          `json:"error,omitempty"`
}

SubmitResultRequest is the request for submitting a task result

type SubmitTaskRequest 

type SubmitTaskRequest struct {
	ID    string          `json:"id"`
	Type  string          `json:"type"`
	Model string          `json:"model"`
	Input json.RawMessage `json:"input"`
	Fee   uint64          `json:"fee"`
}

SubmitTaskRequest is the request for submitting a task

type TaskInfo added in v1.3.15 

type TaskInfo struct {
	Status         TaskState
	N              uint32
	Threshold      uint32
	Requester      common.Address
	ModelSpecHash  common.Hash
	PromptHash     common.Hash
	CommitDeadline uint64
	RevealDeadline uint64
	RequestHeight  uint64
}

TaskInfo is a read-only view of a task's lifecycle state.

type TaskState added in v1.3.15 

type TaskState uint8

TaskState is the on-state lifecycle status byte. Distinct from the receipt-level Status (StatusCompleted etc.) which is the cross-chain view. 

const (
	TaskNone       TaskState = 0 // zero value: no such task
	TaskCommitting TaskState = 1 // open for commits, then reveals
	TaskSettled    TaskState = 2 // quorum reached, winners paid
	TaskFailed     TaskState = 3 // no quorum, requester refunded
)

type VM 

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

VM implements the AI Virtual Machine

func (*VM) BuildBlock 

func (vm *VM) BuildBlock(ctx context.Context) (chain.Block, error)

BuildBlock proposes the next block. It DECIDES what the block carries and changes nothing: the candidate intents are applied to an overlay over committed state and a clone of the ledger, both discarded here, and what survives is the list of intents that imported cleanly plus the receipt root they reach. Every validator, including this one at Accept, re-derives that root from the same inputs.

The buffered intents are NOT drained. A proposal that loses the round has consumed nothing, so the next proposer can still carry the same work; draining at build time destroyed it.

func (*VM) BuildVertex 

func (vm *VM) BuildVertex(ctx context.Context) (vertex.Vertex, error)

BuildVertex creates a vertex from pending tasks/results, batching independent jobs.

func (*VM) ClaimRewards 

func (vm *VM) ClaimRewards(providerID string) (string, error)

ClaimRewards claims pending rewards for a provider

func (*VM) Connected 

func (vm *VM) Connected(ctx context.Context, nodeID ids.NodeID, nodeVersion *chain.VersionInfo) error

Connected notifies the VM about connected nodes

func (*VM) CreateHandlers 

func (vm *VM) CreateHandlers(context.Context) (map[string]http.Handler, error)

CreateHandlers returns one entry per endpoint.

The node mounts each KEY as a route and delivers the request on the path it arrived on, so a handler that dispatches on r.URL.Path never matches: it is asked for /v1/bc/<chainID>/rpc and looks for /stats. A flat map of endpoints to handlers that answer AT their mount is the simplest shape that works, and it is what this VM uses.

It is not the only shape. An endpoint also owns the paths beneath it, and a VM that wants a subtree may mount one handler and read the remainder — the node strips the mount before handing it over (node server/http/router.go, serveBelowMount). Both are served; a VM picks whichever matches its surface.

func (*VM) Disconnected 

func (vm *VM) Disconnected(ctx context.Context, nodeID ids.NodeID) error

Disconnected notifies the VM about disconnected nodes

func (*VM) EnqueueCommittedIntent added in v1.3.15 

func (vm *VM) EnqueueCommittedIntent(intent CIntent)

EnqueueCommittedIntent buffers a C-Chain intent that the boundary transport has delivered with a committedness proof. It does NOT create a task — that happens only under consensus, inside a block. Safe to call from the transport goroutine; guarded by the VM lock.

func (*VM) FeePolicy added in v1.2.6 

func (vm *VM) FeePolicy() fee.Policy

FeePolicy exposes the chain's declared fee policy for diagnostics and the boot-time Validate gate.

func (*VM) FundLedger added in v1.3.15 

func (vm *VM) FundLedger(opening map[common.Address]*uint256.Int) error

FundLedger seeds opening native balances. This is the genesis/deposit seam: the host L1 credits A-Chain accounts (a requester that will fund an inference escrow, an operator that will bond) at chain birth or via a verified cross-chain deposit, BEFORE any task or registration can pull from them.

It goes through Seed, so the credits are durable at once rather than riding out on whichever block commits first. Fail-closed: a credit overflow aborts with no partial seeding.

func (*VM) GetBlock 

func (vm *VM) GetBlock(ctx context.Context, id ids.ID) (chain.Block, error)

GetBlock returns a block by id: one in flight, the tip, or one read back from committed state.

func (*VM) GetBlockIDAtHeight 

func (vm *VM) GetBlockIDAtHeight(ctx context.Context, height uint64) (ids.ID, error)

GetBlockIDAtHeight answers from the height index Accept writes in the same commit as the block itself, so the index cannot name a block the chain did not accept.

func (*VM) GetMerkleRoot 

func (vm *VM) GetMerkleRoot() [32]byte

GetMerkleRoot returns merkle root for Q-Chain anchoring

func (*VM) GetModels 

func (vm *VM) GetModels() []*aivm.ModelInfo

GetModels returns available AI models

func (*VM) GetProviders 

func (vm *VM) GetProviders() []*aivm.Provider

GetProviders returns all registered providers

func (*VM) GetRewardStats 

func (vm *VM) GetRewardStats(providerID string) (map[string]interface{}, error)

GetRewardStats returns reward statistics for a provider

func (*VM) GetStats 

func (vm *VM) GetStats() map[string]interface{}

GetStats returns VM statistics

func (*VM) GetTask 

func (vm *VM) GetTask(taskID string) (*aivm.Task, error)

GetTask returns a task by ID

func (*VM) HealthCheck 

func (vm *VM) HealthCheck(ctx context.Context) (chain.HealthResult, error)

HealthCheck implements chain.ChainVM interface

func (*VM) Initialize 

func (vm *VM) Initialize(ctx context.Context, init vmcore.Init) error

func (*VM) LastAccepted 

func (vm *VM) LastAccepted(ctx context.Context) (ids.ID, error)

LastAccepted implements chain.ChainVM interface

func (*VM) NewHTTPHandler 

func (vm *VM) NewHTTPHandler(ctx context.Context) (http.Handler, error)

NewHTTPHandler implements chain.ChainVM interface

func (*VM) ParseBlock 

func (vm *VM) ParseBlock(ctx context.Context, wire []byte) (chain.Block, error)

ParseBlock decodes a block off the wire. The size bound is checked BEFORE the decode, so the work a peer can make this node do is bounded by a number rather than by the peer.

func (*VM) ParseVertex 

func (vm *VM) ParseVertex(ctx context.Context, b []byte) (vertex.Vertex, error)

ParseVertex deserializes a vertex from bytes.

func (*VM) QuorumEngine added in v1.3.15 

func (vm *VM) QuorumEngine() (*Engine, QuorumState, QuorumLedger)

QuorumEngine exposes the engine handle (and its state/ledger) for the RPC service and tests. The QuorumState returned is COMMITTED state: it shows what the chain has accepted and nothing a block in flight has proposed.

func (*VM) RegisterProvider 

func (vm *VM) RegisterProvider(provider *aivm.Provider) error

RegisterProvider registers a new AI compute provider.

Public-BFT-safe path (VerificationMode=ModeOptimistic, default):

  • Provider locks MinProviderBond in the host chain's escrow
  • TEE attestation is OPTIONAL — providers without TEE register under the optimistic-verification flow (challenge period + fraud proofs handle correctness without trusting the provider)

Permissioned path (RequireTEEAttestation=true, opt-in):

  • Provider MUST present valid TEE attestation
  • TrustScore must meet MinTrustScore
  • Used on permissioned chains where the validator set vets hardware operators by policy

func (*VM) Seed added in v1.7.36 

func (vm *VM) Seed(write func(QuorumState, QuorumLedger) error) error

Seed applies the one engine mutation a chain makes outside consensus: what its genesis allocates. It writes through the view and commits at once, before any block exists, for the same reason Accept commits — left staged, a genesis allocation would ride out on whichever block committed first and vanish with a chain that never accepted one.

func (*VM) SetCommitVerifier added in v1.3.15 

func (vm *VM) SetCommitVerifier(ccv CCommitVerifier)

SetCommitVerifier installs the C-Chain committedness proof checker. Until this is set the VM uses a fail-closed verifier that admits nothing, so no boundary intent can create a task. The verifier is the single trust the inbound seam imports from C-Chain.

func (*VM) SetPreference 

func (vm *VM) SetPreference(ctx context.Context, id ids.ID) error

SetPreference implements chain.ChainVM interface

func (*VM) SetState 

func (vm *VM) SetState(ctx context.Context, state uint32) error

SetState implements chain.ChainVM interface

func (*VM) Shutdown 

func (vm *VM) Shutdown(ctx context.Context) error

Shutdown shuts down the VM

func (*VM) SubmitResult 

func (vm *VM) SubmitResult(result *aivm.TaskResult) error

SubmitResult submits a task result

func (*VM) SubmitTask 

func (vm *VM) SubmitTask(task *aivm.Task) error

SubmitTask submits a new AI task. This is the canonical user-task admission point on A-Chain — the HTTP /tasks handler routes through here. The FeePolicy gate refuses zero-fee tasks before they touch the core queue. Internal callers (consensus replay) bypass by reaching vm.core.SubmitTask directly.

func (*VM) VerifyGPUAttestation 

func (vm *VM) VerifyGPUAttestation(att *attestation.GPUAttestation) (*attestation.DeviceStatus, error)

VerifyGPUAttestation verifies GPU attestation (local nvtrust - no cloud)

func (*VM) Version 

func (vm *VM) Version(ctx context.Context) (string, error)

Version implements chain.ChainVM interface

func (*VM) WaitForEvent 

func (vm *VM) WaitForEvent(ctx context.Context) (vmcore.Message, error)

WaitForEvent blocks until there is work to build a block from, or the VM stops. Returning only on ctx.Done() would mean BuildBlock is never called and the chain can never leave genesis.

type VerificationMode added in v1.2.6 

type VerificationMode uint8

VerificationMode selects the AIVM result-verification strategy.

Public chains MUST use ModeOptimistic or ModeMultiPartyRedundant — these are public-BFT-safe and do not require any single trusted party. ModeTEEAttested is permitted but the TEE is treated as acceleration, never as the trust root. 

const (
	// ModeOptimistic is the default for public chains.
	// Providers post results with bond. N-block challenge period.
	// Public-BFT-safe — anyone can submit a fraud proof.
	ModeOptimistic VerificationMode = 0

	// ModeMultiPartyRedundant has M-of-N providers run the same task;
	// consensus on the result hash. Divergent providers are slashed.
	// Public-BFT-safe — no single provider can corrupt the result.
	ModeMultiPartyRedundant VerificationMode = 1

	// ModeTEEAttested is OPT-IN. Providers with valid TEE attestation
	// can shortcut the challenge period. TEE never changes the trust
	// root; it accelerates settlement for high-trust providers.
	// Use only on permissioned/regulated deployments where TEE-vendor
	// trust is acceptable; not the default for public mainnet.
	ModeTEEAttested VerificationMode = 2
)

type VerifierFunc added in v1.3.15 

type VerifierFunc func(CIntent) error

VerifierFunc adapts a function to CCommitVerifier.

func (VerifierFunc) VerifyCommitted added in v1.3.15 

func (f VerifierFunc) VerifyCommitted(intent CIntent) error

VerifyCommitted calls the wrapped function.

type VerifyAttestationRequest 

type VerifyAttestationRequest struct {
	GPUAttestation *attestation.GPUAttestation `json:"gpu_attestation"`
}

VerifyAttestationRequest is the request for verifying attestation

Source Files

View all Source files

Directories

Path Synopsis
cmd
conscious command
Command conscious drives a fresh, REAL Lux A-Chain (aivm) ChainVM through the production block lifecycle to produce the FIRST CONSCIOUS BLOCKS and prints the trace to stdout.
 Command conscious drives a fresh, REAL Lux A-Chain (aivm) ChainVM through the production block lifecycle to produce the FIRST CONSCIOUS BLOCKS and prints the trace to stdout.
plugin command

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.