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
- Variables
- type AgentMessage
- type AgentMessageType
- type Bridge
- func (b *Bridge) GetResult(queryID string) (*ConsensusResult, error)
- func (b *Bridge) GetValidatorDID(nodeID ids.NodeID) (*DID, error)
- func (b *Bridge) Initialize(coordinator *quasar.RingtailCoordinator) error
- func (b *Bridge) IsFinalized(queryID string) bool
- func (b *Bridge) RegisterValidator(nodeID ids.NodeID, did *DID) error
- func (b *Bridge) SignWithQuasar(msg []byte) (quasar.Signature, error)
- func (b *Bridge) Stats() BridgeStats
- func (b *Bridge) SubmitQuery(ctx context.Context, queryID string, content []byte, submitter ids.NodeID) error
- func (b *Bridge) SubmitResponse(ctx context.Context, queryID, responseID string, content []byte, ...) error
- func (b *Bridge) VerifyQuasar(msg []byte, sig quasar.Signature) bool
- func (b *Bridge) Vote(ctx context.Context, queryID, responseID string, voter ids.NodeID) error
- type BridgeConfig
- type BridgeStats
- type ConsensusResult
- type DID
- type DIDDocument
- type DIDMethod
- type FinalityProof
- type InMemoryStakeRegistry
- func (r *InMemoryStakeRegistry) GetStake(did *DID) (uint64, error)
- func (r *InMemoryStakeRegistry) HasSufficientStake(did *DID, minimum uint64) (bool, error)
- func (r *InMemoryStakeRegistry) SetStake(did *DID, amount uint64) error
- func (r *InMemoryStakeRegistry) StakeWeight(did *DID) (float64, error)
- func (r *InMemoryStakeRegistry) TotalStake() uint64
- type PQKeypair
- type PQSignature
- type PQSignatureType
- type Query
- type QueryState
- type Response
- type Service
- type StakeRegistry
- type ValidatorWeight
- type VerificationMethod
- type Vote
Constants ¶
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 ¶
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") )
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 ¶
GetValidatorDID returns the DID for a NodeID
func (*Bridge) Initialize ¶
func (b *Bridge) Initialize(coordinator *quasar.RingtailCoordinator) error
Initialize sets up the bridge with a Quasar coordinator
func (*Bridge) IsFinalized ¶
IsFinalized checks if a query has reached consensus
func (*Bridge) RegisterValidator ¶
RegisterValidator associates a DID with a Lux NodeID
func (*Bridge) SignWithQuasar ¶
SignWithQuasar signs a message using Quasar hybrid signatures
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 ¶
VerifyQuasar verifies a Quasar signature
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.RingtailStats
}
BridgeStats contains statistics about the bridge
type ConsensusResult ¶
ConsensusResult represents the outcome of consensus voting
type DID ¶
DID represents a W3C Decentralized Identifier
func DIDFromNodeID ¶
DIDFromNodeID creates a did:lux from a Lux NodeID
func DIDFromPublicKey ¶
DIDFromPublicKey creates a did:key from an ML-DSA-65 public key
func DIDFromWeb ¶
DIDFromWeb creates a did:web from a domain and optional path
func (*DID) ExtractKeyMaterial ¶
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
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 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
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 // PQSignatureTypeRingtail is Ring-LWE based threshold signatures PQSignatureTypeRingtail // PQSignatureTypeHybrid combines classical and post-quantum PQSignatureTypeHybrid )
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 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 ¶
ValidatorWeight represents a validator's weight in consensus