Skip to content

Evidence Sources and Verification

RunTimeAdmin edited this page Nov 21, 2026 · 63 revisions

Evidence Sources & Verification

**Referenced Files in This Document** - [payment-backed-attestations.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/payment-backed-attestations.md) - [reputation-model.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/reputation-model.md) - [architecture.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/architecture.md) - [0001-erc8004-as-identity-layer.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/adr/0001-erc8004-as-identity-layer.md) - [0003-evidence-intake.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/adr/0003-evidence-intake.md) - [merkle.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/merkle.js) - [payments.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/payments.js) - [scoring.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/scoring.js) - [SigvaraReputation.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraReputation.sol) - [SigvaraIdentity.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraIdentity.sol)

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

Introduction

This document explains how Sigvara’s reputation system collects, verifies, and commits evidence for agent reputation. It focuses on:

  • Payment-backed attestations and settlement verification
  • Payer identity extraction from transfer logs
  • Anti-fraud controls such as self-payment detection and per-payer caps
  • External trust integration through ERC-8004 feedback
  • Community flag processing and governance
  • The Merkle tree proof system for evidence commitment and verification
  • Counterparty validation, diversity requirements, and manipulation prevention

The system separates computation from storage: the oracle computes scores off-chain, while the on-chain contract stores finalized scores, pending proposals, challenge windows, and Merkle roots over evidence.

Project Structure

Evidence flows from on-chain payment logs and external registries into the oracle, which computes a six-factor score and proposes it to SigvaraReputation. Consumers read the matured score and can verify individual evidence leaves against the committed root.

graph TB
subgraph "On-chain signals"
CH["EVM chain<br/>Transfer logs"]
EREP["ERC-8004 Reputation Registry<br/>raw feedback"]
ID["SigvaraIdentity<br/>agent status + stake view"]
end
subgraph "Oracle"
PAY["payments.js<br/>settlement verification"]
MERKLE["merkle.js<br/>evidence leaves + Merkle root"]
SCORE["scoring.js<br/>six-factor scoring"]
end
subgraph "Contracts"
REP["SigvaraReputation.sol<br/>propose / finalize / verifyEvidence"]
STAKING["SigvaraStaking (external)<br/>slash → zero score"]
end
CH --> PAY
EREP --> SCORE
ID --> SCORE
PAY --> SCORE
SCORE --> REP
REP --> MERKLE
STAKING --> REP
Loading

Diagram sources

Section sources

Core Components

  • Payment verification: Validates settlement transactions, extracts payer from transfer logs, enforces minimum amount and confirmations, and timestamps events by block time. A payment in a block before the one the agent registered in does not count, whether reported or scanned (payment-backed-attestations.md:219-222). Nor does one before the agent's first bond, where its evidence starts (payment-backed-attestations.md:224-229).
  • Pulled payments: When PAYMENT_SCAN_ENABLED=1, each operator scans Transfer logs to bonded agents' addresses itself and credits what it finds with no outcome (ADR 0003). /attest stays as a hint and as the way outcomes arrive at an operator. Outcomes the payer signed then pass between operators, which serve them at GET /outcomes and import each other's (ADR 0006); a token holder's outcome stays with the operator it was posted to.
  • Payment chains: A payment can also count from a chain other than the scored one, read by the same scan, once it is older than that chain's delay (ADR 0009, payment-chains.js:6-9, payment-chains.js:294-302). This is off by default: with PAYMENT_CHAIN_IDS unset no chain is read (payment-chains.js:43-45). A chain's default mode, shadow, reports what it would credit and credits nothing (payment-chains.js:179, payment-chains.js:680). On 4 November 2026 Elysium testnet ran that way on the checker only, and changed no score (0009-payments-on-base.md:253-254).
  • Anti-fraud controls: Rejects self-payments, limits per-payer contribution, decays volume and success evidence, and uses maturity to prevent farm-and-cash-out.
  • External trust: Normalizes ERC-8004 feedback into a capped external score. CounterAudit's own tag is not recognised, so its feedback is not counted twice.
  • Community flags: Unresolved flags reduce the community factor; flags are raised by credentialed services through POST /flag, separate from slashing.
  • Merkle evidence: Each proposal carries a Merkle root over evidence leaves, in a fixed order that does not depend on when each was credited (architecture.md:97-100); verifiers rebuild leaves from chain data, taking the outcome from the oracle, and check them against the contract-stored root. For a payer-signed outcome the oracle can also serve the signed payload, so a verifier can check that the committed outcome is one the payer signed.
  • Counterparty validation: Per-payer caps scale with counterparty standing; propagation grants points only for counterparties with external trust, gated by maturity.

Section sources

Architecture Overview

The reputation pipeline is designed so that anyone can independently verify the inputs used to compute a score without trusting the oracle’s internal state file.

sequenceDiagram
participant Client as "Client"
participant Oracle as "Oracle"
participant Chain as "EVM Chain"
participant Contract as "SigvaraReputation"
Client->>Oracle : POST /attest with txHash
Oracle->>Chain : getTransactionReceipt(txHash)
Chain-->>Oracle : receipt + logs
Oracle->>Chain : getBlock(blockNumber)
Chain-->>Oracle : block timestamp
Oracle->>Oracle : extract payer from Transfer log
Oracle->>Oracle : apply decay, caps, self-payment checks
Oracle->>Contract : proposeReputation(didHash, data, evidenceRoot)
Contract-->>Client : ScoreProposed event
Note over Client,Contract : Challenge window opens
Client->>Contract : verifyEvidence(didHash, leaf, proof)
Contract-->>Client : bool
Loading

Diagram sources

Detailed Component Analysis

Payment-backed Attestations and Settlement Verification

Attestations now require a real settlement transaction. The oracle:

  • Reads the agent address from the identity registry
  • Fetches the transaction receipt and scans for accepted asset transfers to the agent
  • Enforces the minimum amount on each sender (a zero-value transfer never counts) and the minimum confirmations
  • Reads each qualifying sender from the transfer logs as its own payer; the largest contributor names the attestation
  • Records the settlement per transaction, agent and sender to prevent replay
  • Stamps evidence with the block timestamp, not submission time
  • Computes fee activity from accumulated, decayed volume
  • Records an outcome only when the caller holds an oracle token or the request carries the payer's signed outcome; otherwise it credits the payment with none
flowchart TD
Start(["Attestation request"]) --> ValidateTx["Validate txHash format"]
ValidateTx --> GetReceipt["Fetch receipt"]
GetReceipt --> ReceiptOk{"Receipt exists and succeeded?"}
ReceiptOk --> |No| RpcError["Return RPC error or rejection"]
ReceiptOk --> CheckConfirmations["Check confirmations"]
CheckConfirmations --> Confirmed{"Enough confirmations?"}
Confirmed --> |No| Unconfirmed["Reject unconfirmed"]
Confirmed --> ScanTransfers["Scan Transfer logs for asset credit to agent"]
ScanTransfers --> CreditsFound{"Any credits?"}
CreditsFound --> |No| NoTransfer["Reject no transfer"]
CreditsFound --> GroupBySender["Group credits by sender"]
GroupBySender --> MinAmount{"Any sender above zero and at the minimum amount?"}
MinAmount --> |No| BelowMin["Reject below minimum"]
MinAmount --> BlockTime["Read block timestamp"]
BlockTime --> SelfCheck{"Self-payment?"}
SelfCheck --> |Yes| SelfPay["Reject self_payment"]
SelfCheck --> Dedupe["Deduplicate by (tx, agent, sender)"]
Dedupe --> StoreEvent["Store settlement time in ms, leaf encodes seconds"]
StoreEvent --> End(["Verified payment event"])
Loading

Diagram sources

Section sources

Payer Identity Extraction and Anti-Fraud Measures

  • Payer identity: Taken from the transfer logs, not from the caller-supplied attester field. Each qualifying sender is its own payer, and the largest contributor names the attestation.
  • Self-payment detection: Refuses payments where the payer equals the agent address, or the operator at the payment's own block, on the scan, /attest, signed outcomes and imports alike (payment-scan.js:398-408, index.js:2654-2664).
  • Per-payer cap: Limits each counterparty’s contribution to feeScore and attestation weight; trusted counterparties receive a scaled multiplier based on their external standing.
  • Decay: Volume and success evidence decay by half-life; stale evidence cannot maintain a score indefinitely.
  • Outcome handling: Pulled payments, and payments attested with neither an oracle token nor the payer's signature, carry no outcome and are excluded from both sides of the success ratio. A token holder's outcome goes on the largest leg alone; a payer-signed outcome goes on the signer's own leg.
flowchart TD
A["Grouped evidence by payer"] --> B["Compute decayed volume and weight"]
B --> C["Apply per-payer cap"]
C --> D["Scale successes proportionally when capped"]
D --> E["Exclude pulled payments from success ratio"]
E --> F["Aggregate diversified volume and attestations"]
Loading

Diagram sources

Section sources

External Trust Integration via ERC-8004

  • ERC-8004 provides canonical identity and raw signed feedback.
  • The oracle reads linked agent feedback only from addresses that paid the agent, at most the 100 most paid and the newest 10 rows of each (external.js:45-49), normalizes recognized rating dimensions, and scales the mean to a capped external score.
  • CounterAudit publishes under its own counteraudit tag, which the normalizer does not recognise, so its feedback is not counted twice: outcomes already feed the success factor directly.
  • Propagation grants up to 5 points based on counterparties’ external standing, pro-rated and capped, using matured totals to damp reflexivity.
graph LR
LINK["Operator links Sigvara agent to ERC-8004 identity"] --> READ["Oracle reads ERC-8004 feedback"]
READ --> NORMALIZE["Normalize recognized tags"]
NORMALIZE --> SCALE["Scale to externalScore cap"]
SCALE --> SCORE["Include in computeScore"]
CA["CounterAudit outcomes"] --> EXCLUDE["Own tag, not recognised by the normalizer"]
EXCLUDE --> SCORE
Loading

Diagram sources

Section sources

Community Flag Processing and Governance

  • Community factor starts at 5 points and decreases with unresolved flags.
  • Flags are raised by credentialed services through POST /flag, separate from slashing, and cleared with POST /flag/resolve.
  • Decay makes flag penalties gradual; flooring ensures integer scores.
flowchart TD
Flags["Unresolved flags"] --> Penalty["Penalty = flags × 2"]
Penalty --> Cap["Cap penalty at 5"]
Cap --> Community["communityScore = max(0, floor(5 - penalty))"]
Loading

Diagram sources

Section sources

Merkle Tree Proof System for Evidence Commitment

Each proposal includes a Merkle root over evidence leaves. Verifiers:

  • Rebuild leaves from chain data (txHash, payer, amount, settledAt in seconds) and the outcome code the oracle reports, with chainId first for a payment that settled on a payment chain (merkle.js:102-109)
  • Verify the leaf against the contract-stored root using OpenZeppelin’s MerkleProof
  • Use sorted-pair hashing and promote odd nodes to prevent malleability
classDiagram
class Merkle {
+leafFor(event) bytes32
+buildTree(events) object
+rootFor(events) bytes32
+proofFor(tree, index) bytes32[]
+verifyProof(leaf, proof, root) bool
+hashPair(a, b) bytes32
+settledSeconds(event) number
+outcomeCode(success) uint8
}
class SigvaraReputation {
+evidenceRoots[didHash] bytes32
+verifyEvidence(didHash, leaf, proof) bool
}
Merkle --> SigvaraReputation : "verifies leaves against root"
Loading

Diagram sources

Section sources

Counterparty Validation, Diversity Requirements, and Caps

  • Self-payment refusal: Prevents trivial wash attempts using operator or agent addresses.
  • Per-payer cap: Limits contribution to feeScore and attestation weight; trusted counterparties gain a multiplier based on external standing.
  • Diversity requirement: Reaching the feeScore cap requires multiple distinct payers; at the default of 4 points per payer it takes five payers with no standing of their own, and fewer when the payers are trusted (down to three at full standing); the exact number depends on configuration.
  • Propagation gating: Only counterparties with external trust contribute to propagation; unknown parties count as zero. A counterparty the node could not get an answer for (throttled, timed out or dropped) is retried, and if the read still fails the agent is skipped for that epoch.
flowchart TD
P["Payer evidence"] --> S["Self-payment check"]
S --> |Pass| C["Apply per-payer cap"]
C --> T["Scale cap by trusted counterparty standing"]
T --> D["Count distinct counterparties"]
D --> G["Gate propagation on external trust"]
Loading

Diagram sources

Section sources

Dependency Analysis

The oracle depends on chain data and external registries; the contract depends on identity and optional operator bonding.

graph TB
PAY["payments.js"] --> CH["EVM provider"]
PAY --> CFG["Environment config"]
MERKLE["merkle.js"] --> ETH["ethers"]
SCORE["scoring.js"] --> PAY
SCORE --> EXT["ERC-8004 feedback"]
REP["SigvaraReputation.sol"] --> ID["SigvaraIdentity.sol"]
REP --> OP["IOperatorSet (optional)"]
Loading

Diagram sources

Section sources

Performance Considerations

  • Decay arithmetic: Uses scaled integers to preserve precision with BigInt amounts and avoid float drift.
  • Event pruning: Leaves with negligible weight are pruned once per epoch to prevent unbounded state growth.
  • Scanning cost: Pulling payment evidence increases RPC load; backoff and chunking mitigate rate limits. The scan also spaces its getLogs calls (PAYMENT_SCAN_PACE_MS, 500 ms by default), reads a span the node refuses for its size in halves, and, when it credits nothing, re-runs its filter against the newest settlement it holds, of any agent. A failed canary holds the checkpoint, so the range is scanned again at the next epoch.
  • Maturity: Read-time extrapolation avoids reliance on oracle liveness for score accrual.

Troubleshooting Guide

Common issues and resolutions:

  • RPC failures: Treat as transient errors; do not interpret as rejected attestations.
  • Unconfirmed transactions: Require configured confirmation depth, and a block at or below the chain's finalized block, before acceptance.
  • Missing asset configuration: In required mode, a missing PAYMENT_ASSET, or a PAYMENT_MIN_AMOUNT of 0, stops startup.
  • Outcome mismatch: Ensure settledAt is in seconds and outcome uses the three-state code to avoid root mismatches.
  • Duplicate settlement: Deduplication key includes transaction, agent, and sender to handle batch transfers.

Section sources

Conclusion

Sigvara’s evidence system ties reputation to verifiable on-chain payments, external trust, and community flags. Payment verification anchors attestations to real economic activity, anti-fraud controls limit manipulation, and the Merkle proof system makes the oracle’s inputs auditable. External trust integration and propagation ensure that reputation reflects broader ecosystem standing while resisting reflexivity and Sybil amplification. Together, these mechanisms make reputation costly to fake, perishable over time, and transparently verifiable.

Overview

Clone this wiki locally