zap

package
v1.23.1 Latest Latest
Warning

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

Go to latest
Published: Jan 24, 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.RingtailCoordinator) 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.RingtailStats
}

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
	// PQSignatureTypeRingtail is Ring-LWE based threshold signatures
	PQSignatureTypeRingtail
	// 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