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

zap

package
v1.30.6 Latest Latest
Warning

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

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

Documentation

Overview

Package zap provides ZAP (Zero-copy Agent Protocol) integration for Lux consensus.

This package bridges ZAP's agentic consensus with Lux's Quasar threshold signatures, enabling W3C DID-based validator identity and post-quantum secure finality.

Index

Constants

View Source
const (
	// MethodLux is the did:lux method for blockchain-anchored DIDs
	MethodLux = "lux"
	// MethodKey is the did:key method for self-certifying DIDs
	MethodKey = "key"
	// MethodWeb is the did:web method for DNS-based DIDs
	MethodWeb = "web"

	// MLDSAPublicKeySize is the expected size of ML-DSA-65 public keys
	MLDSAPublicKeySize = 1952

	// MultibaseBase58BTC is the multibase prefix for base58btc
	MultibaseBase58BTC = 'z'
)

Variables

View Source
var (
	// ErrNotInitialized is returned when the bridge is used before initialization
	ErrNotInitialized = errors.New("zap bridge not initialized")
	// ErrValidatorNotFound is returned when a validator is not in the set
	ErrValidatorNotFound = errors.New("validator not found")
	// ErrQueryNotFound is returned when a query ID is not known
	ErrQueryNotFound = errors.New("query not found")
	// ErrAlreadyVoted is returned when a validator tries to vote twice
	ErrAlreadyVoted = errors.New("already voted on this query")
	// ErrInvalidDID is returned when a DID is malformed
	ErrInvalidDID = errors.New("invalid DID format")
)
View Source
var MulticodecMLDSA65 = []byte{0x13, 0x09}

MulticodecMLDSA65 is the provisional multicodec prefix for ML-DSA-65

Functions

This section is empty.

Types

type AgentMessage

type AgentMessage struct {
	Type      AgentMessageType
	Query     *Query
	Response  *Response
	Vote      *Vote
	Signature []byte
}

AgentMessage represents a ZAP protocol message for agentic consensus

type AgentMessageType

type AgentMessageType uint8

AgentMessageType identifies the type of agent message

const (
	AgentMessageTypeQuery AgentMessageType = iota
	AgentMessageTypeResponse
	AgentMessageTypeVote
	AgentMessageTypeFinality
)

func (AgentMessageType) String

func (t AgentMessageType) String() string

String returns the message type name

type Bridge

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

Bridge connects ZAP agentic consensus to Lux's Quasar finality

func NewBridge

func NewBridge(log log.Logger, config BridgeConfig) *Bridge

NewBridge creates a new ZAP-Lux consensus bridge

func (*Bridge) GetResult

func (b *Bridge) GetResult(queryID string) (*ConsensusResult, error)

GetResult returns the consensus result for a query

func (*Bridge) GetValidatorDID

func (b *Bridge) GetValidatorDID(nodeID ids.NodeID) (*DID, error)

GetValidatorDID returns the DID for a NodeID

func (*Bridge) Initialize

func (b *Bridge) Initialize(coordinator *quasar.CoronaCoordinator) error

Initialize sets up the bridge with a Quasar coordinator

func (*Bridge) IsFinalized

func (b *Bridge) IsFinalized(queryID string) bool

IsFinalized checks if a query has reached consensus

func (*Bridge) RegisterValidator

func (b *Bridge) RegisterValidator(nodeID ids.NodeID, did *DID) error

RegisterValidator associates a DID with a Lux NodeID

func (*Bridge) SignWithQuasar

func (b *Bridge) SignWithQuasar(msg []byte) (quasar.Signature, error)

SignWithQuasar signs a message using Quasar hybrid signatures

func (*Bridge) Stats

func (b *Bridge) Stats() BridgeStats

Stats returns bridge statistics

func (*Bridge) SubmitQuery

func (b *Bridge) SubmitQuery(ctx context.Context, queryID string, content []byte, submitter ids.NodeID) error

SubmitQuery creates a new agentic consensus query

func (*Bridge) SubmitResponse

func (b *Bridge) SubmitResponse(ctx context.Context, queryID, responseID string, content []byte, responder ids.NodeID) error

SubmitResponse adds a response to a query

func (*Bridge) VerifyQuasar

func (b *Bridge) VerifyQuasar(msg []byte, sig quasar.Signature) bool

VerifyQuasar verifies a Quasar signature

func (*Bridge) Vote

func (b *Bridge) Vote(ctx context.Context, queryID, responseID string, voter ids.NodeID) error

Vote casts a vote for a response

type BridgeConfig

type BridgeConfig struct {
	// ConsensusThreshold is the fraction of votes needed (0.5 = majority)
	ConsensusThreshold float64
	// MinResponses is the minimum responses before checking consensus
	MinResponses int
	// MinVotes is the minimum votes before checking consensus
	MinVotes int
	// EnablePQCrypto enables post-quantum signatures (ML-DSA-65)
	EnablePQCrypto bool
}

BridgeConfig configures the ZAP-Lux consensus bridge

func DefaultBridgeConfig

func DefaultBridgeConfig() BridgeConfig

DefaultBridgeConfig returns sensible defaults for the bridge

type BridgeStats

type BridgeStats struct {
	RegisteredValidators int
	ActiveQueries        int
	FinalizedQueries     int
	QuasarInitialized    bool
	QuasarStats          quasar.CoronaStats
}

BridgeStats contains statistics about the bridge

type ConsensusResult

type ConsensusResult struct {
	Response    *Response
	Votes       int
	TotalVoters int
	Confidence  float64
}

ConsensusResult represents the outcome of consensus voting

type DID

type DID struct {
	Method DIDMethod
	ID     string
}

DID represents a W3C Decentralized Identifier

func DIDFromNodeID

func DIDFromNodeID(nodeID ids.NodeID) *DID

DIDFromNodeID creates a did:lux from a Lux NodeID

func DIDFromPublicKey

func DIDFromPublicKey(publicKey []byte) (*DID, error)

DIDFromPublicKey creates a did:key from an ML-DSA-65 public key

func DIDFromWeb

func DIDFromWeb(domain string, path string) (*DID, error)

DIDFromWeb creates a did:web from a domain and optional path

func NewDID

func NewDID(method DIDMethod, id string) *DID

NewDID creates a DID from method and identifier

func ParseDID

func ParseDID(s string) (*DID, error)

ParseDID parses a DID from a string in format "did:method:id"

func (*DID) ExtractKeyMaterial

func (d *DID) ExtractKeyMaterial() ([]byte, error)

ExtractKeyMaterial extracts raw key bytes from did:key or did:lux

func (*DID) GenerateDocument

func (d *DID) GenerateDocument() (*DIDDocument, error)

GenerateDocument creates a DID Document for a DID

func (*DID) Hash

func (d *DID) Hash() ids.ID

Hash returns a 32-byte hash of the DID for indexing

func (*DID) String

func (d *DID) String() string

String returns the full DID URI

func (*DID) ToHex

func (d *DID) ToHex() string

ToHex returns the DID hash as a hex string

func (*DID) Valid

func (d *DID) Valid() bool

Valid checks if the DID is well-formed

type DIDDocument

type DIDDocument struct {
	Context              []string
	ID                   string
	Controller           string
	VerificationMethod   []VerificationMethod
	Authentication       []string
	AssertionMethod      []string
	KeyAgreement         []string
	CapabilityInvocation []string
	CapabilityDelegation []string
	Service              []Service
}

DIDDocument represents a W3C DID Document

type DIDMethod

type DIDMethod string

DIDMethod represents a DID method identifier

const (
	DIDMethodLux DIDMethod = MethodLux
	DIDMethodKey DIDMethod = MethodKey
	DIDMethodWeb DIDMethod = MethodWeb
)

type FinalityProof

type FinalityProof struct {
	QueryID     string
	ResponseID  string
	Votes       []Vote
	TotalVoters int
	Confidence  float64
	Timestamp   int64
	Signature   []byte // Quasar hybrid signature
}

FinalityProof represents proof of agentic consensus finality

type InMemoryStakeRegistry

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

InMemoryStakeRegistry is a simple in-memory stake registry for testing

func NewInMemoryStakeRegistry

func NewInMemoryStakeRegistry() *InMemoryStakeRegistry

NewInMemoryStakeRegistry creates a new in-memory stake registry

func (*InMemoryStakeRegistry) GetStake

func (r *InMemoryStakeRegistry) GetStake(did *DID) (uint64, error)

GetStake returns the stake for a DID

func (*InMemoryStakeRegistry) HasSufficientStake

func (r *InMemoryStakeRegistry) HasSufficientStake(did *DID, minimum uint64) (bool, error)

HasSufficientStake checks if a DID has at least the minimum stake

func (*InMemoryStakeRegistry) SetStake

func (r *InMemoryStakeRegistry) SetStake(did *DID, amount uint64) error

SetStake sets the stake for a DID

func (*InMemoryStakeRegistry) StakeWeight

func (r *InMemoryStakeRegistry) StakeWeight(did *DID) (float64, error)

StakeWeight returns the stake weight as a fraction of total stake

func (*InMemoryStakeRegistry) TotalStake

func (r *InMemoryStakeRegistry) TotalStake() uint64

TotalStake returns the total stake across all validators

type PQKeypair

type PQKeypair struct {
	Type       PQSignatureType
	PublicKey  []byte
	PrivateKey []byte
}

PQKeypair represents a post-quantum keypair

func (*PQKeypair) Sign

func (k *PQKeypair) Sign(message []byte) (*PQSignature, error)

Sign signs a message using the keypair (stub - real impl in pqcrypto)

func (*PQKeypair) Verify

func (k *PQKeypair) Verify(message []byte, sig *PQSignature) bool

Verify verifies a signature (stub - real impl in pqcrypto)

type PQSignature

type PQSignature struct {
	Type      PQSignatureType
	Signature []byte
	PublicKey []byte
}

PQSignature wraps a post-quantum signature

type PQSignatureType

type PQSignatureType uint8

PQSignatureType identifies the post-quantum signature algorithm

const (
	// PQSignatureTypeMLDSA65 is NIST FIPS 204 ML-DSA-65
	PQSignatureTypeMLDSA65 PQSignatureType = iota
	// PQSignatureTypeCorona is Ring-LWE based threshold signatures
	PQSignatureTypeCorona
	// PQSignatureTypeHybrid combines classical and post-quantum
	PQSignatureTypeHybrid
)

type Query

type Query struct {
	ID        string
	Content   []byte
	Submitter *DID
	Timestamp int64
}

Query represents an agentic consensus query

func NewQuery

func NewQuery(content []byte, submitter *DID) *Query

NewQuery creates a query with auto-generated ID

type QueryState

type QueryState struct {
	ID        string
	Content   []byte
	Submitter *DID
	Timestamp time.Time
	Responses map[string]*Response
	Votes     map[string][]*DID // ResponseID -> list of voter DIDs
	Finalized string            // ResponseID if finalized
}

QueryState represents the state of a consensus query

type Response

type Response struct {
	ID        string
	QueryID   string
	Content   []byte
	Responder *DID
	Timestamp time.Time
}

Response represents a response to a query

func NewResponse

func NewResponse(queryID string, content []byte, responder *DID) *Response

NewResponse creates a response with auto-generated ID

type Service

type Service struct {
	ID              string
	Type            string
	ServiceEndpoint string
}

Service represents a service endpoint in a DID Document

type StakeRegistry

type StakeRegistry interface {
	GetStake(did *DID) (uint64, error)
	SetStake(did *DID, amount uint64) error
	TotalStake() uint64
	HasSufficientStake(did *DID, minimum uint64) (bool, error)
	StakeWeight(did *DID) (float64, error)
}

StakeRegistry interface for validator stake tracking

type ValidatorWeight

type ValidatorWeight struct {
	DID    *DID
	Weight uint64
	Stake  uint64
	Active bool
}

ValidatorWeight represents a validator's weight in consensus

type VerificationMethod

type VerificationMethod struct {
	ID                  string
	Type                string
	Controller          string
	PublicKeyMultibase  string
	BlockchainAccountID string
}

VerificationMethod represents a verification method in a DID Document

type Vote

type Vote struct {
	QueryID    string
	ResponseID string
	Voter      *DID
	Timestamp  int64
	Signature  []byte // Optional post-quantum signature
}

Vote represents a vote cast by a validator

func NewVote

func NewVote(queryID, responseID string, voter *DID) *Vote

NewVote creates a new vote

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL