zkvm

package
v1.3.21 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2026 License: BSD-3-Clause Imports: 38 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Codec pcodecs.Manager
View Source 
var ErrZWitnessNotImplemented = errors.New("Z-Chain MLDSAStark prover not implemented: needs the MLDSA-rollup AIR + a p3q_prove C ABI (LP-020 §6, paper App. B)")

ErrZWitnessNotImplemented is returned by ZWitnessAdapter.Witness until the MLDSAStark rollup AIR and the p3q prover C ABI ship. The verifier side (STARKVerifier → precompile/starkfri) is already wired; this is the prover-binding gap only.

View Source 
var VMID = ids.ID{'z', 'k', 'v', 'm'}

VMID is the unique identifier for ZKVM (Z-Chain)

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

Functions

func ComputeCommitment 

func ComputeCommitment(note *Note) []byte

ComputeCommitment computes a note commitment

func ComputeNullifier 

func ComputeNullifier(note *Note, spendingKey []byte) []byte

ComputeNullifier computes a nullifier for a note

func EncryptNote 

func EncryptNote(note *Note, recipientPubKey []byte, ephemeralPrivKey []byte, chainID ids.ID, txID ids.ID) ([]byte, []byte, error)

EncryptNote encrypts a note for the recipient using ChaCha20-Poly1305. chainID and txID bind the encryption key to prevent cross-chain/cross-tx reuse.

func NewPrivacyHandler 

func NewPrivacyHandler(vm *VM) http.Handler

NewPrivacyHandler creates the privacy-specific handler

func NewProofHandler 

func NewProofHandler(vm *VM) http.Handler

NewProofHandler creates the proof-specific handler

func NewRPCHandler 

func NewRPCHandler(vm *VM) http.Handler

NewRPCHandler creates the main RPC handler

Types

type AddressManager 

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

AddressManager manages private addresses and viewing keys

func NewAddressManager 

func NewAddressManager(db database.Database, enablePrivate bool, log log.Logger) (*AddressManager, error)

NewAddressManager creates a new address manager

func (*AddressManager) CanDecryptNote 

func (am *AddressManager) CanDecryptNote(ephemeralPubKey []byte, address []byte) bool

CanDecryptNote checks if we have the keys to decrypt a note

func (*AddressManager) Close 

func (am *AddressManager) Close()

Close closes the address manager

func (*AddressManager) DeriveNullifier 

func (am *AddressManager) DeriveNullifier(address []byte, note *Note) ([]byte, error)

DeriveNullifier derives a nullifier using the spending key

func (*AddressManager) GenerateAddress 

func (am *AddressManager) GenerateAddress() (*PrivateAddress, error)

GenerateAddress generates a new private address

func (*AddressManager) GetAddress 

func (am *AddressManager) GetAddress(address []byte) (*PrivateAddress, error)

GetAddress retrieves an address by its public address

func (*AddressManager) GetAddressCount 

func (am *AddressManager) GetAddressCount() uint64

GetAddressCount returns the total number of addresses

func (*AddressManager) GetAddressesByViewingKey 

func (am *AddressManager) GetAddressesByViewingKey(viewingKey []byte) ([]*PrivateAddress, error)

GetAddressesByViewingKey returns all addresses associated with a viewing key

func (*AddressManager) SignTransaction 

func (am *AddressManager) SignTransaction(tx *Transaction, signingAddresses [][]byte) error

SignTransaction signs a transaction with the appropriate keys

type Block 

type Block struct {
	ParentID_      ids.ID         `json:"parentId"`
	BlockHeight    uint64         `json:"height"`
	BlockTimestamp int64          `json:"timestamp"`
	Txs            []*Transaction `json:"transactions"`
	StateRoot      []byte         `json:"stateRoot"` // Merkle tree root of UTXO set

	// Aggregated proof for the block (optional)
	BlockProof *ZKProof `json:"blockProof,omitempty"`

	// Cached values
	ID_ ids.ID
	// contains filtered or unexported fields
}

Block represents a block in the ZK UTXO chain

func (*Block) Accept 

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

Accept accepts the block

func (*Block) Bytes 

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

Bytes returns the block bytes

func (*Block) Height 

func (b *Block) Height() uint64

Height returns the block height

func (*Block) ID 

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

ID returns the block ID

func (*Block) Parent 

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

Parent is an alias for ParentID for compatibility

func (*Block) ParentID 

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

ParentID returns the parent block ID

func (*Block) Reject 

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

Reject rejects the block

func (*Block) Status 

func (b *Block) Status() uint8

Status returns the block status

func (*Block) Timestamp 

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

Timestamp returns the block timestamp

func (*Block) ToSummary 

func (b *Block) ToSummary() *BlockSummary

ToSummary converts a block to a summary

func (*Block) Verify 

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

Verify verifies the block

type BlockSummary 

type BlockSummary struct {
	ID        ids.ID `json:"id"`
	Height    uint64 `json:"height"`
	Timestamp int64  `json:"timestamp"`
	TxCount   int    `json:"txCount"`
	StateRoot []byte `json:"stateRoot"`
}

BlockSummary represents a lightweight block summary

type FHEData 

type FHEData struct {
	// Encrypted computation inputs
	EncryptedInputs [][]byte `json:"encryptedInputs"`

	// Computation circuit
	CircuitID string `json:"circuitId"`

	// Encrypted result
	EncryptedResult []byte `json:"encryptedResult"`

	// Proof of correct computation
	ComputationProof []byte `json:"computationProof"`
}

FHEData represents fully homomorphic encryption data

type FHEProcessor 

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

FHEProcessor handles fully homomorphic encryption operations

func NewFHEProcessor 

func NewFHEProcessor(config ZConfig, log log.Logger) (*FHEProcessor, error)

NewFHEProcessor creates a new FHE processor

func (*FHEProcessor) AddCiphertexts 

func (fp *FHEProcessor) AddCiphertexts(ct1, ct2 []byte) ([]byte, error)

AddCiphertexts performs homomorphic addition

func (*FHEProcessor) DecryptValue 

func (fp *FHEProcessor) DecryptValue(ciphertext []byte, privateKey []byte) (uint64, error)

DecryptValue decrypts an FHE ciphertext

func (*FHEProcessor) EncryptValue 

func (fp *FHEProcessor) EncryptValue(value uint64) ([]byte, error)

EncryptValue encrypts a value using FHE

func (*FHEProcessor) GetStats 

func (fp *FHEProcessor) GetStats() uint64

GetStats returns FHE processing statistics

func (*FHEProcessor) MultiplyCiphertext 

func (fp *FHEProcessor) MultiplyCiphertext(ct []byte, scalar uint64) ([]byte, error)

MultiplyCiphertext performs homomorphic multiplication by a plaintext

func (*FHEProcessor) ProcessFHEComputation 

func (fp *FHEProcessor) ProcessFHEComputation(
	circuitID string,
	encryptedInputs [][]byte,
) ([]byte, []byte, error)

ProcessFHEComputation performs an FHE computation

func (*FHEProcessor) VerifyFHEOperations 

func (fp *FHEProcessor) VerifyFHEOperations(tx *Transaction) error

VerifyFHEOperations verifies FHE operations in a transaction

type Factory 

type Factory struct{}

Factory implements vms.Factory interface for creating Z-Chain VM instances

func (*Factory) New 

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

New implements vms.Factory

type Genesis 

type Genesis struct {
	Timestamp  int64          `json:"timestamp"`
	InitialTxs []*Transaction `json:"initialTransactions,omitempty"`

	// Initial setup parameters
	SetupParams *SetupParams `json:"setupParams,omitempty"`
}

Genesis represents genesis data

func ParseGenesis 

func ParseGenesis(genesisBytes []byte) (*Genesis, error)

ParseGenesis parses genesis bytes (supports both JSON and Codec formats)

type Groth16Proof 

type Groth16Proof struct {
	Ar  bn254.G1Affine // Proof component A
	Bs  bn254.G2Affine // Proof component B
	Krs bn254.G1Affine // Proof component C
}

Groth16Proof represents a Groth16 proof structure

type Groth16VerifyingKey 

type Groth16VerifyingKey struct {
	Alpha bn254.G1Affine   // Alpha in G1
	Beta  bn254.G2Affine   // Beta in G2
	Gamma bn254.G2Affine   // Gamma in G2
	Delta bn254.G2Affine   // Delta in G2
	K     []bn254.G1Affine // K[i] for public inputs
}

Groth16VerifyingKey represents a Groth16 verifying key

type Health 

type Health struct {
	DatabaseHealthy   bool   `json:"databaseHealthy"`
	UTXOCount         uint64 `json:"utxoCount"`
	NullifierCount    uint64 `json:"nullifierCount"`
	LastBlockHeight   uint64 `json:"lastBlockHeight"`
	PendingBlockCount int    `json:"pendingBlockCount"`
	MempoolSize       int    `json:"mempoolSize"`
	ProofCacheSize    int    `json:"proofCacheSize"`
}

Health represents VM health status

type Mempool 

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

Mempool manages pending transactions

func NewMempool 

func NewMempool(maxSize int, log log.Logger) *Mempool

NewMempool creates a new mempool

func (*Mempool) AddTransaction 

func (mp *Mempool) AddTransaction(tx *Transaction) error

AddTransaction adds a transaction to the mempool

func (*Mempool) Clear 

func (mp *Mempool) Clear()

Clear removes all transactions from the mempool

func (*Mempool) GetPendingTransactions 

func (mp *Mempool) GetPendingTransactions(limit int) []*Transaction

GetPendingTransactions returns pending transactions sorted by priority

func (*Mempool) HasNullifier 

func (mp *Mempool) HasNullifier(nullifier []byte) bool

HasNullifier checks if a nullifier is already in the mempool

func (*Mempool) HasTransaction 

func (mp *Mempool) HasTransaction(txID ids.ID) bool

HasTransaction checks if a transaction is in the mempool

func (*Mempool) PruneExpired 

func (mp *Mempool) PruneExpired(currentHeight uint64)

PruneExpired removes expired transactions

func (*Mempool) RemoveTransaction 

func (mp *Mempool) RemoveTransaction(txID ids.ID)

RemoveTransaction removes a transaction from the mempool

func (*Mempool) Size 

func (mp *Mempool) Size() int

Size returns the number of transactions in the mempool

type MempoolTx 

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

MempoolTx represents a transaction in the mempool

type Note 

type Note struct {
	Value      *big.Int `json:"value"`      // Encrypted amount
	Address    []byte   `json:"address"`    // Recipient address
	AssetID    ids.ID   `json:"assetId"`    // Asset type
	Randomness []byte   `json:"randomness"` // Note randomness
	Nullifier  []byte   `json:"nullifier"`  // Computed nullifier
}

Note represents a shielded note (internal representation)

func DecryptNote 

func DecryptNote(encryptedNote []byte, ephemeralPubKey []byte, recipientPrivKey []byte, chainID ids.ID, txID ids.ID) (*Note, error)

DecryptNote decrypts a note using the recipient's key and ChaCha20-Poly1305. chainID and txID must match the values used during encryption.

type NullifierDB 

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

NullifierDB manages spent nullifiers

func NewNullifierDB 

func NewNullifierDB(db database.Database, log log.Logger) (*NullifierDB, error)

NewNullifierDB creates a new nullifier database

func (*NullifierDB) Close 

func (ndb *NullifierDB) Close()

Close closes the nullifier database

func (*NullifierDB) GetNullifierCount 

func (ndb *NullifierDB) GetNullifierCount() uint64

GetNullifierCount returns the total number of spent nullifiers

func (*NullifierDB) GetNullifierHeight 

func (ndb *NullifierDB) GetNullifierHeight(nullifier []byte) (uint64, error)

GetNullifierHeight returns the height when a nullifier was spent

func (*NullifierDB) GetNullifiersByHeight 

func (ndb *NullifierDB) GetNullifiersByHeight(height uint64) [][]byte

GetNullifiersByHeight returns all nullifiers spent at a specific height

func (*NullifierDB) IsNullifierSpent 

func (ndb *NullifierDB) IsNullifierSpent(nullifier []byte) bool

IsNullifierSpent checks if a nullifier has been spent

func (*NullifierDB) MarkNullifierSpent 

func (ndb *NullifierDB) MarkNullifierSpent(nullifier []byte, height uint64) error

MarkNullifierSpent marks a nullifier as spent

func (*NullifierDB) RemoveNullifier 

func (ndb *NullifierDB) RemoveNullifier(nullifier []byte) error

RemoveNullifier removes a nullifier (used for reorg)

type PLONKProof 

type PLONKProof struct {
	// Commitments (7 G1 points)
	LCommit bn254.G1Affine // Wire L commitment
	RCommit bn254.G1Affine // Wire R commitment
	OCommit bn254.G1Affine // Wire O commitment
	ZCommit bn254.G1Affine // Permutation polynomial commitment
	TLow    bn254.G1Affine // Quotient polynomial low
	TMid    bn254.G1Affine // Quotient polynomial mid
	THigh   bn254.G1Affine // Quotient polynomial high

	// Opening proof components
	WzOpening  bn254.G1Affine // Opening at z
	WzwOpening bn254.G1Affine // Opening at z*omega

	// Evaluation proofs (scalars)
	AEval     fr.Element // a(z) evaluation
	BEval     fr.Element // b(z) evaluation
	CEval     fr.Element // c(z) evaluation
	SigmaEval fr.Element // sigma permutation evaluation
	ZEval     fr.Element // z(z*omega) evaluation
}

PLONKProof represents a PLONK proof structure

type PLONKVerifyingKey 

type PLONKVerifyingKey struct {
	// SRS elements
	G1      bn254.G1Affine // Generator in G1
	G2      bn254.G2Affine // Generator in G2
	G2Alpha bn254.G2Affine // [alpha]_2

	// Selector commitments
	QLCommit bn254.G1Affine // Left selector
	QRCommit bn254.G1Affine // Right selector
	QMCommit bn254.G1Affine // Multiplication selector
	QOCommit bn254.G1Affine // Output selector
	QCCommit bn254.G1Affine // Constant selector

	// Permutation commitments
	S1Commit bn254.G1Affine // Sigma_1 permutation
	S2Commit bn254.G1Affine // Sigma_2 permutation
	S3Commit bn254.G1Affine // Sigma_3 permutation

	// Domain parameters
	N      uint64     // Circuit size (power of 2)
	K1, K2 fr.Element // Coset generators
	Omega  fr.Element // Root of unity
}

PLONKVerifyingKey represents a PLONK verifying key

type PrivateAddress 

type PrivateAddress struct {
	Address         []byte `json:"address"`         // Public address (32 bytes)
	ViewingKey      []byte `json:"viewingKey"`      // Viewing key for scanning
	SpendingKey     []byte `json:"spendingKey"`     // Spending key (private)
	Diversifier     []byte `json:"diversifier"`     // Address diversifier
	IncomingViewKey []byte `json:"incomingViewKey"` // For incoming payments only
	CreatedAt       int64  `json:"createdAt"`
}

PrivateAddress represents a private address

type ProofVerifier 

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

ProofVerifier verifies zero-knowledge proofs. When verifying keys are all zeros (dummy), proof verification is disabled and VerifyProof returns an error. This is fail-closed by design.

func NewProofVerifier 

func NewProofVerifier(config ZConfig, log log.Logger) (*ProofVerifier, error)

NewProofVerifier creates a new proof verifier

func (*ProofVerifier) ClearCache 

func (pv *ProofVerifier) ClearCache()

ClearCache clears the proof verification cache

func (*ProofVerifier) GetCacheSize 

func (pv *ProofVerifier) GetCacheSize() int

GetCacheSize returns the current size of the proof cache

func (*ProofVerifier) GetStats 

func (pv *ProofVerifier) GetStats() (verifyCount, cacheHits, cacheMisses uint64)

GetStats returns verifier statistics

func (*ProofVerifier) VerifyBlockProof 

func (pv *ProofVerifier) VerifyBlockProof(block *Block) error

VerifyBlockProof verifies an aggregated block proof. When GPU is available and multiple proofs exist, uses batch MSM acceleration.

func (*ProofVerifier) VerifyTransactionProof 

func (pv *ProofVerifier) VerifyTransactionProof(tx *Transaction) error

VerifyTransactionProof verifies a transaction's zero-knowledge proof. Returns an error if verifying keys are dummy (all zeros).

func (*ProofVerifier) VerifyingKeysLoaded 

func (pv *ProofVerifier) VerifyingKeysLoaded() bool

VerifyingKeysLoaded returns true if real (non-dummy) verifying keys are loaded.

type SetupParams 

type SetupParams struct {
	// Groth16 CRS
	PowersOfTau  []byte `json:"powersOfTau,omitempty"`
	VerifyingKey []byte `json:"verifyingKey,omitempty"`

	// PLONK setup
	PlonkSRS []byte `json:"plonkSRS,omitempty"`

	// FHE parameters
	FHEPublicParams []byte `json:"fhePublicParams,omitempty"`
}

SetupParams contains trusted setup parameters

type ShieldedOutput 

type ShieldedOutput struct {
	// Commitment to the note (amount and address)
	Commitment []byte `json:"commitment"`

	// Encrypted note ciphertext
	EncryptedNote []byte `json:"encryptedNote"`

	// Ephemeral public key for note encryption
	EphemeralPubKey []byte `json:"ephemeralPubKey"`

	// Output proof (rangeproof for amount)
	OutputProof []byte `json:"outputProof"`
}

ShieldedOutput represents a confidential output

type StateTree 

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

StateTree manages a sparse Merkle tree of the UTXO set

func NewStateTree 

func NewStateTree(db database.Database, log log.Logger) (*StateTree, error)

NewStateTree creates a new sparse Merkle tree

func (*StateTree) ApplyTransaction 

func (st *StateTree) ApplyTransaction(tx *Transaction) error

ApplyTransaction applies a transaction to the state tree

func (*StateTree) Close 

func (st *StateTree) Close()

Close closes the state tree

func (*StateTree) ComputeRoot 

func (st *StateTree) ComputeRoot() ([]byte, error)

ComputeRoot computes the new Merkle root after pending changes. Uses GPU-accelerated Poseidon hash when available for ZK-friendly hashing. Falls back to SHA-256 when GPU is unavailable.

func (*StateTree) Finalize 

func (st *StateTree) Finalize(newRoot []byte) error

Finalize commits the pending changes and updates the root

func (*StateTree) GetMerkleProof 

func (st *StateTree) GetMerkleProof(commitment []byte) ([][]byte, error)

GetMerkleProof generates a Merkle proof for a commitment in the sparse Merkle tree

func (*StateTree) GetRoot 

func (st *StateTree) GetRoot() []byte

GetRoot returns the current state root

func (*StateTree) VerifyMerkleProof 

func (st *StateTree) VerifyMerkleProof(commitment []byte, proof [][]byte, root []byte) bool

VerifyMerkleProof verifies a sparse Merkle proof

type Transaction 

type Transaction struct {
	ID      ids.ID          `json:"id"`
	Type    TransactionType `json:"type"`
	Version uint8           `json:"version"`

	// Transparent inputs/outputs (for shield/unshield)
	TransparentInputs  []*TransparentInput  `json:"transparentInputs,omitempty"`
	TransparentOutputs []*TransparentOutput `json:"transparentOutputs,omitempty"`

	// Shielded components
	Nullifiers [][]byte          `json:"nullifiers"` // Spent note nullifiers
	Outputs    []*ShieldedOutput `json:"outputs"`    // New shielded outputs

	// Zero-knowledge proof
	Proof *ZKProof `json:"proof"`

	// FHE operations (optional)
	FHEData *FHEData `json:"fheData,omitempty"`

	// Transaction metadata
	Fee    uint64 `json:"fee"`
	Expiry uint64 `json:"expiry"`         // Block height
	Memo   []byte `json:"memo,omitempty"` // Encrypted memo

	// Signature for transparent components
	Signature []byte `json:"signature,omitempty"`
}

Transaction represents a confidential transaction

func (*Transaction) ComputeID 

func (tx *Transaction) ComputeID() ids.ID

ComputeID computes the transaction ID

func (*Transaction) GetNullifiers 

func (tx *Transaction) GetNullifiers() [][]byte

GetNullifiers returns all nullifiers in the transaction

func (*Transaction) GetOutputCommitments 

func (tx *Transaction) GetOutputCommitments() [][]byte

GetOutputCommitments returns all output commitments

func (*Transaction) HasFHEOperations 

func (tx *Transaction) HasFHEOperations() bool

HasFHEOperations returns true if the transaction includes FHE operations

func (*Transaction) ValidateBasic 

func (tx *Transaction) ValidateBasic() error

ValidateBasic performs basic validation

type TransactionType 

type TransactionType uint8

TransactionType represents the type of transaction 

const (
	TransactionTypeTransfer TransactionType = iota
	TransactionTypeMint
	TransactionTypeBurn
	TransactionTypeShield   // Convert transparent to shielded
	TransactionTypeUnshield // Convert shielded to transparent
)

type TransparentInput 

type TransparentInput struct {
	TxID      ids.ID `json:"txId"`
	OutputIdx uint32 `json:"outputIdx"`
	Amount    uint64 `json:"amount"`
	Address   []byte `json:"address"`
}

TransparentInput represents an unshielded input

type TransparentOutput 

type TransparentOutput struct {
	Amount  uint64 `json:"amount"`
	Address []byte `json:"address"`
	AssetID ids.ID `json:"assetId"`
}

TransparentOutput represents an unshielded output

type TxHeap 

type TxHeap []*MempoolTx

TxHeap implements heap.Interface for priority ordering

func (TxHeap) Len 

func (h TxHeap) Len() int

func (TxHeap) Less 

func (h TxHeap) Less(i, j int) bool

func (*TxHeap) Pop 

func (h *TxHeap) Pop() interface{}

func (*TxHeap) Push 

func (h *TxHeap) Push(x interface{})

func (TxHeap) Swap 

func (h TxHeap) Swap(i, j int)

type UTXO 

type UTXO struct {
	TxID        ids.ID `json:"txId"`
	OutputIndex uint32 `json:"outputIndex"`
	Commitment  []byte `json:"commitment"`  // Output commitment
	Ciphertext  []byte `json:"ciphertext"`  // Encrypted note
	EphemeralPK []byte `json:"ephemeralPK"` // Ephemeral public key
	Height      uint64 `json:"height"`      // Block height when created
}

UTXO represents an unspent transaction output

type UTXODB 

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

UTXODB manages the UTXO set

func NewUTXODB 

func NewUTXODB(db database.Database, log log.Logger) (*UTXODB, error)

NewUTXODB creates a new UTXO database

func (*UTXODB) AddUTXO 

func (udb *UTXODB) AddUTXO(utxo *UTXO) error

AddUTXO adds a new UTXO to the set

func (*UTXODB) Close 

func (udb *UTXODB) Close()

Close closes the UTXO database

func (*UTXODB) GetAllCommitments 

func (udb *UTXODB) GetAllCommitments() [][]byte

GetAllCommitments returns all UTXO commitments (for Merkle tree)

func (*UTXODB) GetUTXO 

func (udb *UTXODB) GetUTXO(commitment []byte) (*UTXO, error)

GetUTXO retrieves a UTXO by commitment

func (*UTXODB) GetUTXOCount 

func (udb *UTXODB) GetUTXOCount() uint64

GetUTXOCount returns the total number of UTXOs

func (*UTXODB) GetUTXOsByHeight 

func (udb *UTXODB) GetUTXOsByHeight(height uint64) ([]*UTXO, error)

GetUTXOsByHeight returns all UTXOs created at a specific height

func (*UTXODB) PruneOldUTXOs 

func (udb *UTXODB) PruneOldUTXOs(minHeight uint64) error

PruneOldUTXOs removes UTXOs older than a certain height

func (*UTXODB) RemoveUTXO 

func (udb *UTXODB) RemoveUTXO(commitment []byte) error

RemoveUTXO removes a UTXO from the set

type VM 

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

VM implements the Zero-Knowledge UTXO Chain VM

func (*VM) BuildBlock 

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

BuildBlock builds a new block

func (*VM) BuildVertex 

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

BuildVertex drains the mempool, batches non-conflicting txs, and returns a vertex.

func (*VM) Connected 

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

func (*VM) CreateHandlers 

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

CreateHandlers returns the VM handlers

func (*VM) CrossChainRequest 

func (vm *VM) CrossChainRequest(ctx context.Context, chainID ids.ID, requestID uint32, deadline time.Time, request []byte) error

CrossChainRequest implements the common.VM interface

func (*VM) CrossChainRequestFailed 

func (vm *VM) CrossChainRequestFailed(ctx context.Context, chainID ids.ID, requestID uint32, appErr *warp.Error) error

CrossChainRequestFailed implements the common.VM interface

func (*VM) CrossChainResponse 

func (vm *VM) CrossChainResponse(ctx context.Context, chainID ids.ID, requestID uint32, response []byte) error

CrossChainResponse implements the common.VM interface

func (*VM) Disconnected 

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

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) GetBlock 

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

GetBlock retrieves a block by ID

func (*VM) GetBlockIDAtHeight 

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

GetBlockIDAtHeight implements the chain.HeightIndexedChainVM interface

func (*VM) Gossip 

func (vm *VM) Gossip(ctx context.Context, nodeID ids.NodeID, msg []byte) error

Gossip implements the common.VM interface

func (*VM) HealthCheck 

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

HealthCheck performs a health check

func (*VM) Initialize 

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

Initialize initializes the VM

func (*VM) LastAccepted 

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

func (*VM) NewHTTPHandler 

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

NewHTTPHandler returns HTTP handlers for the VM

func (*VM) ParseBlock 

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

ParseBlock parses a block from bytes

func (*VM) ParseVertex 

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

ParseVertex deserializes a vertex from bytes.

func (*VM) Request 

func (vm *VM) Request(ctx context.Context, nodeID ids.NodeID, requestID uint32, deadline time.Time, request []byte) error

Request implements the common.VM interface

func (*VM) RequestFailed 

func (vm *VM) RequestFailed(ctx context.Context, nodeID ids.NodeID, requestID uint32, appErr *warp.Error) error

RequestFailed implements the common.VM interface

func (*VM) Response 

func (vm *VM) Response(ctx context.Context, nodeID ids.NodeID, requestID uint32, response []byte) error

Response implements the common.VM interface

func (*VM) SetPreference 

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

Additional interface implementations

func (*VM) SetState 

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

SetState sets the VM state

func (*VM) Shutdown 

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

Shutdown shuts down the VM

func (*VM) StrictPQ added in v1.3.10 

func (vm *VM) StrictPQ() bool

StrictPQ reports whether this Z-Chain instance is on the strict-PQ security profile. It is the single bit that gates both the shielded- proof verifier and the classical-precompile registration.

func (*VM) Version 

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

Version returns the VM version

func (*VM) WaitForEvent 

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

WaitForEvent blocks until an event occurs that should trigger block building

func (*VM) ZKPrecompiles added in v1.3.10 

func (vm *VM) ZKPrecompiles() *precompiles.MapRegistry

ZKPrecompiles returns the registered Z-Chain ZK verifier precompiles. On a strict-PQ chain the classical Groth16 (0x80) / PLONK (0x81) addresses resolve to "no precompile" (fail-closed by absence).

type Vertex 

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

Vertex represents a DAG vertex in the ZK UTXO chain. Conflict key: set of nullifiers spent in the vertex. Two vertices conflict iff their nullifier sets intersect.

func (*Vertex) Accept 

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

func (*Vertex) Bytes 

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

func (*Vertex) Conflicts 

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

Conflicts returns true if this vertex and other share any nullifier.

func (*Vertex) ConflictsVertex 

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

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

func (*Vertex) Epoch 

func (v *Vertex) Epoch() uint32

func (*Vertex) Height 

func (v *Vertex) Height() uint64

func (*Vertex) ID 

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

func (*Vertex) Parents 

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

func (*Vertex) Reject 

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

func (*Vertex) Status 

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

func (*Vertex) Txs 

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

func (*Vertex) Verify 

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

type ZConfig 

type ZConfig struct {
	// Privacy configuration
	EnableConfidentialTransfers bool `serialize:"true" json:"enableConfidentialTransfers"`
	EnablePrivateAddresses      bool `serialize:"true" json:"enablePrivateAddresses"`

	// ZK proof configuration
	ProofSystem      string `serialize:"true" json:"proofSystem"` // groth16, plonk, etc.
	CircuitType      string `serialize:"true" json:"circuitType"` // transfer, mint, burn
	VerifyingKeyPath string `serialize:"true" json:"verifyingKeyPath"`
	TrustedSetupPath string `serialize:"true" json:"trustedSetupPath"`

	// VerifyingKeys supplies real (non-dummy) verifying keys per circuit
	// type (keyed by the TransactionType string), in-memory at genesis.
	// When empty, loadVerifyingKeys installs all-zero dummy keys (proof
	// verification disabled, fail-closed). On a strict-PQ chain, supplying
	// a real bn254 verifying key here is REFUSED at construction
	// (errStrictPQRealVKForbidden) — shielded value uses STARK/FRI only.
	VerifyingKeys map[string][]byte `serialize:"true" json:"verifyingKeys"`

	// StrictPQ HARD-DISABLES the classical (bn254 pairing-based) shielded
	// proof systems on this chain. When true, the shielded-tx ProofVerifier
	// REFUSES groth16/plonk/bulletproofs and accepts ONLY the post-quantum
	// STARK/FRI system (delegated to precompile/starkfri, which fails
	// closed until the prover binding exists). Loading a real (non-dummy)
	// bn254 verifying key on a strict-PQ chain is an ERROR. This is the
	// Lux primary-network posture: a CRQC that breaks bn254 cannot forge a
	// shield/unshield proof to mint or steal shielded value.
	StrictPQ bool `serialize:"true" json:"strictPQ"`

	// FHE configuration
	EnableFHE     bool   `serialize:"true" json:"enableFHE"`
	FHEScheme     string `serialize:"true" json:"fheScheme"`     // BFV, CKKS, etc.
	SecurityLevel uint32 `serialize:"true" json:"securityLevel"` // 128, 192, 256

	// Performance
	MaxUTXOsPerBlock         uint32        `serialize:"true" json:"maxUtxosPerBlock"`
	ProofVerificationTimeout time.Duration `serialize:"true" json:"proofVerificationTimeout"`
	ProofCacheSize           uint32        `serialize:"true" json:"proofCacheSize"`
}

ZConfig contains VM configuration

type ZKProof 

type ZKProof struct {
	ProofType    string   `json:"proofType"` // groth16, plonk, etc.
	ProofData    []byte   `json:"proofData"`
	PublicInputs [][]byte `json:"publicInputs"`
}

ZKProof represents a zero-knowledge proof

type ZWitnessAdapter 

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

ZWitnessAdapter adapts the Z-Chain MLDSAStark prover to the consensus ZWitnessProducer interface used by the Quasar round driver.

TODO(pqz-circuit): implement the MLDSAStark rollup AIR (Goldilocks) and add a `p3q_prove` C ABI to ~/work/lux/p3q, then integrate the prover here. Until then Witness returns ErrZWitnessNotImplemented and the round driver finalizes at the next lower witness level (PolicyQuorum or PolicyPQ). The verifier side is already STARK/FRI.

func NewZWitnessAdapter 

func NewZWitnessAdapter(vm *VM) *ZWitnessAdapter

NewZWitnessAdapter constructs a Z-witness adapter backed by the given Z-Chain VM.

func (*ZWitnessAdapter) Witness 

func (a *ZWitnessAdapter) Witness(ctx context.Context, digest [32]byte, validatorMLDSAPubs [][]byte) ([]byte, error)

Witness produces a post-quantum STARK / FRI proof aggregating per- validator ML-DSA-65 signatures over the round digest. Signature matches consensus/protocol/quasar.ZWitnessProducer.

validatorMLDSAPubs is the canonical ML-DSA-65 public-key list rooted in pchain_validator_root for the round; the STARK circuit takes this list as a public input.

Returns ErrZWitnessNotImplemented today (prover binding outstanding — see the package comment); the round driver treats this as the witness being unavailable and finalizes at the next-lower witness level. We do NOT return fabricated proof bytes: an unsound "proof" on the finality path would be a forgery oracle.

Source Files

View all Source files

Directories

Path Synopsis
cmd
plugin command
Package fhe provides GPU-accelerated FHE operations for the zkvm.
 Package fhe provides GPU-accelerated FHE operations for the zkvm.

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.