Repository navigation
Cross Chain Considerations
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
This document explains how to deploy Sigvara across multiple blockchain networks and how cross-chain operations should be designed around the current codebase. The repository currently implements a single-chain trust layer on top of ERC-8004 identity, with an off-chain oracle that computes reputation scores and writes them to SigvaraReputation. Cross-chain state mirroring is planned for Solana and Base via LayerZero, but no bridge contracts or cross-chain message-passing logic are present in this repository today.
The key design constraint for any future cross-chain deployment is that agent identities are chain-scoped: the DID method embeds the source chain ID into the identifier and its hash. That makes direct identity reuse across chains unsafe without explicit bridging rules. Reputation scores are also anchored per chain because they depend on on-chain payments, feedback, slashing history, maturity time, and operator handovers.
For multi-chain deployments, the safest approach is to treat each network as an independent Sigvara instance with its own registry, staking asset, oracle operators, and governance, while using shared operational practices, monitoring, and upgrade procedures. Any future cross-chain bridge must preserve slashability, ownership, maturity, and evidence integrity rather than merely copying score numbers.
At a high level, the repository contains:
- Solidity contracts for identity, reputation, staking, oracle bonding, fees, and token utilities.
- Foundry scripts for deployment and upgrades.
- A Node-based oracle service that indexes events, verifies payment-backed attestations, and proposes/finalizes scores.
- A TypeScript SDK for consumers and integration tests.
- Documentation covering architecture, Arc deployment, quickstart, and security posture.
graph TB
subgraph "Contracts"
ID["SigvaraIdentity"]
REP["SigvaraReputation"]
STK["SigvaraStaking"]
ORB["SigvaraOracleBond"]
FEES["SigvaraEpochFees"]
SVR["SVRToken"]
end
subgraph "Scripts"
DEP["Deploy.s.sol"]
UPG["Upgrade.s.sol"]
end
subgraph "Oracle Service"
ORA["Oracle Indexer<br/>Event Scanner + Score Computation"]
EXT["External Feed Reader"]
end
subgraph "SDK"
TS_SDK["TypeScript SDK"]
end
DEP --> ID
DEP --> REP
DEP --> STK
DEP --> SVR
UPG --> ID
UPG --> REP
UPG --> STK
UPG --> ORB
UPG --> FEES
ORA --> ID
ORA --> REP
ORA --> STK
EXT --> ID
EXT --> REP
TS_SDK --> ID
TS_SDK --> REP
TS_SDK --> STK
Diagram sources
Section sources
For multi-chain deployment, the following components must be understood and replicated per chain:
| Component | Responsibility | Multi-Chain Implication |
|---|---|---|
SigvaraIdentity |
Registers agents, stores operator, Ed25519 public key, status, transfer history, and derives chain-scoped DIDs. | Each chain gets its own identity registry; the same agent address has different DIDs across chains. |
SigvaraReputation |
Anchors computed reputation scores, challenge windows, maturity, and slash effects. | Scores cannot be blindly copied across chains; they must be recomputed from local evidence. |
SigvaraStaking |
Manages bonds, slashing, unbonding, and minimum stake enforcement. | Bond assets and gas tokens differ by chain; Arc uses USDC as native gas and testnet uses a faucet SVR token. |
SigvaraOracleBond |
Records bonded oracle operators and enables slashing of operator performance bonds. | Operator sets should be independent per chain unless a coordinated cross-chain governance model is implemented. |
SigvaraEpochFees |
Collects epoch fees when enabled. Never deployed, and left out of the mainnet launch and the first audit. | Fee policy and collection may vary by chain. script/DeployEpochFees.s.sol refuses chain 5042. |
| Oracle service | Scans identity/reputation events, verifies payment-backed attestations, computes scores, and proposes/finalizes them. | Each chain needs its own indexer configuration, RPC provider, start block, and external feed settings. |
| TypeScript SDK | Provides registration, verification, challenge-response, and threshold checks. | Consumers configure one chain at a time through addresses and chain ID. |
SigvaraReader |
Stateless read helper for on-chain consumers: isTrusted, isTrustedFresh (adds a limit on the score’s age) and trust. The protocol never calls it, and it is not yet deployed on any chain. |
Deploy one per chain, pointed at that chain’s identity, reputation and staking proxies. |
Section sources
Sigvara is not itself a cross-chain protocol. It is a computed-reputation and staked-slashing layer built on top of ERC-8004 identity and raw feedback. The roadmap explicitly lists cross-chain work as a future phase involving Solana and Base state mirroring via LayerZero.
graph TB
subgraph "Current Single-Chain Design"
EID["ERC-8004 Identity Registry"]
EREP["ERC-8004 Reputation Registry"]
SIG_ID["SigvaraIdentity"]
SIG_REP["SigvaraReputation"]
SIG_STK["SigvaraStaking"]
ORA["Oracle Service"]
end
subgraph "Planned Cross-Chain Phase"
ARC["Arc / Ethereum-like Chain"]
BASE["Base"]
SOL["Solana"]
LZ["LayerZero Bridge (planned)"]
end
EID --> ORA
EREP --> ORA
ORA --> SIG_REP
SIG_STK --> SIG_REP
SIG_ID --> SIG_REP
ARC --- LZ
BASE --- LZ
SOL --- LZ
Note["Cross-chain state mirroring is planned for Q2 2027.<br/>No bridge implementation exists in this repository."]
Diagram sources
Section sources
The DID method is did:sigvara:<chainId>:<agentAddress>, and the on-chain index key is derived from the chain ID and agent address. This means:
- An agent registered on Arc testnet (
5042002) has a different DID from the same address on Arc mainnet (5042). - A bridge cannot simply move a DID across chains without defining which chain’s identity is authoritative.
- If a bridge mirrors identity, it must decide whether the mirrored identity is read-only, transferable, or bound to a new operator on the destination chain.
flowchart TD
Start["Agent registers on Source Chain"] --> DeriveDID["Derive didHash from chainId + agentAddress"]
DeriveDID --> StoreOnSource["Store identity on source chain"]
StoreOnSource --> CheckBridge{"Cross-chain bridge required?"}
CheckBridge --> |No| LocalUse["Use locally on source chain"]
CheckBridge --> |Yes| DefineRules["Define cross-chain identity rules"]
DefineRules --> DestinationChain["Mirror or re-register on destination chain"]
DestinationChain --> NewDID["Destination DID includes destination chainId"]
NewDID --> LocalUse
Diagram sources
Section sources
Reputation is not just a number. It is composed of fee activity, success rate, tenure, external trust, community flags, and propagation. The oracle proposes a score, the contract stores a proposed score during a challenge window, and after finalization the score matures over time. Slashing zeroes the score and clears the maturity anchor.
For cross-chain synchronization:
- Do not copy finalized scores directly between chains.
- Use the destination chain’s oracle to recompute scores from destination-chain evidence.
- If a bridge carries ERC-8004 feedback or payment settlement proofs, those become inputs to the destination oracle, not the output.
- Maturity must restart or be recalculated on the destination chain because it depends on local timestamps, handovers, and slash history.
sequenceDiagram
participant SRC as "Source Chain"
participant ORA_SRC as "Source Oracle"
participant REP_SRC as "SigvaraReputation (Source)"
participant BRIDGE as "Planned Bridge"
participant ORA_DST as "Destination Oracle"
participant REP_DST as "SigvaraReputation (Destination)"
SRC->>ORA_SRC : Provide attestations and payment data
ORA_SRC->>REP_SRC : proposeReputation(didHash, data, evidenceRoot)
REP_SRC-->>ORA_SRC : Challenge window open
ORA_SRC->>REP_SRC : finalizeReputation(didHash)
REP_SRC-->>SRC : Matured score available
Note over SRC,REP_SRC : Score is anchored locally and cannot be safely copied.
BRIDGE->>ORA_DST : Carry verified evidence or feedback roots
ORA_DST->>REP_DST : Recompute score from destination-chain data
REP_DST-->>SRC : Destination score is independent
Diagram sources
Section sources
The repository already supports deploying to multiple EVM networks through Foundry scripts and environment-driven configuration. The Arc deployment guide shows how chain-specific facts such as gas tokens, RPC endpoints, explorer behavior, and bond token decimals affect deployment.
Recommended multi-chain patterns:
- Per-chain deployment artifacts: keep
deployments/{chainId}.jsonfor each target network. - Per-chain operator sets: do not assume the same oracle wallet can operate all chains identically.
- Per-chain bond assets: Arc uses USDC as native gas and testnet uses a faucet SVR token; mainnet will use SVR according to token policy.
- Per-chain launch parameters: the contracts hold the period floors and ceilings (score window, slash challenge, unbonding, maturity rate) on every chain, but the deploy scripts’ launch checks apply only on chain 5042 (Arc mainnet). There they refuse a missing or non-18-decimal bond token, a minimum stake under 10,000 SVR, an operator bond under 2,500,000 SVR, and a missing guardian or one that is the deployer, the oracle, the committee or the slasher. On any other chain the testnet defaults apply unless the numbers are stated, except that
DeployOracleBondrefuses one address as both slasher and payee on every chain, and both default to the deployer, so a run that states neither stops. The bond-token check is inDeploy.s.solonly. - Per-chain pause guardian:
GUARDIAN_ADDRESSis optional on a testnet and required on mainnet. It can pause new registrations, stake deposits, score proposals and bond deposits for three days at a time, and nothing else. - Per-chain upgrade procedures: simulate against forks, verify proxy storage slots, and rehearse critical upgrades before broadcasting.
flowchart TD
Plan["Select target chains"] --> Config["Configure RPC, chainId, gas token, bond token"]
Config --> Deploy["Run Deploy.s.sol per chain"]
Deploy --> Artifacts["Commit deployments/{chainId}.json"]
Artifacts --> OracleConfig["Point oracle at chain"]
OracleConfig --> Verify["Run SDK integration tests"]
Verify --> Monitor["Monitor health, divergence, and metrics"]
Diagram sources
Section sources
The deployment script deploys implementations, deploys UUPS proxies, initializes contracts, wires roles, and writes addresses to deployments/{chainId}.json. Upgrades deploy fresh implementations and update proxy pointers.
Key instantiation rules for multi-chain deployments:
- Always deploy fresh implementations per chain.
- Initialize reputation with the identity registry address before enabling scoring.
- Initialize staking with identity, reputation, and bond token addresses.
- Set maturity rate and other chain-specific parameters during initialization.
- Record proxy and implementation addresses for rollback and incident review.
classDiagram
class SigvaraIdentity {
+registerAgent(agentAddress, ed25519PubKey, signature)
+updateStatus(didHash, newStatus)
+rotatePublicKey(didHash, newEd25519PubKey)
+computeDidHash(agentAddress)
}
class SigvaraReputation {
+proposeReputation(didHash, data, evidenceRoot)
+finalizeReputation(didHash)
+getTotalScore(didHash)
+meetsThreshold(didHash, threshold)
+zeroReputation(didHash)
}
class SigvaraStaking {
+depositStake(didHash, amount)
+initiateSlash(didHash, victim, evidenceHash)
+executeSlash(didHash)
+hasMinimumStake(didHash) bool
}
class SigvaraOracleBond {
+admit(operator)
+isActiveOperator(address) bool
+bondOf(address) uint256
}
SigvaraReputation --> SigvaraIdentity : "validates identity"
SigvaraStaking --> SigvaraIdentity : "checks status and stake view"
SigvaraStaking --> SigvaraReputation : "slash zeroes score"
SigvaraReputation --> SigvaraOracleBond : "requires bonded operator"
Diagram sources
Section sources
Arc demonstrates how network differences matter:
- Gas token: USDC is native gas on Arc, not ETH.
- Bond token configuration: the contracts take the bond token by address at initialization, and decimals must match the intended economic model.
- RPC providers: production oracle indexing should use a dedicated provider rather than the public endpoint, and the provider has to be measured, not assumed. On Arc testnet only QuickNode worked among the alternatives: dRPC accepts
eth_getLogsranges of only about 100 blocks, and Blockdaemon returns nothing for older transactions. - External feeds: the oracle can read an external ERC-8004 feed on another chain (Base Sepolia historically), but that is a read-only signal, not a bridge.
flowchart TD
Env[".env or environment variables"] --> Oracle["Oracle service"]
Env --> SDK["TypeScript SDK"]
Oracle --> ChainRPC["Chain RPC"]
Oracle --> ExternalRPC["External RPC for ERC-8004 feed"]
SDK --> ChainRPC
ChainRPC --> Contracts["Identity, Reputation, Staking"]
ExternalRPC --> ExternalContracts["External Identity/Reputation"]
Diagram sources
Section sources
Because cross-chain bridges are not yet implemented, the most important security guidance is to avoid assumptions about trustless identity or reputation movement.
Critical risks:
- Bridge vulnerabilities: A bridge that copies state without verifying ownership, slashing history, or maturity can create false trust.
- Reentrancy attacks: While not specific to cross-chain, any bridge contract interacting with Sigvara contracts must respect reentrancy guards and the order of state changes.
- State consistency guarantees: A destination chain must never accept a score higher than what its local oracle would compute from verified evidence.
- Identity hijacking: Bridging a DID without proving control of the agent address or operator can allow attackers to impersonate agents.
- Slashing evasion: If a bridge moves an agent to a new chain without transferring bond exposure, the agent becomes unslashable on the destination.
- Maturity manipulation: Copying a matured score bypasses the intended delay that prevents newly acquired reputation from being instantly spent.
Operational safeguards:
- Treat each chain as independently governed until a formal cross-chain governance model is audited.
- Require destination-chain oracle recomputation instead of trusting source-chain scores.
- Keep slash authority and operator admission separate from bridge administration.
- Monitor bridge liveness, message delivery, and disagreement rates.
Section sources
The oracle service is the operational heart of multi-chain deployment. For each network:
- Configure RPC URL, identity contract address, reputation contract address, and start block.
- Set
EXPECTED_CHAIN_ID(5042for Arc mainnet,5042002for the testnet). With it set, nothing is read for scoring or signed while the RPC reports another chain. A state file saved on another chain is refused either way. Unset, the oracle signs for whatever chainRPC_URLserves and says so at startup. - Fund the oracle wallet with the chain’s gas token.
- Enable payment scanning if desired, understanding that it changes scores and requires consistent configuration across operators.
- Point external feeds only if reading another chain’s ERC-8004 feedback is supported and configured.
flowchart TD
Start["Start oracle node"] --> LoadEnv["Load .env configuration"]
LoadEnv --> InitChain["Initialize chain reader"]
InitChain --> ScanEvents["Scan AgentRegistered and related events"]
ScanEvents --> ComputeScores["Compute 6-factor reputation"]
ComputeScores --> Propose["Propose reputation on chain"]
Propose --> Finalize["Finalize after challenge window"]
Finalize --> Health["Publish health and metrics"]
Diagram sources
Section sources
Network latency affects both event indexing and transaction submission:
- Use reliable RPC providers for oracle indexing rather than public endpoints.
- Avoid relying on a single host for primary oracle, checker, and watcher processes.
- Handle timeouts when refreshing chain IDs or reading external feeds.
- Ensure only one oracle instance runs per signing key to avoid nonce collisions.
flowchart TD
RPC["RPC Provider"] --> Timeout{"Request timed out?"}
Timeout --> |Yes| Retry["Retry with backoff or alternate RPC"]
Timeout --> |No| Read["Read chainId or logs"]
Retry --> Read
Read --> Cache["Cache chainId and errors"]
Cache --> Health["Report health status"]
Diagram sources
Section sources
Gas optimization differs by chain:
- On Arc, gas is paid in USDC as the native token, so fee estimation and script execution may require legacy mode if standard EIP-1559 estimation fails.
- Bond token decimals matter: if pointing bonds at USDC, ensure amounts and contract initialization match the token’s decimal model. On chain 5042 the deploy script refuses a bond token that is not 18 decimals.
- Batch operations where possible, but do not batch unrelated cross-chain state changes.
- Separate simulation and broadcast steps to reduce risk.
flowchart TD
Estimate["Estimate gas"] --> ArcCheck{"Is gas token USDC-native?"}
ArcCheck --> |Yes| LegacyFallback["Retry with legacy mode if needed"]
ArcCheck --> |No| StandardFlow["Standard EVM gas flow"]
LegacyFallback --> Broadcast["Broadcast deployment or upgrade"]
StandardFlow --> Broadcast
Broadcast --> Verify["Verify deployed addresses and roles"]
Diagram sources
Section sources
Monitoring should cover:
- Oracle health and divergence endpoints.
- Payment scan progress and start blocks.
- External feed connectivity and chain ID.
- Operator bonding status and ability to propose.
- Proxy implementation versions and upgrade history.
- SDK integration test results against live chains.
graph TB
subgraph "Monitoring Surface"
Health["/health"]
Divergence["/divergence"]
Evidence["/evidence/:didHash"]
Metrics["/metrics"]
end
subgraph "Alerts"
OracleDown["Oracle down"]
DivergenceHigh["Disagreement rate high"]
ExternalFeedBroken["External feed broken"]
OperatorNotBonded["Operator not bonded or admitted"]
UpgradeMismatch["Proxy implementation mismatch"]
end
Health --> OracleDown
Divergence --> DivergenceHigh
Metrics --> ExternalFeedBroken
Metrics --> OperatorNotBonded
Metrics --> UpgradeMismatch
Diagram sources
Section sources
The core dependency relationships relevant to multi-chain deployment are:
-
SigvaraReputationdepends onSigvaraIdentityto validate that a DID was registered and that the agent is not slashed. -
SigvaraStakingdepends onSigvaraIdentityfor status and stake-view wiring. - The oracle depends on both identity and reputation contracts, plus optional external feeds.
- The SDK depends on ABIs and addresses for identity, reputation, and staking.
graph LR
SDK["SDK"] --> ID["SigvaraIdentity"]
SDK --> REP["SigvaraReputation"]
SDK --> STK["SigvaraStaking"]
ORA["Oracle"] --> ID
ORA --> REP
ORA --> STK
REP --> ID
STK --> ID
Diagram sources
Section sources
Multi-chain performance depends on oracle scalability, RPC reliability, and chain throughput:
- Run primary, checker, and watcher on separate hosts with separate RPC providers.
- Rate-limit public read endpoints like
/scoreand/evidencebecause they perform chain reads and Merkle tree reconstruction. - Avoid running multiple oracle instances with the same signing key due to nonce collisions.
- Prefer deterministic, forward-only scanning for payment events and persist checkpoints carefully.
- Keep external feed failures fail-safe so missing ERC-8004 feedback reduces a factor rather than breaking an epoch.
Section sources
Common multi-chain and cross-chain readiness issues:
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Oracle cannot propose scores | Operator not bonded or not admitted, or the signing wallet is not the signer its operator named (main) | Check SigvaraOracleBond.isActiveOperator for the signing wallet and the admin admission steps. |
| Reputation proposals revert | Identity registry not wired or stake view not set | Upgrade reputation and identity in the documented order and initialize required storage. |
| External score remains zero | No ERC-8004 link or external feed unreachable | Configure external RPC and verify agent linkage; external feed failure should not break epochs, except with EXTERNAL_LINK_FROM_BLOCK set, where a registry whose chain cannot be read stops all scoring (docs/operations-runbook.md, section 3). |
| Payment factors collapse after restart | State file lost or not on a persistent volume, so recorded payments and outcomes are gone | Restore the newest off-box copy if there is one (docs/operations-runbook.md, section 1). Otherwise re-post the settlement hashes to /attest with a token, adding success only where the primary holds a token holder's outcome; payer-signed outcomes the other operator holds come back through the import at the next epoch, unless their deadline passed more than PAYER_OUTCOMES_IMPORT_GRACE_HOURS before it runs. The scan restarts at PAYMENT_SCAN_FROM_BLOCK by itself, because its checkpoint was in the lost file, and it never refills an outcome. |
Registrations, deposits, proposals or bond deposits revert with InflowsPausedUntil
|
A guardian pause is running | Wait for the time in the error, at most three days, or for the guardian or admin to lift it. Exits, disputes, rulings, slash execution and finalization are not paused. |
| Same-key oracle transactions collide | Multiple instances running with same private key | Run only one instance per signing key. |
| Cross-chain score mismatch | Attempting to copy source score to destination | Recompute destination score from destination-chain evidence. |
Section sources
Sigvara’s current codebase is a single-chain computed-reputation and staked-slashing layer. Cross-chain support is planned for Solana and Base via LayerZero, but no bridge contracts or cross-chain protocols exist in this repository. For multi-chain deployments today, the correct pattern is to deploy independent Sigvara instances per chain, configure per-chain oracle nodes, and enforce strict separation of identity, reputation, staking, and governance.
Any future cross-chain bridge must treat identity as chain-bound, reputation as recomputable only from verified evidence, and slashing as non-transferable unless explicitly modeled. The safest cross-chain strategy is to mirror verifiable inputs—such as payment settlement proofs or ERC-8004 feedback roots—and let each destination chain compute its own matured, slashable reputation.
The repository’s roadmap identifies cross-chain as a future phase. Until then, treat every chain as an isolated trust domain.
Section sources
The Arc testnet runbook provides a concrete example of role assignment, deployment commands, and pre-deployment security considerations.
Section sources
- 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