discovery

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Apr 13, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package discovery implements gossip-based agent card propagation and peer discovery.

Index

Constants

View Source
const TopicAgentCard = "/lango/agentcard/1.0.0"

TopicAgentCard is the GossipSub topic for agent card propagation.

Variables

This section is empty.

Functions

func CanonicalCardPayload added in v0.7.0

func CanonicalCardPayload(card *GossipCard) ([]byte, error)

CanonicalCardPayload returns the canonical JSON for signing. It clones the card, zeros ONLY Signature and PQSignature, and marshals everything else — including Bundle and PQSignerPublicKey.

func PeerIDFromString

func PeerIDFromString(s string) (peer.ID, error)

PeerIDFromString parses a peer ID string.

func VerifyCardSignature added in v0.7.0

func VerifyCardSignature(card *GossipCard, classicalVerify func(pubkey, message, sig []byte) error) error

VerifyCardSignature verifies the classical + optional PQ signatures on a card. Returns nil if the card is unsigned (backward compat with legacy cards).

Types

type AdService

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

AdService manages agent advertisement and discovery via DHT provider records.

func NewAdService

func NewAdService(cfg AdServiceConfig) *AdService

NewAdService creates a new agent advertisement service.

func (*AdService) Advertise

func (s *AdService) Advertise(ctx context.Context) error

Advertise publishes the local agent ad to the DHT.

func (*AdService) Discover

func (s *AdService) Discover(ctx context.Context, tags []string) ([]*AgentAd, error)

Discover searches for agent ads matching the given tags.

func (*AdService) DiscoverByCapability

func (s *AdService) DiscoverByCapability(ctx context.Context, capability string) []*AgentAd

DiscoverByCapability returns ads matching a specific capability.

func (*AdService) StoreAd

func (s *AdService) StoreAd(ad *AgentAd) error

StoreAd stores a discovered agent ad after ZK credential verification.

type AdServiceConfig

type AdServiceConfig struct {
	DHT      *dht.IpfsDHT
	LocalAd  *AgentAd
	Verifier ZKCredentialVerifier
	Logger   *zap.SugaredLogger
}

AdServiceConfig configures the AdService.

type AgentAd

type AgentAd struct {
	DID            string            `json:"did"`
	Name           string            `json:"name"`
	Description    string            `json:"description"`
	Tags           []string          `json:"tags"`
	Capabilities   []string          `json:"capabilities,omitempty"`
	Pricing        *PricingInfo      `json:"pricing,omitempty"`
	ZKCredentials  []ZKCredential    `json:"zkCredentials,omitempty"`
	OntologyDigest *OntologyDigest   `json:"ontologyDigest,omitempty"`
	Multiaddrs     []string          `json:"multiaddrs,omitempty"`
	PeerID         string            `json:"peerId"`
	Timestamp      time.Time         `json:"timestamp"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

AgentAd is a structured service advertisement (Context Flyer).

type CardSignatureVerifyFunc added in v0.7.0

type CardSignatureVerifyFunc func(pubkey, message, sig []byte) error

CardSignatureVerifyFunc verifies a card's classical signature.

type CardSigner added in v0.7.0

type CardSigner interface {
	Sign(ctx context.Context, payload []byte) ([]byte, error)
	Algorithm() string
}

CardSigner signs gossip card content with a classical algorithm.

type GossipCard

type GossipCard struct {
	Name                 string          `json:"name"`
	Description          string          `json:"description"`
	DID                  string          `json:"did,omitempty"`
	Multiaddrs           []string        `json:"multiaddrs,omitempty"`
	Capabilities         []string        `json:"capabilities,omitempty"`
	Pricing              *PricingInfo    `json:"pricing,omitempty"`
	ZKCredentials        []ZKCredential  `json:"zkCredentials,omitempty"`
	OntologyDigest       *OntologyDigest `json:"ontologyDigest,omitempty"`
	PeerID               string          `json:"peerId"`
	Timestamp            time.Time       `json:"timestamp"`
	Bundle               json.RawMessage `json:"bundle,omitempty"`             // v2: serialized IdentityBundle for DID resolution
	Signature            []byte          `json:"signature,omitempty"`          // classical signature over canonical payload
	SignatureAlgorithm   string          `json:"signatureAlgorithm,omitempty"` // algorithm for classical signature
	PQSignerPublicKey    []byte          `json:"pqSignerPublicKey,omitempty"`  // embedded ML-DSA-65 pubkey for rotation-safe PQ verification
	PQSignature          []byte          `json:"pqSignature,omitempty"`        // ML-DSA-65 signature over canonical payload
	PQSignatureAlgorithm string          `json:"pqSignatureAlgorithm,omitempty"`
}

GossipCard is an agent card propagated via GossipSub.

type GossipConfig

type GossipConfig struct {
	Host            host.Host
	PubSub          *pubsub.PubSub // optional pre-created PubSub instance
	LocalCard       *GossipCard
	Interval        time.Duration
	Verifier        ZKCredentialVerifier
	CardSigner      CardSigner              // optional: sign published cards
	PQCardSigner    PQCardSigner            // optional: PQ dual-sign
	ClassicalVerify CardSignatureVerifyFunc // optional: verify received card signatures
	Logger          *zap.SugaredLogger
}

GossipConfig configures the gossip service.

type GossipService

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

GossipService manages agent card propagation via GossipSub.

func NewGossipService

func NewGossipService(cfg GossipConfig) (*GossipService, error)

NewGossipService creates a new gossip-based discovery service.

func (*GossipService) FindByCapability

func (g *GossipService) FindByCapability(capability string) []*GossipCard

FindByCapability returns peers that advertise the given capability.

func (*GossipService) FindByDID

func (g *GossipService) FindByDID(did string) *GossipCard

FindByDID returns a peer by DID.

func (*GossipService) IsRevoked

func (g *GossipService) IsRevoked(did string) bool

IsRevoked checks if a DID has been revoked.

func (*GossipService) KnownPeers

func (g *GossipService) KnownPeers() []*GossipCard

KnownPeers returns all known peer agent cards.

func (*GossipService) RevokeDID

func (g *GossipService) RevokeDID(did string)

RevokeDID marks a DID as revoked, preventing its credentials from being accepted.

func (*GossipService) SetMaxCredentialAge

func (g *GossipService) SetMaxCredentialAge(d time.Duration)

SetMaxCredentialAge sets the maximum allowed age for ZK credentials.

func (*GossipService) Start

func (g *GossipService) Start(wg *sync.WaitGroup)

Start begins periodic card publication and message processing.

func (*GossipService) Stop

func (g *GossipService) Stop()

Stop halts the gossip service.

type OntologyDigest added in v0.7.0

type OntologyDigest struct {
	SchemaVersion  int      `json:"schemaVersion"`
	Digest         string   `json:"digest"`
	TypeCount      int      `json:"typeCount"`
	PredicateCount int      `json:"predicateCount"`
	TypeNames      []string `json:"typeNames,omitempty"`
}

OntologyDigest is a lightweight summary of an agent's ontology schema, enabling peers to discover ontology-capable agents and assess schema compatibility before initiating heavier exchange protocols.

type PQCardSigner added in v0.7.0

type PQCardSigner interface {
	SignPQ(ctx context.Context, payload []byte) ([]byte, error)
	PQAlgorithm() string
	PQPublicKey() []byte
}

PQCardSigner is an optional interface for PQ dual-signing gossip cards.

type PricingInfo

type PricingInfo struct {
	Currency   string            `json:"currency"`   // e.g. "USDC"
	PerQuery   string            `json:"perQuery"`   // per-query price
	PerMinute  string            `json:"perMinute"`  // per-minute price
	ToolPrices map[string]string `json:"toolPrices"` // per-tool pricing
}

PricingInfo describes the pricing for an agent's services.

type ZKCredential

type ZKCredential struct {
	CapabilityID string    `json:"capabilityId"`
	Proof        []byte    `json:"proof"`
	IssuedAt     time.Time `json:"issuedAt"`
	ExpiresAt    time.Time `json:"expiresAt"`
}

ZKCredential is a zero-knowledge proof of agent capability.

type ZKCredentialVerifier

type ZKCredentialVerifier func(cred *ZKCredential) (bool, error)

ZKCredentialVerifier verifies a ZK credential proof.

Jump to

Keyboard shortcuts

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