Repository navigation
Advanced Topics
RunTimeAdmin edited this page Oct 30, 2026
·
19 revisions
**Referenced Files in This Document**
- [README.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/README.md)
- [architecture.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/architecture.md)
- [reputation-model.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/reputation-model.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)
- [0004-operator-custody.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/adr/0004-operator-custody.md)
- [0005-governance-and-emergency-powers.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/docs/adr/0005-governance-and-emergency-powers.md)
- [SplitAuthority.s.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/script/SplitAuthority.s.sol)
- [score-caps.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/score-caps.js)
- [SigvaraReputation.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraReputation.sol)
- [SigvaraStaking.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraStaking.sol)
- [Upgrade.s.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/script/Upgrade.s.sol)
- [scoring.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/scoring.js)
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
This document provides advanced, expert-level guidance for contributors and operators extending Sigvara’s scoring model, integrating cross-chain components, operating governance and upgrades safely, hardening the system against exploits, and optimizing performance and gas usage. It focuses on implementation details, architectural trade-offs, and operational procedures grounded in the repository’s contracts, oracle logic, and design records.
The repository separates protocol concerns into:
- On-chain registries and economic primitives under
src/. - Oracle computation and evidence intake under
oracle/. - Governance, deployment, and upgrade tooling under
script/andscripts/. - Design decisions and architecture under
docs/, including ADRs. - TypeScript SDK under
packages/sdk/. - Test suites and invariant checks under
test/.
graph TB
subgraph "On-chain"
REP["SigvaraReputation"]
STK["SigvaraStaking"]
IDN["SigvaraIdentity"]
ORB["SigvaraOracleBond"]
end
subgraph "Off-chain"
ORA["Oracle Network<br/>scoring + evidence"]
CON["Consumers / SDK"]
end
ORA --> REP
STK --> REP
IDN --> REP
REP --> CON
Diagram sources
Section sources
- SigvaraReputation: Stores normalized 6-factor scores, enforces optimistic proposal windows, maturity, and evidence roots.
- SigvaraStaking: Manages bonds, unbonding, slashing lifecycle, and dispute resolution; coordinates with Identity and Reputation.
- SigvaraIdentity: Agent identity, Ed25519 keys, status transitions, and stake view integration.
- SigvaraOracleBond: Optional bonded operator registry gating score proposals.
- Oracle scoring: Deterministic factor functions and epoch aggregation producing Merkle-rooted evidence.
Key responsibilities:
- Scoring is off-chain; contracts store, gate, and serve scores.
- Slashing zeroes reputation and terminates agent status.
- Maturity controls spendability of earned scores.
- Evidence roots enable public verification of included payments.
Section sources
Sigvara sits above ERC-8004 identity and raw feedback, computing a normalized score and enforcing slashable bonds. Signals flow from CounterAudit outcomes, watchdog flags, ERC-8004 feedback, and on-chain payment scans into the oracle, which proposes scores to the reputation contract after challenge windows.
sequenceDiagram
participant CA as "CounterAudit"
participant WD as "Watchdog"
participant EREP as "ERC-8004 Feedback"
participant ORA as "Oracle"
participant REP as "SigvaraReputation"
participant STK as "SigvaraStaking"
CA->>ORA : Outcome attestations
WD->>ORA : Flags
EREP->>ORA : External feedback
ORA->>ORA : Compute factors + Merkle root
ORA->>REP : proposeReputation(data, evidenceRoot)
Note over REP : Challenge window opens
alt Committee rejects
REP-->>ORA : ScoreRejected
else Window elapses
ORA->>REP : finalizeReputation(didHash)
REP-->>ORA : ReputationUpdated(totalScore)
end
STK->>REP : zeroReputation(didHash) on slash
Diagram sources
Extending the scoring model requires changes in both the oracle’s deterministic functions and the on-chain cap/validation layer.
- Add or adjust factor functions in the oracle scoring module.
- Update factor caps and validation constants in the reputation contract. The oracle keeps its six caps in one module,
score-caps.js, and its test reads the contract'sMAX_*_SCOREconstants, so a reweight is one edit plus a failing test if the contract was not changed with it. - Ensure evidence accounting aligns with new inputs (e.g., per-payer caps, decay).
- Maintain determinism across operators by anchoring time to chain timestamps and avoiding host-dependent drift.
flowchart TD
Start(["New Factor Idea"]) --> Define["Define inputs, decay, and bounds"]
Define --> Implement["Implement pure function in oracle scoring"]
Implement --> Validate["Add cap and validation in reputation contract"]
Validate --> Integrate["Wire into computeScore total"]
Integrate --> Test["Unit test factor + end-to-end epoch"]
Test --> Review{"Deterministic across operators?"}
Review --> |No| FixDrift["Anchor time, fix float drift"]
Review --> |Yes| Deploy["Deploy oracle update + contract cap change"]
Diagram sources
Section sources
Evidence intake has evolved from push-only attestations to pull-based payment scanning, improving convergence between operators.
- Pull path: Each operator independently indexes Transfer logs to registered agent addresses;
/attestbecomes a hint and outcome carrier. - Push path: Outcomes remain push because success/failure is not on-chain.
- Deduplication and payer identity must be consistent across paths to avoid divergence.
flowchart TD
A["Transfer log to agent address"] --> B["Operator scan"]
C["POST /attest with settlement tx"] --> D["Outcome carrier + hint"]
B --> E["Credit fee activity / tenure"]
D --> F["Credit success rate if outcome present"]
E --> G["Aggregate per payer, apply caps + decay"]
F --> G
G --> H["Compute factors + Merkle root"]
Diagram sources
Section sources
When introducing novel algorithms:
- Keep factor functions pure and deterministic.
- Anchor all time-sensitive calculations to chain timestamps.
- Clamp outputs to contract-defined caps to prevent revert risks.
- Provide Merkle leaves that reflect the exact inputs used in scoring.
- Run checker-mode recomputation to detect drift before mainnet.
classDiagram
class ScoringModule {
+computeScore(inputs)
+feeScore(volume)
+successRate(success, total)
+tenure(spanDays, recency)
+community(flags)
+propagation(counterpartyStanding)
}
class ReputationContract {
+proposeReputation(data, evidenceRoot)
+finalizeReputation(didHash)
+getTotalScore(didHash)
+verifyEvidence(didHash, leaf, proof)
}
ScoringModule --> ReputationContract : "proposes capped data"
Diagram sources
Section sources
Cross-chain strategy centers on mirroring state via LayerZero while preserving trust assumptions:
- Identity and feedback are canonical on ERC-8004; Sigvara computes and slashes on target chains.
- Bridge strategies should mirror only what is necessary: agent identity linkage, external feedback references, and slash outcomes.
- Multi-chain deployments require independent oracle operators per chain, with shared input standards and deterministic scoring.
graph TB
SRC["Source Chain<br/>ERC-8004 + Sigvara"]
LZ["LayerZero Messaging"]
DST["Destination Chain<br/>Mirrored State"]
ORASRC["Source Oracle"]
ORADST["Destination Oracle"]
SRC --> LZ
LZ --> DST
ORASRC --> SRC
ORADST --> DST
Section sources
Governance and upgrades rely on UUPS proxies controlled by roles, with timelock targets for mainnet:
- Roles include DEFAULT_ADMIN_ROLE, UPGRADER_ROLE, ORACLE_ROLE, SLASHING_COMMITTEE_ROLE, and STAKING_CORE_ROLE, and on
mainGUARDIAN_ROLE (plus SLASHER_ROLE on the bond registry). - Upgrades use a dedicated script that validates dependencies, deploys new implementations, and verifies slot changes. After the handover the upgrade goes through the timelock instead, because the script cannot act as it.
- A Safe is the intended mainnet holder of the admin role and a 48 hour timelock the holder of the upgrade role. On
mainthe upgrade role administers itself and the roles that move funds or change an agent's standing, so the Safe cannot give itself an upgrade or install a slasher in the next transaction. It can still revoke the fund-moving roles at once, but not the upgrade role, and it keeps the oracle and guardian grants. The Arc testnet proxies predate this: there the admin also grants those roles.
sequenceDiagram
participant Gov as "Governance Timelock"
participant Script as "Upgrade Script"
participant Proxy as "UUPS Proxy"
participant Impl as "New Implementation"
Gov->>Script : Authorize upgrade
Script->>Proxy : upgradeToAndCall(newImpl, initData)
Proxy->>Impl : _authorizeUpgrade()
Impl-->>Proxy : Storage layout verified
Script-->>Gov : Record live implementation
Diagram sources
Section sources
Slash lifecycle includes initiation, suspension, challenge period, dispute, resolution, and execution:
- Initiation suspends the agent immediately.
- Dispute freezes stake and moves proposal to resolution. On
mainthe admin rules, not the committee, and cannot uphold a dispute before the challenge deadline or once it can be expired; the admin can also veto a pending or disputed slash, and a slash nobody executes can be lapsed by anyone 14 days after its deadline. After any dropped proposal the committee waits one challenge period before it can file against the agent again. The Arc testnet contracts have worked this way since 26 October 2026, apart from the bound on upholding a dispute, which they take at their next upgrade. - Execution burns 50%, distributes 25% to victim and 25% to reporter, zeros reputation, and marks agent slashed.
stateDiagram-v2
[*] --> PendingSlash
PendingSlash --> Suspended : initiateSlash()
Suspended --> Disputed : disputeSlash()
Disputed --> Executed : resolveDispute(uphold=true)
Disputed --> Cancelled : resolveDispute(uphold=false), expireDispute() or vetoSlash()
PendingSlash --> Executed : executeSlash()
PendingSlash --> Cancelled : cancelSlash(), vetoSlash() or expireSlash()
Executed --> [*]
Cancelled --> ActiveOrSuspended : reinstate if bonded
Diagram sources
Section sources
Upgrade safety emphasizes dependency ordering and storage layout stability:
- The upgrade script checks that dependent interfaces exist before upgrading a contract, and that the proxy is the kind of contract the target names.
- Storage fields are appended to preserve proxy layouts (shared state such as the inflow pause sits in an ERC-7201 namespaced slot); reinitializers configure new state. They are admin-gated, so after the handover a timelocked upgrade lands with empty data and the Safe calls the reinitializer in a second transaction, which means a new reinitializer needs an unset state that fails closed.
- Post-upgrade, record the live implementation address to maintain an auditable history.
flowchart TD
Prep["Prepare new implementation"] --> DepCheck["Check dependencies"]
DepCheck --> |Pass| Upgrade["upgradeToAndCall(newImpl, initData)"]
DepCheck --> |Fail| Abort["Abort upgrade"]
Upgrade --> Verify["Verify implementation slot changed"]
Verify --> Record["Record live implementation"]
Diagram sources
Section sources
Security posture includes:
- Vulnerability assessment through unit, fuzz, invariant tests, and Slither in CI.
- Exploit mitigation via bond requirements, slash finality, maturity delays, and evidence roots.
- Formal verification approaches: invariants over staking and identity states, plus checker-mode recomputation to detect divergence.
Key mitigations:
- Only bonded agents are scored; slashing zeroes reputation and terminates status.
- Maturity prevents farm-and-cash-out exploitation.
- Evidence roots allow public verification of included payments.
- A Safe for the admin role and a 48 hour timelock for upgrades and the roles that move funds, on mainnet.
- On
main: a guardian key can pause new inflows for three days at a time and nothing else, and the periods, the score window and the maturity rate have floors and ceilings enforced in the initializers as well as the setters. - The oracle fails safe against a wrong-chain RPC, a clock that disagrees with the chain's, fees above its caps and a state file it cannot trust.
- The strength of the contract tests is measured with the mutation harnesses in
scripts/mutation.
Section sources
Design rationale and trade-offs are captured in ADRs:
- ADR 0001 adopts ERC-8004 as the canonical identity layer, retaining SigvaraReputation and SigvaraStaking as computed-score and slashing layers.
- ADR 0003 shifts evidence intake to pull-based scanning, closing the gap where unreported work was invisible and improving operator convergence.
- ADR 0004 separates the key that signs from the key that holds the bond: an operator names a signer, finalizing asks about the proposer, and an agent is charged once per epoch.
- ADR 0005 records who can do what in an emergency: roles that move funds are granted through the timelock, the admin rules on disputes and can veto, a guardian can pause inflows, and the launch figures are floors in the mainnet scripts. Its later decisions add that a slash is executed only while its reporter is still on the committee (so revoking a compromised member defuses what it filed), and that a withdrawal's claim time and rejected evidence are fixed when they are recorded.
- ADR 0002 records the static-analysis findings that were reviewed and accepted.
graph LR
ADR1["ADR 0001<br/>ERC-8004 Identity Layer"] --> SIGVARA["SigvaraReputation + Staking"]
ADR3["ADR 0003<br/>Pull-Based Evidence"] --> ORA["Oracle Convergence"]
ADR4["ADR 0004<br/>Operator Custody"] --> BOND["Operator signers and bond"]
ADR5["ADR 0005<br/>Governance and Emergency Powers"] --> SIGVARA
Diagram sources
Section sources
Component coupling and cohesion:
- SigvaraReputation depends on SigvaraIdentity for agent existence, status, and stake view.
- SigvaraStaking depends on SigvaraIdentity for status transitions and on SigvaraReputation for zeroing scores.
- Oracle scoring is decoupled from contracts but must respect contract caps and validation rules.
graph TB
IDN["SigvaraIdentity"] --> REP["SigvaraReputation"]
STK["SigvaraStaking"] --> IDN
STK --> REP
ORA["Oracle Scoring"] --> REP
Diagram sources
Section sources
Optimization techniques:
- Gas optimization: Use view functions for reads, minimize storage writes, and batch operations where possible.
- Oracle efficiency: Chunked log scanning with backoff and checkpointing reduces RPC pressure.
- Determinism: Anchor time to chain timestamps to avoid drift and reduce checker disagreements.
- Scalability: Independent operator scanning improves resilience; shared input standards reduce divergence.
Recommendations:
- Prefer pull-based evidence intake to reduce reliance on push channels.
- Clamp all factor outputs to contract caps to prevent revert costs.
- Use Merkle proofs for evidence verification to keep on-chain verification cheap.
Section sources
Common issues and resolutions:
- Score not finalizing: Check challenge window and ensure no rejection occurred.
- Operator not allowed to propose: Verify bonded operator registration (or, on
main, that the key is the named signer of one) and role assignment. - Evidence mismatch: Rebuild Merkle root from chain logs and compare with stored root.
- Upgrade failure: Confirm dependency interfaces exist and storage layout is compatible.
Operational steps:
- Use
record-implementations.mjsto verify live implementation addresses. - Run checker-mode recomputation to detect divergence between operators.
- Monitor slash disputes and ensure the admin rules within the 14-day dispute window (
DISPUTE_RESOLUTION_PERIOD); after that anyone can callexpireDispute, and onmainan uphold is refused from then on.
Section sources
Sigvara’s advanced topics center on deterministic scoring, robust evidence intake, secure governance and upgrades, and resilient multi-chain operations. Contributors should prioritize determinism, evidence verifiability, and careful dependency management when extending the system. Operators should enforce timelocked governance, run checker-mode recomputation, and maintain clear audit trails for upgrades and slash disputes.
- Token and distribution details are documented separately and are out of scope for this advanced technical guide.
- For ecosystem integrations and quickstart flows, refer to the primary documentation and SDK guides.
- 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