Skip to content

Integration Guides

Jump to bottom
RunTimeAdmin edited this page Oct 30, 2026 · 24 revisions

Integration Guides

**Referenced Files in This Document** - [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
  • 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.12, published to npm on 29 October 2026. 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
  • 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; isTrustedFresh adds a limit on the score's age. It is in the repository and deployed nowhere, so 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 (deployed nowhere yet)
  • 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
  • The 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). A request without a token credits the payment and records no outcome. SIGVARA_ORACLE_TIMEOUT_MS defaults to 4000

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)

Important note:

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

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, stale score (if you set maxScoreAgeSeconds), below threshold
  • Store outstanding challenges per session in production

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

Real-time updates:

  • Poll /score/:didHash for preview scores
  • Use /badge/:address.svg for embeddable status
  • Monitor /health and /metrics for operational signals

Section sources

Enterprise Integration Scenarios

Common enterprise patterns:

  • Multi-service orchestration with consistent audience values
  • Distributed nonce stores for fleet-scale gating
  • 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
  • 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 threshold: earn score via independent payments and attested outcomes
  • 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

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