Skip to content

Integration Guides

Jump to bottom
RunTimeAdmin edited this page Nov 5, 2026 · 37 revisions

Integration Guides

**Referenced Files in This Document** - [standing.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/standing.ts) - [x402.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/x402.ts) - [tools.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/tools.ts) - [counteraudit-integration.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/counteraudit-integration.md) - [ai-frameworks.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/ai-frameworks.md) - [mcp-gated-tool README.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/examples/mcp-gated-tool/README.md) - [server.mjs](https://github.com/RunTimeAdmin/Sigvara/blob/main/examples/mcp-gated-tool/server.mjs) - [sdk README.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/README.md) - [index.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/index.ts) - [agent.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/agent.ts) - [verifier.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/verifier.ts) - [gate.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/src/gate.ts) - [oracle README.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/README.md)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides end-to-end integration guides for connecting external systems to Sigvara. It covers:

  • CounterAudit platform integration for audit packet enrichment and outcome reporting
  • AI framework integrations including LangChain, AutoGen, CrewAI, and TypeScript patterns
  • Checking an agent before paying or hiring it, under an x402 client or in a framework's tools
  • MCP (Model Context Protocol) gated tool implementation with a practical server example
  • Web application integration patterns using the TypeScript SDK
  • Enterprise integration scenarios, security considerations, and performance optimization strategies
  • Step-by-step tutorials and troubleshooting guidance

The goal is to help you build secure, auditable agent workflows that are tied to on-chain identity and reputation while remaining compatible with common AI frameworks and MCP hosts.

SDK behaviour on this page is that of 1.0.0-alpha.16, published to npm on 5 November 2026. New since 1.0.0-alpha.15: SigvaraTrustCheck, which asks the gate's question about a bare address, with no proof; sigvaraX402Fetch, which checks the seller before an x402 payment is signed; sigvaraTrustTool and requireTrustedAgent, for LangChain and its like; minBond on SigvaraGate, with its below_bond refusal; challengeSecret on SigvaraGate, which accepts only challenges the gate issued, with generateChallenge taking an optional fourth argument that makes the nonce; a spent nonce recorded for one agent and one audience, as a hash a NonceStore is handed where it was handed the nonce; and SigvaraVerifier keeping to 20 calls in a batch. New since 1.0.0-alpha.14: sigvara-mcp, a read-only MCP trust server for an agent's MCP host (see MCP Gated Tools), the evidence-root functions evidenceLeaf, evidenceRoot and matchEvidenceRoot, and reads on SigvaraVerifier for a trust check, verifyEvidence and getEvidenceRoot among them. New since 1.0.0-alpha.13: profile: 'production' on SigvaraGate, which makes the constructor refuse to build the gate until instances and maxScoreAgeSeconds are both set. New since 1.0.0-alpha.12: atomicNonceStore; the gate's instances setting, with which a gate set to 'multiple' refuses to start without a nonce store with an atomic consume(); and signPaymentOutcome and verifyPaymentOutcome, which sign and check a payer's statement of whether one payment's work was delivered. New since 1.0.0-alpha.11: the agent's signChallenge is removed, so a call does not compile in TypeScript and throws in JavaScript, and signChallengeFor is the way to sign. New since 1.0.0-alpha.10: verifySignature requires the expected audience (see the changelog). These items are new since 1.0.0-alpha.9 (listed in the changelog): signChallengeFor, the 30 second read timeout, the parallel status and score read, the gate also checking the bond held now, the optional maxScoreAgeSeconds limit and its stale_score refusal, the refusal of a challenge dated in the future, the checks on a gate's threshold, ttlSeconds and maxScoreAgeSeconds, and the agent keeping its secret key in a private field.

Project Structure

Sigvara exposes integration points through:

  • Documentation describing integration flows and configuration
  • A TypeScript SDK for identity, challenge-response authentication, reputation checks, and gating
  • An MCP gated tool example demonstrating JSON-RPC over stdio with standing-based access control
  • An off-chain oracle that computes and publishes reputation scores backed by payment-verified evidence
graph TB
subgraph "Client Applications"
App["Web App / Backend"]
Framework["LangChain / AutoGen / CrewAI"]
MCPHost["MCP Host"]
end
subgraph "Sigvara Runtime"
SDK["@sigvara/protocol-sdk"]
Gate["SigvaraGate"]
Verifier["SigvaraVerifier"]
Agent["SigvaraAgent"]
end
subgraph "External Services"
CA["CounterAudit API"]
Oracle["Sigvara Oracle HTTP API"]
end
subgraph "Blockchain"
Chain["Arc Testnet Contracts"]
end
App --> SDK
Framework --> CA
MCPHost --> Gate
Gate --> Verifier
Verifier --> Chain
App --> Oracle
CA --> Chain
Loading

Diagram sources

Section sources

Core Components

  • SigvaraAgent: generates Ed25519 keys, derives DID and didHash, signs challenges
  • SigvaraVerifier: reads identity, status, reputation, stake; verifies signatures against on-chain public keys
  • SigvaraGate: issues challenges, enforces nonce replay protection, admits or refuses based on standing and threshold
  • SigvaraTrustCheck: asks the gate's question about a bare address, with no proof, for deciding whether to pay or hire it
  • SigvaraReader (Solidity, src/SigvaraReader.sol): for contracts that must decide whether to deal with an agent. isTrusted(agent, minScore) checks Active status, the bond held now against the current minimum stake, and the spendable score; isTrusted(agent, minScore, minBond) also asks for a bond of at least minBond; isTrustedFresh adds a limit on how long ago the score was proposed. It is on Arc testnet at 0x2921b4eE879CdF5793FA273BbDc4E7dF01ABcef8, and sigvara.xyz/integrate has the call from a service and from a contract. To point at other registries, a consumer deploys its own (see docs/integration.md)
  • CounterAudit integration: enriches sealed audit packets with on-chain identity and frozen reputation score at seal time
  • Oracle: computes six-factor reputation from payment-backed attestations and publishes finalized scores on chain

Key responsibilities:

  • Identity binding: deterministic DID derivation and on-chain registration
  • Authentication: challenge-response with audience binding and TTL
  • Reputation gating: enforce minimum maturity and score thresholds
  • Audit trail: tamper-evident sealing with reputation snapshot
  • Evidence and scoring: payment verification, Merkle roots, and public auditability

Section sources

Architecture Overview

The integration architecture connects applications, AI frameworks, and MCP hosts to Sigvara’s on-chain identity and reputation via the SDK and external services.

sequenceDiagram
participant Client as "Application"
participant SDK as "@sigvara/protocol-sdk"
participant Gate as "SigvaraGate"
participant Verifier as "SigvaraVerifier"
participant Chain as "Arc Contracts"
participant CA as "CounterAudit"
participant Oracle as "Oracle API"
Client->>SDK : Initialize SigvaraAgent / SigvaraVerifier
Client->>CA : POST /v1/audit/ingest with agent_did
CA->>Chain : Query identity and reputation
Chain-->>CA : Identity + frozen score
CA-->>Client : Sealed packet_id
Client->>Gate : challenge(did)
Gate-->>Client : { payload, expiresAt }
Client->>Gate : admit(did, challenge, signature)
Gate->>Verifier : verifySignature(...)
Verifier->>Chain : Read pubkey, status, score
Chain-->>Verifier : Data
Verifier-->>Gate : Verified?
Gate-->>Client : Admit or Refuse with reason
Loading

Diagram sources

Detailed Component Analysis

CounterAudit Platform Integration

CounterAudit enriches sealed audit packets with an agent’s on-chain identity and reputation score at seal time. The enriched fields are included inside the AES-GCM seal, making the reputation snapshot tamper-evident and timestamped.

Integration steps:

  • Add agent_did to ingest calls
  • Configure self-hosted or use managed service
  • Read enriched fields from verified packets
  • Build trust gates using verifier methods
flowchart TD
Start(["Ingest Call"]) --> ParseDID["Parse DID<br/>did:sigvara:<chainId>:<address>"]
ParseDID --> ComputeHash["Compute didHash"]
ComputeHash --> QueryChain["Query Identity + Reputation"]
QueryChain --> EnrichPacket["Enrich Packet Body"]
EnrichPacket --> Seal["AES-GCM Seal + Timestamp"]
Seal --> Return["Return packet_id, entry_hash, created_at"]
Loading

Diagram sources

Best practices:

  • Always include agent_did for tamper-evident reputation snapshots
  • Treat enrichment errors as non-blocking; packets still seal
  • Use verifier methods like meetsThreshold before accepting agent actions. It compares the spendable score alone and ignores status and bond, so also check isActive and hasMinimumStake, or call SigvaraReader.isTrusted, on Arc testnet at 0x2921b4eE879CdF5793FA273BbDc4E7dF01ABcef8
  • Validate enriched fields after verification to confirm identity and score at seal time

Outcome reporting:

  • Submit outcomes with settlement transaction hashes
  • Oracle re-reads transfers to determine payer and amount
  • Success rate and fee activity feed into reputation
  • A relayed outcome is recorded because CounterAudit presents an oracle token (SIGVARA_ORACLE_URL and SIGVARA_ORACLE_TOKEN; without both, CounterAudit still enriches packets and reports nothing), and only for an org listed in CA_OUTCOME_PUBLISH_ORG_IDS. The outcome is the ingesting org's word, so since 30 October 2026 the production deployment lists no org. A request with neither a token nor the payer's signature credits the payment and records no outcome. SIGVARA_ORACLE_TIMEOUT_MS defaults to 4000
  • Outcomes the payer signed take their own connector, sigvara-payment-outcome-v1, with no allowlist and no oracle token: CounterAudit checks the signature, seals the record and forwards it to each operator, which checks it again. CounterAudit has carried them on Arc testnet since 1 November 2026

Security notes:

  • Settlement hash is required: the oracle re-reads the transaction and takes the payer from the transfer log rather than trusting the caller
  • Forged hashes fail at the oracle
  • Enrichment is inside the seal; tampering invalidates integrity

Section sources

AI Framework Integrations

Patterns across frameworks:

  • Generate DID at startup
  • Sign challenges when asked to authenticate
  • Include agent_did in every audit call
  • Verify signatures and reputation before trusting peer agents

LangChain (Python):

  • Wrap tools to include agent_did and audit results
  • Gate execution by reputation threshold

AutoGen (Python):

  • Extend assistant to audit replies
  • Include connector ID and message metadata

CrewAI (Python):

  • Callback tasks to audit task outputs
  • Use preview fields to avoid leaking sensitive data

TypeScript (framework-agnostic):

  • Middleware pattern for fire-and-forget auditing
  • Challenge-response for agent-to-agent authentication, answering an inbound challenge with signChallengeFor(payload, peerDid) (alpha.9 has only signChallenge, which signs whatever it is handed; the agent's signChallenge is removed in 1.0.0-alpha.12)

LangChain (TypeScript, from 1.0.0-alpha.16):

  • sigvaraTrustTool(tool, trust) gives the model a tool to call before dealing with another agent
  • requireTrustedAgent(fn, trust, agentFrom) makes a tool of yours refuse to run for an agent without standing, whatever the model decided, and is the one to rely on
  • You pass in LangChain's tool, so LangChain is not a dependency of the SDK. See AI Framework Integration

Important note:

  • Python examples are pseudocode; no published Python SDK exists
  • Use the TypeScript SDK or call the Oracle HTTP API directly

Section sources

Before Paying or Hiring an Agent

SigvaraGate asks a caller to prove who it is. To decide whether to pay or hire an address, what matters is who the money goes to, so SigvaraTrustCheck (from 1.0.0-alpha.16) asks the same question with no proof, by the same rule. sigvaraX402Fetch goes underneath an x402 client, as wrapFetchWithPayment(sigvaraX402Fetch(fetch, trust), client): every payTo offered must have standing, or the request rejects with X402SellerRefused and the client signs nothing. It checks who is paid, not that work will be delivered, and a seller paid anywhere but the agent's registered address reads as having no standing. A failed read throws, with URLs removed, since it is neither a yes nor a no. See TypeScript SDK. sigvara.xyz/integrate has a card on it.

Section sources

MCP Gated Tool Implementation

The MCP gated tool demonstrates how to refuse tool calls from agents without standing. It uses JSON-RPC over stdio and implements a two-step handshake:

  • sigvara_challenge: returns a signed challenge payload
  • restricted_search: validates signature, checks standing, and executes work if admitted
sequenceDiagram
participant Agent as "Agent"
participant Server as "MCP Server"
participant Gate as "SigvaraGate"
participant Chain as "Arc Contracts"
Agent->>Server : tools/list
Server-->>Agent : Tools available
Agent->>Server : sigvara_challenge { did }
Server->>Gate : challenge(did)
Gate-->>Server : { payload, expiresAt }
Server-->>Agent : challenge response
Agent->>Server : restricted_search { did, challenge, signature, query }
Server->>Gate : admit(did, challenge, signature)
Gate->>Chain : verifySignature + isActive + hasMinimumStake + getTotalScore
Chain-->>Gate : Status + Bond + Score
Gate-->>Server : Admit or Refuse
Server-->>Agent : Result or refusal reason
Loading

Diagram sources

Practical guidance:

  • Set environment variables: SIGVARA_THRESHOLD, SIGVARA_AUDIENCE, RPC_URL, CHAIN_ID
  • Use stable audience per deployment to prevent relay attacks
  • Handle refusal reasons explicitly: bad proof, replayed, not active, below bond (if you set minBond), stale score (if you set maxScoreAgeSeconds), below threshold
  • Keep each outstanding challenge under its payload, and drop it only when the proof holds, as the example does. In production, key them to a session as well

Section sources

Web Application Integration Patterns

Frontend and backend integration patterns:

  • Initialize SigvaraAgent and SigvaraVerifier with RPC URL, addresses, and chain ID
  • Register agents and deposit stake to activate them
  • Issue challenges and verify signatures for agent-to-agent auth
  • Use SigvaraGate for admission decisions with clear refusal reasons
  • Integrate real-time reputation updates via oracle endpoints and badge generation

User experience design:

  • Show agent status and score badges
  • Provide actionable feedback for refusals
  • Cache reputation reads where appropriate
  • Surface evidence links for transparency. The public explorer at sigvara.xyz/agents rebuilds any Arc testnet agent's evidence root in the browser and asks the reputation contract to confirm each payment its finalized root covers, and sigvara.xyz/epochs shows each proposal for one agent and what became of it

Real-time updates:

  • Poll /score/:didHash for preview scores
  • Use /badge/:address.svg for embeddable status
  • Monitor /health and /metrics for operational signals. sigvara.xyz/status reads the oracle operators and the event index from their public endpoints in the browser

Section sources

Enterprise Integration Scenarios

Common enterprise patterns:

  • Multi-service orchestration with consistent audience values
  • Distributed nonce stores for fleet-scale gating, with instances: 'multiple' so each gate refuses to start without one, and profile: 'production' so it refuses to start until instances and maxScoreAgeSeconds are set. The same challengeSecret on every instance makes a fleet accept only challenges it issued, with no shared state
  • Reverse proxy hardening for oracle endpoints
  • Token-per-service credentials for write endpoints
  • Monitoring and alerting for epoch failures and divergence

Security considerations:

  • Audience binding prevents relay attacks
  • Nonce uniqueness prevents replay attacks, and a spent nonce counts for one agent and one audience
  • Payment verification ensures credible reputation signals
  • Public evidence enables third-party audits

Performance optimization:

  • Fire-and-forget audit calls to avoid blocking critical paths
  • Cache verifier reads where safe
  • Rate-limit read endpoints behind proxies
  • Use batched RPC calls and efficient contract interactions

Section sources

Dependency Analysis

The SDK exports core classes and utilities used across integrations.

classDiagram
class SigvaraAgent {
+generate(options)
+issueChallenge(peerDid, ttlSeconds)
+signChallengeFor(payload, audience)
+did
+didHash
+publicKeyBytes32
}
class SigvaraVerifier {
+getIdentity(did)
+isActive(did)
+getReputation(did)
+getTotalScore(did)
+getScoreUpdatedAt(did)
+meetsThreshold(did, threshold)
+verifySignature(did, challengePayload, signatureBase58, maxAgeSeconds, expectedAudience)
+buildDidDocument(did)
}
class SigvaraGate {
+challenge(did)
+admit(did, challenge, signatureBase58)
+threshold
+audience
}
SigvaraGate --> SigvaraVerifier : "uses"
SigvaraAgent --> SigvaraVerifier : "complementary"
Loading

Diagram sources

Section sources

Performance Considerations

  • Audit calls should be fire-and-forget to avoid blocking user-facing operations
  • Use view calls (meetsThreshold, isActive, hasMinimumStake) for fast, gas-free checks; meetsThreshold alone ignores status and bond
  • Cache reputation reads where appropriate, but refresh after state changes
  • Rate-limit oracle read endpoints and monitor /metrics
  • Prefer total score reads over full factor breakdowns when only thresholds matter
  • Use distributed nonce stores for multi-instance deployments to avoid replay vulnerabilities

Troubleshooting Guide

Common issues and resolutions:

  • Bad proof: ensure signature matches registered public key and challenge audience
  • Replay detected: request a fresh challenge and store nonces atomically
  • Not active: check bonding status; slashed agents cannot recover
  • Below bond (only with minBond): the agent holds the protocol's minimum but less than the gate asks for
  • Stale score (only with maxScoreAgeSeconds): the score was proposed longer ago than the limit, or never. Check the oracle, and that the limit is more than two of its proposals apart
  • Below threshold: earn score via independent payments and attested outcomes
  • X402SellerRefused: a payTo offered has no standing, or the 402 could not be read. A seller has to be paid at the agent's registered address for the check to find it
  • Enrichment errors: inspect agent_enrichment_error; packets still seal
  • Oracle health: monitor /health for 503 conditions and epoch failures
  • Divergence alerts: run checker mode and watcher to detect operator disagreements

Operational tips:

  • Validate environment variables for RPC URLs, contract addresses, and tokens
  • Confirm token names loaded at startup for write endpoints
  • Inspect /evidence to rebuild Merkle roots and verify payments
  • Use /divergence endpoints to identify scoring discrepancies

Section sources

Conclusion

Sigvara provides a robust foundation for integrating external systems with on-chain identity, reputation, and auditability. By combining CounterAudit enrichment, AI framework adapters, MCP gating, and the TypeScript SDK, you can build secure, transparent agent workflows. Follow best practices for audience binding, nonce management, payment verification, and monitoring to ensure reliable enterprise-grade integrations.

Appendices

Step-by-Step Tutorials

CounterAudit Ingest with Enrichment

  1. Obtain your agent DID
  2. Call /v1/audit/ingest with agent_did
  3. Receive packet_id
  4. Verify with /v1/audit/verify/$PACKET_ID
  5. Read enriched fields and validate seal integrity

Section sources

MCP Gated Tool Setup

  1. Install dependencies
  2. Run server with environment variables
  3. List tools via JSON-RPC
  4. Request challenge and sign with agent key
  5. Call gated tool with signature
  6. Handle refusal reasons

Section sources

TypeScript SDK Quickstart

  1. Initialize SigvaraAgent and SigvaraVerifier
  2. Register agent and deposit stake
  3. Issue challenge and verify signature
  4. Check threshold and status
  5. Use SigvaraGate for admission decisions
  6. Use SigvaraTrustCheck before paying or hiring an address

Section sources

Home

Overview

Protocol Architecture

Smart Contracts Reference

Oracle Service

Reputation System Design

TypeScript SDK

Integration Guides

Deployment and Operations

Development and Testing

Advanced Topics

Clone this wiki locally