Repository navigation
External Trust Integration
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
This document explains how Sigvara integrates external trust through ERC-8004 reputation registries. It covers how linked agent feedback is retrieved from external sources, normalized into a common scale, and converted into Sigvara’s scoring framework. It also documents the scaling algorithm that maps heterogeneous external ratings (the recognized tags use scales of 0 to 100, 0 to 1 and 0 to 5) to Sigvara’s 25-point external factor within the 0 to 100 score, the trust weighting mechanism for external influence, configuration options, fallback behavior when external data is unavailable, caching strategies, and security considerations around trusting external data sources.
External trust integration spans three layers:
- Oracle orchestration: reads linked agents, calls the external module, and composes the full score.
- External registry client: reads ERC-8004 feedback, verifies ownership, normalizes tags, and returns a bounded factor.
- Scoring and on-chain storage: aggregates factors and stores the finalized score with maturity and challenge windows.
graph TB
OR["Oracle index.js<br/>epoch loop"] --> EXT["external.js<br/>ERC-8004 reader"]
OR --> SC["scoring.js<br/>factor aggregation"]
OR --> CH["chain.js<br/>counterparty standing"]
SC --> REP["SigvaraReputation.sol<br/>store + maturity"]
EXT --> EREP["ERC-8004 Reputation Registry"]
EXT --> EID["ERC-8004 Identity Registry"]
Diagram sources
Section sources
- ERC-8004 external reader (
external.js): fetches signed feedback, verifies ownership, normalizes recognized tags, and returns a capped external factor. - Oracle epoch controller (
index.js): links Sigvara agents to ERC-8004 identities, retrieves external scores, and feeds them into the scoring function. - Scoring aggregator (
scoring.js): combines fee, success, tenure, external trust, community, and propagation factors into a total out of 100. - Counterparty standing helper (
chain.js): computes inherited trust using each counterparty’s external standing capped by their matured total. - On-chain reputation store (
SigvaraReputation.sol): validates proposed factors, enforces caps, manages proposals, challenges, finalization, and maturity.
Section sources
The external trust path begins with an operator linking a Sigvara agent to an ERC-8004 identity it owns, through POST /link. That call needs a write credential (scope link) and is refused with 403 when the identity is not owned by the agent’s operator. During each oracle epoch, the oracle reads the linked agent’s feedback from the ERC-8004 Reputation Registry, normalizes recognized rating dimensions, and converts them into a single external factor. That factor contributes up to 25 points toward the 100-point total. The contract stores and serves the score; computation remains off-chain.
sequenceDiagram
participant Operator as "Operator"
participant Oracle as "Oracle index.js"
participant External as "external.js"
participant ID as "ERC-8004 Identity"
participant Rep as "ERC-8004 Reputation"
participant Scorer as "scoring.js"
participant Store as "SigvaraReputation.sol"
Operator->>Oracle : Link agent to ERC-8004 identity
Oracle->>External : externalScoreFor(agentId, operator)
External->>ID : ownerOf(agentId)
ID-->>External : owner address
External->>Rep : getClients / getLastIndex / readFeedback
Rep-->>External : raw feedback rows
External-->>Oracle : normalized externalScore (0-25)
Oracle->>Scorer : computeScore(externalScore + other factors)
Scorer-->>Oracle : total score (0-100)
Oracle->>Store : proposeReputation(data, evidenceRoot)
Store-->>Oracle : pending proposal
Diagram sources
- The external module initializes only when all three environment variables are set: RPC URL, identity registry address, and reputation registry address. If any are missing, the module is inert and every external score becomes zero.
- For each linked agent, ownership is verified by checking that the ERC-8004 NFT owner matches the Sigvara operator wallet. Any error or mismatch yields zero. The only call made to the ERC-8004 Identity Registry is
ownerOf(agentId); the Reputation Registry is read withgetClients,getLastIndexandreadFeedback. - Feedback is fetched per client via
getClients, thengetLastIndex, thenreadFeedback. Revoked feedback is skipped, and index gaps are tolerated. - Each feedback row contains a value, decimals, and tag(s). The value is scaled by its decimals, and the tag is lowercased before normalization.
flowchart TD
Start(["externalScoreFor"]) --> CheckEnabled{"EXTERNAL_* configured?"}
CheckEnabled --> |No| ReturnZero["Return 0"]
CheckEnabled --> |Yes| VerifyOwner["Verify ERC-8004 NFT owner == operator"]
VerifyOwner --> OwnerOK{"Owner matches?"}
OwnerOK --> |No| ReturnZero
OwnerOK --> |Yes| ReadClients["Read clients for agentId"]
ReadClients --> LoopClients{"For each client"}
LoopClients --> GetIndex["Get last feedback index"]
GetIndex --> LoopIndices{"For i = 1..last"}
LoopIndices --> ReadFB["Read feedback(row)"]
ReadFB --> Revoked{"isRevoked?"}
Revoked --> |Yes| NextIndex["Skip"]
Revoked --> |No| NormalizeRow["Normalize value by decimals + tag"]
NormalizeRow --> Accumulate["Accumulate recognized rows"]
Accumulate --> NextIndex
NextIndex --> LoopIndices
LoopIndices --> ComputeMean["Compute mean of recognized ratings"]
ComputeMean --> ScaleFactor["Scale mean to 0-25"]
ScaleFactor --> End(["Return externalScore"])
Diagram sources
Section sources
- Recognized tags are mapped to 0–1 ratings using predefined normalizers. Examples include percentage-based tags divided by 100, win-rate already in 0–1, and star-like ratings divided by 5.
- Unrecognized tags are excluded rather than guessed, preserving meaningfulness. A tag is matched against the normalizer table by its own key only, because the tag is text chosen by whoever posts the feedback and a plain object also answers to
constructorand__proto__. - The mean of recognized ratings is rounded and scaled to a maximum of 25 points, the external cap kept in
oracle/score-caps.js. - In the overall scoring model, this external factor contributes up to 25 of the 100 total points. Other factors contribute fee activity (up to 20), success rate (up to 15), tenure (up to 30), community (up to 5), and propagation (up to 5).
flowchart TD
Rows["Raw feedback rows"] --> Filter["Filter recognized tags"]
Filter --> MapNorm["Map each value to 0-1 via TAG_NORMALIZERS"]
MapNorm --> Mean["Compute arithmetic mean"]
Mean --> Clamp["Clamp to 0-25"]
Clamp --> Factor["externalScore factor (0-25)"]
Factor --> Total["Sum with other factors to get total (0-100)"]
Diagram sources
Section sources
- External trust influences two parts of the score:
- Direct external factor: normalized ERC-8004 feedback contributes up to 25 points.
- Propagation factor: counterparties’ external standing raises the value of their evidence and contributes up to 5 points.
- Counterparty standing is computed as the minimum of the counterparty’s external score and their matured total. This prevents laundering a farmed total into another agent’s trust and ensures only external standing propagates.
- An unregistered or slashed counterparty has none. A counterparty the node could not answer for is not read as having none: the read is retried, and if it still fails the agent is skipped for that epoch, because scoring on a missing standing would lower the proposal for the wrong reason.
flowchart TD
Payer["Counterparty"] --> ExtStanding["Counterparty.externalScore"]
Payer --> MaturedTotal["Counterparty.maturedTotal"]
ExtStanding --> Cap["min(externalScore, maturedTotal)"]
MaturedTotal --> Cap
Cap --> EvidenceCap["Raise per-payer evidence cap"]
Cap --> Propagation["Add up to 5 propagation points"]
Diagram sources
Section sources
- Environment variables:
-
EXTERNAL_RPC: RPC endpoint for the ERC-8004 chain. -
EXTERNAL_IDENTITY_ADDRESS: ERC-8004 Identity Registry address. -
EXTERNAL_REPUTATION_ADDRESS: ERC-8004 Reputation Registry address.
-
- When all three are set, the external module is enabled. Otherwise, it is disabled and external scores default to zero.
- Chain health reporting:
-
configured()indicates whether the three values are present. -
refreshChainId()resolves and caches the actual chain ID. -
chainState()reports one of: disabled, configured, or unreachable.
-
classDiagram
class ExternalModule {
+init(cfg)
+configured() bool
+refreshChainId() number|null
+chainState() object
+externalScoreFor(agentId, expectedOwner) number
+verifyOwnership(agentId, expectedOwner) bool
+computeExternalScore(rows) number
}
class Config {
+externalRpc string
+externalIdentity string
+externalReputation string
}
ExternalModule --> Config : "reads"
Diagram sources
Section sources
- Disabled feed: if
EXTERNAL_*is unset,externalScoreForreturns zero without throwing. - Unreachable RPC: chain state reports “unreachable,” and individual reads fail safely, returning zero.
- Epoch resilience: failures in external reads do not abort the epoch; they simply yield zero for that factor.
- These fallbacks are for the ERC-8004 feed. On Sigvara's own chain a read the node could not get an answer to (throttled, timed out or dropped) is retried and, if it still fails, skips the agent for that epoch instead of yielding zero; a read that reverts counts as no standing.
flowchart TD
Enabled{"EXTERNAL_* configured?"}
Enabled --> |No| Zero["externalScore = 0"]
Enabled --> |Yes| Reachable{"RPC reachable?"}
Reachable --> |No| Zero
Reachable --> |Yes| Ownership{"NFT owner == operator?"}
Ownership --> |No| Zero
Ownership --> |Yes| Fetch["Fetch + normalize feedback"]
Fetch --> Result["externalScore (0-25)"]
Diagram sources
Section sources
- Chain ID caching:
refreshChainId()resolves and caches the chain ID once per initialization, avoiding repeated network calls. - Per-epoch payer score cache: the oracle caches counterparty standing across agents within an epoch to avoid redundant chain reads.
- Concurrency batching: ethers batches independent JSON-RPC calls issued in the same tick, reducing round trips during phase-one reads.
- Timeouts: external reads use a timeout wrapper to prevent long stalls from blocking the epoch.
flowchart TD
Init["external.init()"] --> CacheCID["Cache chainId"]
EpochStart["Epoch start"] --> ClearPayerCache["Clear payerScoreCache"]
PayerLookup["Resolve counterparty standings"] --> BatchCalls["Batch Promise.all calls"]
BatchCalls --> StoreCache["Store in payerScoreCache"]
ExternalReads["External feedback reads"] --> Timeout["withTimeout(promise)"]
Diagram sources
Section sources
- Ownership verification: before trusting ERC-8004 feedback, the module checks that the ERC-8004 NFT owner matches the Sigvara operator. This prevents claiming another agent’s reputation.
- Opt-in design: external integration is disabled unless explicitly configured, ensuring no accidental reliance on untrusted data.
- Avoiding double-counted signals: CounterAudit publishes under its own
counteraudittag, which the normalizer does not recognise, so the same signal is not counted twice. - Contract-side validation: proposed factors are validated against maximum caps; invalid proposals revert.
- Maturity and challenge window: scores become spendable over time and can be challenged before finalization, mitigating farm-and-cash-out risks.
flowchart TD
Input["External feedback"] --> Verify["Verify NFT ownership"]
Verify --> TagCheck{"Tag recognized?"}
TagCheck --> |No| Exclude["Exclude from normalization"]
TagCheck --> |Yes| Normalize["Normalize to 0-1"]
Normalize --> Aggregate["Aggregate mean → 0-25"]
Aggregate --> Validate["Contract validates caps"]
Validate --> Challenge["Challenge window"]
Challenge --> Finalize["Finalize + maturity"]
Diagram sources
- external.js:161-179
- external.js:31-61
- architecture.md:130-138
- SigvaraReputation.sol:369-448
- SigvaraReputation.sol:696-752
Section sources
- external.js:161-179
- external.js:31-61
- architecture.md:130-138
- SigvaraReputation.sol:369-448
- SigvaraReputation.sol:696-752
External trust depends on:
- Oracle orchestration: coordinates linked agents, external reads, and scoring.
- ERC-8004 registries: provide canonical identity and raw feedback.
- Scoring logic: aggregates factors and clamps totals.
- Counterparty standing: uses external standing to weight evidence and propagate trust.
- On-chain store: enforces caps, manages proposals, and exposes matured scores.
graph LR
Index["index.js"] --> External["external.js"]
Index --> Scoring["scoring.js"]
Index --> Chain["chain.js"]
Scoring --> Reputation["SigvaraReputation.sol"]
External --> ERC8004ID["ERC-8004 Identity"]
External --> ERC8004Rep["ERC-8004 Reputation"]
Diagram sources
Section sources
- Batching: independent chain reads are batched to reduce HTTP overhead.
- Chunking: large scans are split into chunks to avoid RPC limits and backpressure.
- Caching: chain ID and per-epoch payer scores are cached to minimize repeated calls.
- Timeouts: external reads are wrapped with timeouts to prevent epoch stalls.
- Concurrency: phase-one reads are concurrent but chunked to balance throughput and provider limits.
- External feed disabled: verify all three environment variables are set. If any are missing, external scores will be zero.
- Unreachable RPC: check
chainState()for “unreachable” status and inspect the error message. Ensure the RPC endpoint is valid and accessible. - Ownership mismatch: ensure the ERC-8004 NFT owner matches the Sigvara operator address. A mismatch results in zero external score.
- No recognized tags: if feedback uses unrecognized tags, the normalizer excludes them, resulting in zero external score. Add recognized tags or extend the normalizer deliberately.
- Epoch failures: external read errors should not abort the epoch. Inspect logs for warnings about external read timeouts or RPC failures.
Section sources
Sigvara’s external trust integration leverages ERC-8004 to bring cross-protocol reputation into its scoring model. The system retrieves signed feedback, verifies ownership, normalizes recognized rating dimensions, and scales them into a bounded external factor. That factor contributes up to 25 points to the 100-point total and also influences counterparty evidence and propagation. The design is opt-in, resilient to failures, and secured by ownership checks, contract-side validation, and maturity/challenge mechanisms. Operators can configure external providers, monitor feed health, and rely on caching and batching for performance.
- Agent Registration and Lifecycle
- Contract Overview and Architecture
- Economic Security Model and Incentives
- Evidence Verification and Merkle Proofs
- Key Management and Rotation
- Maturity Mechanism and Score Release
- Proposal Workflow and Challenge System
- Score Storage and Data Model
- SigvaraIdentity Contract
- SigvaraOracleBond Contract
- SigvaraReputation Contract
- SigvaraStaking Contract
- Slashing Lifecycle and Dispute Resolution
- Stake Management Functions
- Status Management and Control
- Token and Fee Contracts
- Unbonding Period and Withdrawal Security
- Anti-Manipulation and Security Measures
- Community Flag Processing
- Evidence Sources and Verification
- External Trust Integration
- Merkle Proof System
- Oracle Score Computation
- Payment-Backed Attestations
- Scoring Model and Formulas
- Agent Creation and Key Management
- Agent Operations
- Agent Registration Workflow
- Challenge-Response Authentication
- Gate Access Control
- Integration Patterns and Examples
- SDK Overview and Setup
- Verifier Functions