Skip to content

Troubleshooting and FAQ

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

Troubleshooting & FAQ

**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) - [SECURITY.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/SECURITY.md) - [SigvaraIdentity.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraIdentity.sol) - [SigvaraStaking.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraStaking.sol) - [SigvaraReputation.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraReputation.sol) - [scoring.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/scoring.js) - [chain.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/chain.js) - [response-cache.js](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/response-cache.js)

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 is a practical troubleshooting and FAQ guide for Sigvara’s ecosystem. It focuses on agent registration, score computation, slash disputes, integration issues, performance tuning, security incident response, diagnostics, known limitations, and planned improvements. The guidance maps directly to the protocol contracts, the oracle implementation, and the SDK usage patterns documented in the repository.

Project Structure

Sigvara consists of:

  • On-chain registries: identity, staking, reputation, and optional oracle bonding.
  • Off-chain components: an oracle that computes scores from payment-backed evidence and watchdog flags, plus supporting utilities such as backoff, caching, and metrics.
  • SDK and examples: TypeScript helpers for agent-to-agent authentication, gating, DID resolution, and registration flows.
graph TB
subgraph "On-chain"
ID["SigvaraIdentity"]
ST["SigvaraStaking"]
REP["SigvaraReputation"]
end
subgraph "Off-chain"
OR["Oracle"]
SDK["TypeScript SDK"]
CACHE["Response Cache"]
end
OR --> REP
OR --> ID
ST --> ID
ST --> REP
SDK --> REP
SDK --> ID
OR --> CACHE
Loading

Diagram sources

Section sources

Core Components

  • SigvaraIdentity: anchors agent identities, Ed25519 keys, operator control, status transitions, and two-step operator transfer.
  • SigvaraStaking: manages bonds, unbonding, slashing initiation/dispute/execution, and proceeds distribution.
  • SigvaraReputation: stores computed scores, enforces challenge windows, maturity, evidence roots, and bonded-oracle checks.
  • Oracle scoring: pure functions compute six factors; chain helpers provide RPC resilience, slot-race handling, and fee-gating.
  • Response cache: LRU cache with revision-based invalidation for expensive evidence responses.

Section sources

Architecture Overview

The system follows an optimistic scoring model:

  • The oracle proposes a score with an evidence root.
  • A challenge window allows the committee to reject bad proposals.
  • Finalization is permissionless after the window.
  • Slashing can zero reputation and mark agents terminal.
sequenceDiagram
participant UC as "User / Counterparty"
participant OR as "Oracle"
participant REP as "SigvaraReputation"
participant CM as "Committee"
UC->>OR : "Attestation + settlement tx"
OR->>REP : "proposeReputation(didHash, data, evidenceRoot)"
REP-->>OR : "ScoreProposed"
Note over REP : "Challenge window open"
alt "Committee rejects during window"
CM->>REP : "rejectReputation(didHash)"
REP-->>CM : "ScoreRejected"
else "Window elapses unchallenged"
UC->>REP : "finalizeReputation(didHash)"
REP-->>UC : "ReputationUpdated(totalScore)"
end
Loading

Diagram sources

Section sources

Detailed Component Analysis

Agent Registration Troubleshooting

Common symptoms:

  • Registration reverts with signature or key errors.
  • Agent remains PendingBond after deposit.
  • Operator cannot rotate key or transfer ownership.

Resolution steps:

  1. Verify the agent address signed the registration digest returned by the registry.
    • The digest must be unsigned before signing; wallets apply EIP-191 automatically.
    • Ensure the signer is the agent address itself (EOA or ERC-1271).
  2. Confirm the agent is registered and not already present under the same didHash.
  3. Deposit stake to reach minimumStake to transition from PendingBond to Active.
  4. If key compromise occurred:
    • Suspend the agent immediately.
    • Rotate the Ed25519 public key.
    • Reinstate only after rebonding if needed.
  5. For operator transfer:
    • Offer transfer, then accept from the new operator.
    • Transfers are blocked while slash is pending.
flowchart TD
Start(["Registration Entry"]) --> Digest["Compute registrationDigest()"]
Digest --> Sign["Agent signs digest off-chain"]
Sign --> Register["Call registerAgent(agentAddress, pubKey, signature)"]
Register --> Status{"Status = PendingBond?"}
Status --> |Yes| Stake["Deposit stake >= minimumStake"]
Stake --> Activate["updateStatus(PendingBond -> Active)"]
Status --> |No| Error["AlreadyRegistered or BadSignature"]
Activate --> End(["Active"])
Error --> End
Loading

Diagram sources

Section sources

Score Computation Troubleshooting

Common symptoms:

  • Scores do not finalize.
  • Committee rejects proposed scores.
  • Evidence verification fails.
  • Maturity feels too slow or too fast.

Resolution steps:

  1. Check factor caps: each factor must not exceed its maximum.
  2. Ensure the agent is scorable:
    • Registered and not slashed.
    • Bonded according to the stake view.
  3. Validate evidence root:
    • Rebuild Merkle proof for each payment leaf.
    • Compare against stored evidenceRoots.
  4. Use chain timestamps for time-sensitive logic to avoid host clock skew.
  5. Adjust maturity rate through governance if necessary; it cannot be set to zero, and on main not above 100 points a day.
  6. On main, finalizing also asks whether the proposer could still make the proposal: if it has lost ORACLE_ROLE or its operator standing, finalizeReputation reverts ProposerNotAuthorized and a replacement proposal (the primary's next epoch, or a checker's proposeIfEmpty) takes its place. The Arc testnet contracts do not check the proposer.
flowchart TD
Start(["Score Proposal"]) --> ValidateFactors["Validate factor caps"]
ValidateFactors --> Scorable{"Agent scorable?"}
Scorable --> |No| Reject["Revert: NotRegistered/Slashed/NotBonded"]
Scorable --> |Yes| StorePending["Store PendingScore + evidenceRoot"]
StorePending --> Window{"Challenge window active?"}
Window --> |Reject| Cancel["Committee rejects proposal"]
Window --> |Finalize| Mature["Set matured anchor and timestamp"]
Mature --> End(["Live score"])
Loading

Diagram sources

Section sources

Slash Dispute Handling

Common symptoms:

  • Agent stuck in Suspended state.
  • Slash proposal never executed or canceled.
  • Dispute freeze persists beyond expected period.

Resolution steps:

  1. Initiate slash:
    • Committee calls initiateSlash with victim and evidence hash.
    • Agent becomes Suspended immediately.
    • On main it reverts SlashCooldownActive if a proposal for the agent was dropped less than one challenge period ago.
  2. Dispute:
    • Operator calls disputeSlash within the challenge deadline.
    • Proposal moves to Disputed; stake remains frozen.
  3. Resolution:
    • On main the admin resolves, not the committee: uphold executes the slash, but only after the challenge deadline fixed when the slash was filed (ChallengePeriodActive before then); drop cancels at any time and reinstates if bonded. The admin can also vetoSlash a pending or disputed proposal. The Arc testnet contracts have worked this way since 26 October 2026. On main an uphold is also refused once the dispute can be expired (DisputeResolutionExpired); the testnet takes that at its next upgrade.
    • If unresolved, anyone may expireDispute after the resolution period (14 days).
  4. Execution:
    • Anyone may executeSlash after the challenge period without dispute, as long as the reporter still holds the committee role. On main, a pending slash that nobody executes can be dropped by anyone with expireSlash 14 days after its deadline, so execute promptly.
    • Distribution: 50% burn, 25% victim, 25% reporter.
    • Identity marked Slashed; reputation zeroed.
sequenceDiagram
participant V as "Victim"
participant C as "Committee"
participant S as "SigvaraStaking"
participant I as "SigvaraIdentity"
participant R as "SigvaraReputation"
V->>C : "Report agent + evidence"
C->>S : "initiateSlash(didHash, victim, evidenceHash)"
S->>I : "updateStatus(Suspended)"
Note over S : "Challenge period begins"
alt "Operator disputes"
Op->>S : "disputeSlash(didHash)"
Admin->>S : "resolveDispute(didHash, uphold/drop)"
else "Undisputed"
Any->>S : "executeSlash(didHash)"
S->>I : "updateStatus(Slashed)"
S->>R : "zeroReputation(didHash)"
end
Loading

Diagram sources

Section sources

Integration Scenarios

Common symptoms:

  • SDK gate rejects agents unexpectedly.
  • Agent-to-agent authentication fails.
  • On-chain consumers cannot read scores reliably.

Resolution steps:

  1. Gate checks:
    • Verify proof validity, replay protection, active status, and threshold.
    • Use a shared NonceStore behind load balancers.
  2. Agent-to-agent auth:
    • Verifier issues a challenge payload including DID, nonce, and timestamp.
    • Prover signs with Ed25519 private key.
    • Verifier resolves public key from chain and verifies signature and threshold.
  3. On-chain reads:
    • Use getTotalScore/meetsThreshold for decisions.
    • Handle provider failures gracefully; consider retries and backoff.
sequenceDiagram
participant A as "Agent A"
participant B as "Agent B"
participant ID as "SigvaraIdentity"
participant REP as "SigvaraReputation"
B->>A : "Challenge : SIGVARA-VERIFY : {DID} : {nonce} : {timestamp}"
A->>A : "Sign payload with Ed25519"
A->>B : "{did, signature}"
B->>ID : "getIdentity(didHash)"
ID-->>B : "{pubKey, status}"
B->>REP : "meetsThreshold(didHash, threshold)"
REP-->>B : "true/false"
alt "Valid and meets threshold"
B-->>A : "Action permitted"
else "Invalid or below threshold"
B-->>A : "Rejected"
end
Loading

Diagram sources

Section sources

Dependency Analysis

Key dependencies:

  • SigvaraStaking depends on SigvaraIdentity for status and operator checks.
  • SigvaraReputation depends on SigvaraIdentity for scorable checks and optionally on an operator bond registry.
  • Oracle chain helpers depend on ethers contracts and implement backoff, slot-race detection, and rate-limit classification.
classDiagram
class SigvaraIdentity {
+registerAgent()
+rotatePublicKey()
+updateStatus()
+offerOperatorTransfer()
+acceptOperatorTransfer()
}
class SigvaraStaking {
+depositStake()
+initiateWithdrawal()
+claimWithdrawal()
+initiateSlash()
+disputeSlash()
+resolveDispute()
+expireDispute()
+expireSlash()
+cancelSlash()
+vetoSlash()
+executeSlash()
}
class SigvaraReputation {
+proposeReputation()
+proposeIfEmpty()
+finalizeReputation()
+rejectReputation()
+zeroReputation()
+getTotalScore()
+verifyEvidence()
}
class ChainHelpers {
+readWithBackoff()
+isSlotTaken()
+isRateLimited()
+proposeScore()
+finalizeScore()
+getPendingScore()
+getTotalScore()
}
SigvaraStaking --> SigvaraIdentity : "status checks"
SigvaraReputation --> SigvaraIdentity : "scorable checks"
ChainHelpers --> SigvaraReputation : "propose/finalize"
ChainHelpers --> SigvaraIdentity : "identity queries"
Loading

Diagram sources

Section sources

Performance Considerations

Gas optimization tips:

  • Batch operations where possible; avoid redundant reads in hot paths.
  • Prefer paged accessors for large operator agent lists.
  • Use view calls locally when safe (e.g., didHash derivation verified once per process).
  • Avoid unnecessary token approvals; check allowance before depositing.

Query performance:

  • Use readWithBackoff for transient RPC failures; distinguish genuine reverts from node errors.
  • Chunk log scans to respect provider limits and checkpoint progress frequently.
  • Cache stake view contract instance to reduce repeated lookups.

Caching strategies:

  • Use response cache for expensive endpoints like evidence generation.
  • Size cache by serialized bytes; evict least-recently-used entries.
  • Invalidate via revision tokens rather than explicit invalidation calls.

Section sources

Troubleshooting Guide

Agent Registration Issues

Symptoms:

  • BadRegistrationSignature or AlreadyRegistered.
  • PendingBond never becomes Active.
  • Cannot rotate key or transfer operator.

Checklist:

  • Confirm agent signed the registration digest returned by the registry.
  • Ensure the agent address is not already registered.
  • Deposit stake at least equal to minimumStake to activate.
  • For key compromise: suspend, rotate key, reinstate after rebonding.
  • For operator transfer: offer then accept; transfers blocked during slash pending.

Errors to watch:

  • BadRegistrationSignature
  • AlreadyRegistered
  • InsufficientCollateral
  • TransferWhileSlashPending
  • SlashSuspensionLocked

Section sources

Score Computation Failures

Symptoms:

  • proposeReputation reverts with factor out-of-range.
  • finalizeReputation reverts with NoScorePending or ChallengeWindowActive.
  • Evidence verification returns false.

Checklist:

  • Validate all six factors against their caps.
  • Ensure agent is scorable (registered, not slashed, bonded).
  • Recompute evidence root and verify leaf proofs.
  • Use chain timestamps for timing checks.
  • Governance-adjust maturity rate if needed; zero is rejected, and on main so is anything above 100 points a day.
  • On main, finalizeReputation reverts ProposerNotAuthorized for a proposal whose proposer has lost its standing; a replacement proposal supersedes it.

Errors to watch:

  • ScoreOutOfRange
  • NoScorePending
  • ChallengeWindowActive
  • ProposerNotAuthorized (on main)
  • IdentityRegistryNotSet
  • StakeViewNotSet
  • AgentNotRegistered
  • AgentSlashed
  • AgentNotBonded

Section sources

Oracle Operator Errors

Symptoms:

  • Slot taken repeatedly.
  • Rate-limited writes.
  • Operator standing denied.

Checklist:

  • Distinguish slot-taken from real failures using isSlotTaken.
  • Classify rate limiting using isRateLimited; do not retry writes.
  • Check operatorStanding at startup; ensure wallet is admitted and bonded.
  • Use proposeIfEmpty for checker mode to avoid overwriting primary proposals. On main it also replaces a pending proposal whose proposer has lost its authority; the Arc testnet contracts revert for any pending proposal.
  • Tell a transaction the oracle would not sign (a fee above MAX_FEE_GWEI or a worst-case cost above MAX_TX_COST) or never saw mined from the contract refusing it: they are counted in sigvara_oracle_tx_refused_total{reason}, and the cause is the RPC.
  • If the oracle will not start, read the first lines of its log. It names every numeric setting it cannot use, a wrong ORACLE_MODE, a key that is not 64 hex characters (the value is never printed), a non-loopback bind with no write credential, a state file it cannot use, and an RPC on a chain other than EXPECTED_CHAIN_ID.

Errors to watch:

  • ScoreAlreadyPending
  • OracleNotBonded
  • ProposerNotAuthorized (on main)
  • AlreadyCharged (the oracle counts it as paid)
  • Provider throttling (-32005, 429)

Section sources

Slash Lifecycle Problems

Symptoms:

  • Agent remains Suspended.
  • Slash proposal never executed or canceled.
  • Dispute freeze persists.

Checklist:

  • Verify challenge deadline and dispute deadlines.
  • The admin must resolve disputed slashes; otherwise expireDispute after period.
  • ExecuteSlash requires undisputed window to have elapsed, and the reporter to still hold the committee role (ReporterNotAuthorized otherwise).
  • On main, a pending slash that nobody executes or cancels can be expired with expireSlash once 14 days have passed since its deadline.
  • After execution, identity becomes Slashed and reputation is zeroed.

Errors to watch:

  • ChallengePeriodActive
  • ChallengePeriodExpired
  • SlashAlreadyPending
  • SlashNotDisputed
  • DisputeResolutionActive
  • DisputeResolutionExpired (on main)
  • SlashCooldownActive (on main)
  • ExecutionPeriodActive (on main)

Section sources

Security Incident Response

Key procedures:

  • Key compromise:
    • Immediately suspend the agent.
    • Rotate Ed25519 key.
    • Reinstate after rebonding if required.
  • Slash dispute:
    • The admin upholds or drops; expired disputes can be cleared.
  • Emergency:
    • Follow the security policy and report privately.
    • Coordinate disclosure after fix availability.

Section sources

Conclusion

This guide consolidates common failure modes across registration, scoring, slashing, and integration, with concrete resolutions mapped to the protocol contracts and oracle implementation. Use the diagnostic helpers for RPC resilience, classify slot races and throttling correctly, and rely on evidence roots and maturity mechanics to maintain trustworthiness. For ongoing issues, consult the security policy and coordinate responsibly.

Appendices

Frequently Asked Questions

Conceptual questions:

  • What does the reputation score represent?
    • It is a normalized, capped sum of six factors derived from payment-backed attestations, community flags, external trust, and counterparty standing. Only bonded agents are scored.
  • How does staking work?
    • Operators deposit stake to back agents. Bonds enable slashing; withdrawals enter an unbonding queue still subject to slash sweeps.
  • What is the protocol economics model?
    • Slashed stake is partially burned, with portions awarded to victims and reporters. Fees may gate epoch scoring when configured.

Operational questions:

  • Why is my score not finalizing?
    • Check factor caps, scorable status, evidence root, and challenge window timing.
  • Why does the gate reject my agent?
    • Verify proof validity, replay protection, active status, and threshold.
  • How do I recover from a compromised key?
    • Suspend, rotate key, reinstate after rebonding.

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