Skip to main content

Table of Contents

Module spoon_ai.identity

SpoonOS Agent DID Identity Module Implements ERC-8004 compliant decentralized identity for agents

Module spoon_ai.identity.did_models

DID Data Models for SpoonOS Agents Following W3C DID Core specification and ERC-8004 standard

VerificationMethodType Objects​

class VerificationMethodType(str, Enum)

Supported verification method types

ServiceType Objects​

class ServiceType(str, Enum)

Agent service endpoint types

VerificationMethod Objects​

class VerificationMethod(BaseModel)

Cryptographic verification method for DID authentication

ServiceEndpoint Objects​

class ServiceEndpoint(BaseModel)

Service endpoint for agent interaction

ReputationScore Objects​

class ReputationScore(BaseModel)

Aggregated reputation score

Attestation Objects​

class Attestation(BaseModel)

Verifiable attestation about an agent

AgentCard Objects​

class AgentCard(BaseModel)

Agent Card following Google's A2A protocol Provides human-readable agent information

AgentDID Objects​

class AgentDID(BaseModel)

Complete W3C DID Document for SpoonOS Agent

to_did_document​

def to_did_document() -> Dict[str, Any]

Export as standard W3C DID Document

to_agent_card​

def to_agent_card() -> Dict[str, Any]

Export agent card separately

DIDResolutionResult Objects​

class DIDResolutionResult(BaseModel)

Result of DID resolution

Module spoon_ai.identity.attestation

Attestation and Trust Score Management Handles verifiable credentials and reputation calculations

AttestationManager Objects​

class AttestationManager()

Manages verifiable attestations for agents

create_attestation​

def create_attestation(issuer_did: str,
                       subject_did: str,
                       claim: Dict,
                       evidence: Optional[str] = None) -> Attestation

Create a verifiable attestation

Arguments:

  • issuer_did - DID of the attestation issuer
  • subject_did - DID of the agent being attested
  • claim - Attestation claim data
  • evidence - Optional supporting evidence

Returns:

Signed Attestation object

verify_attestation​

def verify_attestation(attestation: Attestation) -> bool

Verify attestation signature

submit_reputation_on_chain​

def submit_reputation_on_chain(subject_did: str, score: int,
                               evidence: str) -> str

Submit reputation score to on-chain registry

Arguments:

  • subject_did - DID of agent being rated
  • score - Score between -100 and 100
  • evidence - Evidence for the score

Returns:

Transaction hash

submit_validation_on_chain​

def submit_validation_on_chain(subject_did: str, is_valid: bool,
                               reason: str) -> str

Submit validation for an agent

Arguments:

  • subject_did - DID of agent being validated
  • is_valid - Whether agent is valid
  • reason - Reason for validation decision

Returns:

Transaction hash

TrustScoreCalculator Objects​

class TrustScoreCalculator()

Calculates trust scores for agents

calculate_trust_score​

def calculate_trust_score(did: str) -> Dict

Calculate comprehensive trust score

Returns:

Dict with trust score components:

  • reputation_score: -100 to 100
  • validation_status: bool
  • trust_level: "high" | "medium" | "low" | "untrusted"
  • confidence: 0 to 1

get_reputation_breakdown​

def get_reputation_breakdown(did: str, limit: int = 10) -> List[Dict]

Get detailed reputation submissions

get_validation_breakdown​

def get_validation_breakdown(did: str, limit: int = 10) -> List[Dict]

Get detailed validation submissions

Module spoon_ai.identity.storage_client

Storage clients for DID documents and agent cards Supports NeoFS (primary) and IPFS (backup replication)

DIDStorageClient Objects​

class DIDStorageClient()

Unified storage client for DID documents NeoFS primary with IPFS replication

publish_did_document​

def publish_did_document(agent_id: str, did_document: Dict,
                         agent_card: Dict) -> Tuple[str, str]

Publish DID document and agent card to storage Returns (didDocURI, agentCardURI)

fetch_did_document​

def fetch_did_document(uri: str) -> Dict

Fetch DID document from URI (NeoFS or IPFS)

publish_credential​

def publish_credential(agent_id: str, credential: Dict) -> str

Publish verifiable credential

close​

def close()

Close HTTP clients

Module spoon_ai.identity.did_resolver

DID Resolver for SpoonOS Agents Implements unified DID resolution with NeoFS-first policy

DIDResolver Objects​

class DIDResolver()

Unified DID resolver for SpoonOS agents Resolution flow: On-chain anchor → NeoFS (primary) → IPFS (fallback)

resolve​

def resolve(did: str) -> DIDResolutionResult

Resolve DID to complete DID document

Arguments:

  • did - DID string (did🥄agent:<identifier>)

Returns:

DIDResolutionResult with document and metadata

resolve_metadata_only​

def resolve_metadata_only(did: str) -> Dict

Resolve only on-chain metadata (fast path)

verify_did​

def verify_did(did: str) -> bool

Verify DID exists and is resolvable

Module spoon_ai.identity.erc8004_abi

Shared ERC-8004 ABI fragments (minimal, artifact-free).

These ABIs cover the common calls used by the Python SDK and demos.

Module spoon_ai.identity.erc8004_client

ERC-8004 Smart Contract Client Handles on-chain interactions with agent registries

ERC8004Client Objects​

class ERC8004Client()

Client for interacting with ERC-8004 agent registries

calculate_did_hash​

def calculate_did_hash(did: str) -> bytes

Calculate keccak256 hash of DID string

create_eip712_signature​

def create_eip712_signature(did_hash: bytes, agent_card_uri: str,
                            did_doc_uri: str) -> str

Create EIP-712 signature for agent registration

register_agent​

def register_agent(did: str, agent_card_uri: str, did_doc_uri: str) -> str

Register agent on-chain

resolve_agent​

def resolve_agent(did: str) -> Dict

Resolve agent metadata from on-chain registry

update_capabilities​

def update_capabilities(did: str, capabilities: List[str]) -> str

Update agent capabilities on-chain

build_feedback_auth​

def build_feedback_auth(agent_id: Union[int, bytes],
                        client_address: str,
                        index_limit: int,
                        expiry: int,
                        signer_address: Optional[str] = None,
                        identity_registry: Optional[str] = None,
                        chain_id: Optional[int] = None) -> bytes

Build and sign feedbackAuth payload required by chaoschain ERC8004 reputation registry. Returns abi.encode(struct) ++ signature (65 bytes).

give_feedback​

def give_feedback(did: str,
                  score: int,
                  tag1: bytes = b"",
                  tag2: bytes = b"",
                  fileuri: str = "",
                  filehash: bytes = b"\x00" * 32,
                  index_limit: int = 10,
                  expiry: Optional[int] = None,
                  client_address: Optional[str] = None) -> str

Submit feedback using ERC8004 giveFeedback with feedbackAuth.

get_reputation_summary​

def get_reputation_summary(did: str,
                           client_addresses: Optional[List[str]] = None,
                           tag1: bytes = b"\x00" * 32,
                           tag2: bytes = b"\x00" * 32) -> Tuple[int, int]

Return (count, averageScore 0-100).

get_reputation​

def get_reputation(did: str) -> Tuple[int, int]

Backward compatible: (averageScore, count).

validation_request​

def validation_request(
        did: str,
        validator: str,
        request_uri: str,
        request_hash: Optional[bytes] = None) -> Tuple[str, bytes]

Create validation request; returns tx hash and requestHash used.

get_validation_status​

def get_validation_status(request_hash: bytes) -> Dict

Get per-request validation status.

submit_validation​

def submit_validation(did: str, is_valid: bool, reason: str = "") -> str

Map boolean into 0/100 scale response.

register_agent​

def register_agent(token_uri: str,
                   metadata: Optional[List[Tuple[str, bytes]]] = None) -> int

Register agent on IdentityRegistry; returns agentId.