Repository navigation
Development Environment Setup
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
This document explains how to set up a complete Sigvara development environment. It covers:
- Installing and configuring the Foundry toolchain for Solidity contracts
- Installing Node.js and project dependencies for the Oracle service and TypeScript SDK
- Understanding key directories such as
src/,oracle/,packages/sdk/, andtest/ - Explaining configuration files including
foundry.toml, package scripts, and environment variables - Running initial builds and tests
- Verifying that your local setup is correct
- Troubleshooting common issues across Windows, macOS, and Linux
Sigvara is an on-chain reputation and staking layer built on top of ERC-8004 identity. The repository contains:
- Solidity contracts under
src/ - Foundry scripts under
script/ - Oracle service under
oracle/ - TypeScript SDK under
packages/sdk/ - Tests under
test/and per-package test folders - Documentation under
docs/
The repository’s own README provides the high-level contract setup commands and describes the protocol architecture, while the Arc deployment guide and quickstart provide chain-specific details and environment variable examples.
Section sources
At a high level, the repository is organized by responsibility:
| Directory | Purpose | What you will work with here |
|---|---|---|
src/ |
Solidity contracts | Reputation, staking, identity, oracle bond, token, and epoch fees, plus the stateless SigvaraReader and the shared InflowGuard and TimelockedGrants contracts |
script/ |
Foundry deployment and upgrade scripts | Deploy, upgrade, split authority, deploy the reader, and other on-chain operations |
scripts/ |
Repository checks and tools |
fetch-deps.sh (Solidity dependencies), check-docs.mjs, check-headers.mjs, check-evidence-fixture.mjs, and the chain and deployment helpers |
examples/ |
Worked examples | The MCP-gated tool (mcp-gated-tool/) and a gated marketplace contract (gated-marketplace/) |
test/ |
Foundry-based contract tests | Unit, fuzz, invariant, E2E, and upgrade tests |
oracle/ |
Node.js reputation oracle | Epoch scoring, attestations, evidence, metrics, and HTTP endpoints |
packages/sdk/ |
TypeScript SDK | Agent identity, reputation, challenge-response authentication, and verifier utilities |
docs/ |
Protocol and developer documentation | Architecture, quickstart, Arc deployment, token model, and security notes |
site/ |
Website assets and pages | Public site, docs, demo pages, the read-only explorer (agents, operators, slashes), the score epochs and simulation pages, and client-side code |
sim/ |
Testnet simulation | A labelled simulation that runs 20 agents, 40 customers, a Sybil ring and two slashes on Arc testnet for four weeks; see docs/simulation.md
|
deployments/ |
Live deployment artifacts | Chain ID-specific JSON files with proxy addresses and implementation history, and 5042002.simulation.json, every address the testnet simulation controls |
archive/token-launch/ |
Historical token launch material | Out-of-build token contracts and related docs |
graph TB
Root["Repository Root"] --> Src["src/ — Solidity contracts"]
Root --> Script["script/ — Foundry deploy/upgrade scripts"]
Root --> Test["test/ — Foundry contract tests"]
Root --> Oracle["oracle/ — Node.js reputation oracle"]
Root --> Sdk["packages/sdk/ — TypeScript SDK"]
Root --> Docs["docs/ — Protocol and developer guides"]
Root --> Site["site/ — Website assets"]
Root --> Deployments["deployments/ — On-chain deployment artifacts"]
Diagram sources
Section sources
This section summarizes the main components you will interact with during setup.
The core protocol contracts include:
- Computed reputation anchor
- Staked accountability and slashing logic
- Identity registry used today
- Oracle bond registry
- Token and epoch fee contracts
These contracts are compiled and tested with Foundry. The repository’s README documents the basic Foundry workflow: install dependencies, build, and run tests.
Section sources
The Oracle is a Node.js service that:
- Scans registered agents
- Computes a six-factor score from payment-verified attestations and watchdog signals
- Proposes scores on-chain along with a Merkle root over the evidence
- Exposes health, metrics, attestation, flag, evidence, and badge endpoints
Its package.json declares Node.js 18 or newer, dotenv, and ethers. The Oracle README provides a quick start, Docker deployment guidance, API behavior, environment variables, and production checklist items.
Section sources
The SDK provides:
- Agent identity management
- Reputation queries
- Challenge-response authentication
- On-chain registration helpers
Its package.json defines build, test, and typecheck scripts, a prepublishOnly hook that builds the package and runs the tests before a release, and depends on ethers and tweetnacl. The README shows how to install and use the SDK for gating, agent-to-agent verification, registration, and DID resolution.
Section sources
Foundry tests cover unit, fuzz, invariant, E2E, and upgrade scenarios. The Oracle has its own Node.js test suite, and the SDK uses Vitest. The README lists the default commands for running each suite.
Section sources
For development setup purposes, think of Sigvara as three layers:
- On-chain layer: Solidity contracts manage identity, reputation, staking, bonds, and fees.
- Off-chain oracle layer: A Node.js service reads chain data, verifies payments, computes scores, and proposes updates.
- Client layer: Applications and agents use the TypeScript SDK to register agents, verify identities, and check reputation thresholds.
graph TB
Client["Client / Agent App"] --> Sdk["@sigvara/protocol-sdk"]
Sdk --> Contracts["Solidity Contracts<br/>Identity, Reputation, Staking, Oracle Bond"]
Client --> Oracle["Oracle Service<br/>Node.js"]
Oracle --> Contracts
Oracle --> Rpc["Chain RPC Endpoint"]
Diagram sources
Foundry is required to compile, script, and test the Solidity contracts. The repository’s README gives the minimal workflow: clone, install dependencies, build, and run tests.
Key configuration lives in foundry.toml:
- Source directory is
src/ - Output directory is
out/ - Libraries are resolved from
lib/ - Remappings point to OpenZeppelin contracts and Forge std
- Optimizer is enabled with a configured number of runs
- Solidity compiler version is pinned, and so is the EVM version (
cancun) - Fuzz profiles define default and CI iteration counts
- RPC endpoints for Arc testnet and Arc mainnet are defined
flowchart TD
Start(["Developer runs Foundry command"]) --> ReadConfig["Read foundry.toml"]
ReadConfig --> ResolveLibs["Resolve lib/ and remappings"]
ResolveLibs --> Compile["Compile src/ contracts"]
Compile --> RunTests["Run forge test"]
RunTests --> Result{"Tests pass?"}
Result --> |Yes| Ready["Contracts ready for scripting or deployment"]
Result --> |No| Debug["Inspect failing test and re-run"]
Diagram sources
Section sources
The Oracle and SDK are Node.js projects with different responsibilities:
| Package | Main purpose | Node.js requirement | Key scripts |
|---|---|---|---|
oracle/ |
Reputation oracle service | 18+ |
start, test
|
packages/sdk/ |
TypeScript SDK for clients | Not declared in package.json; the SDK README says Node 18 or newer, and CI runs Node 20 |
build, test, typecheck, prepublishOnly
|
The Oracle requires dotenv and ethers. The SDK depends on ethers and tweetnacl, and uses TypeScript and Vitest for building and testing.
Section sources
There are two major configuration surfaces:
The Oracle README documents required, recommended, optional, payment verification, and payment scan pull variables. At minimum, you need:
RPC_URL-
ORACLE_PRIVATE_KEY(orORACLE_PRIVATE_KEY_FILE, a path to a file holding the key; setting both stops the process) IDENTITY_ADDRESSREPUTATION_ADDRESS
Production also recommends:
ORACLE_ADMIN_TOKENORACLE_STATE_PATHEXPECTED_CHAIN_IDATTEST_COOLDOWN_MS
Every numeric setting is checked before anything starts. A value that is set and is not a plain number in range stops the process, with every offending setting named.
Payment verification and scanning add many more variables, including PAYMENT_VERIFICATION, PAYMENT_ASSET, PAYMENT_MIN_AMOUNT, PAYMENT_SCAN_ENABLED, and others.
The quickstart shows example .env values for operator private key, RPC URL, and contract addresses. The Arc guide shows how to set SDK integration test environment variables such as SIGVARA_RPC_URL, SIGVARA_CHAIN_ID, and the contract addresses.
flowchart TD
EnvStart["Set environment variables"] --> OracleEnv["Oracle .env"]
EnvStart --> SdkEnv["SDK integration test env"]
OracleEnv --> Required["Required: RPC_URL, ORACLE_PRIVATE_KEY,<br/>IDENTITY_ADDRESS, REPUTATION_ADDRESS"]
OracleEnv --> Optional["Optional: PAYMENT_VERIFICATION,<br/>PAYMENT_SCAN_ENABLED, etc."]
SdkEnv --> TestVars["SIGVARA_RPC_URL, SIGVARA_CHAIN_ID,<br/>contract addresses, operator key"]
Required --> RunOracle["Run oracle service"]
Optional --> RunOracle
TestVars --> RunSdkTests["Run SDK integration tests"]
Diagram sources
Section sources
Follow these steps to get a working local development environment.
Install Foundry so you can use forge and cast. The repository’s README states that Foundry is required for the contracts.
Clone the repository and fetch the Solidity dependencies with sh scripts/fetch-deps.sh. It fetches OpenZeppelin (v5.6.1) and forge-std, each by commit, into lib/, which is gitignored; the repository has no submodules and no forge install step.
Run the Foundry build command. This compiles the Solidity contracts using the settings in foundry.toml.
Run the full Foundry test suite. For higher-intensity fuzzing, use the CI profile. Everything runs offline except two fork suites: SlashDrillFork.t.sol forks Arc testnet on every run, so it needs the arc_testnet endpoint in foundry.toml to answer, and SplitAuthorityFork.t.sol skips its twelve tests unless you pass --fork-url https://rpc.testnet.arc.io. Without a fork URL, 712 of the 724 contract tests run and 12 skip.
Use Node.js 18 or newer. The Oracle explicitly requires Node 18+.
Navigate to oracle/ and install dependencies.
Copy the Oracle environment template and configure it with your RPC URL, private key, and contract addresses. The Oracle README explains required and optional variables.
Start the Oracle service locally. You can also use Docker if you prefer containerized operation.
Navigate to packages/sdk/ and install dependencies. Use the SDK’s build script to compile TypeScript output.
Run the SDK test suite with Vitest.
- Confirm
forge buildsucceeds - Confirm
forge testpasses - Confirm the Oracle starts without missing required variables
- Confirm the Oracle tests pass
- Confirm the SDK builds and tests pass
Section sources
This section maps the most important development-time dependencies.
graph LR
Dev["Developer Machine"] --> Foundry["Foundry<br/>forge, cast"]
Dev --> Node["Node.js >= 18"]
Foundry --> Contracts["src/ Solidity contracts"]
Foundry --> Scripts["script/ Foundry scripts"]
Foundry --> Tests["test/ Foundry tests"]
Node --> Oracle["oracle/ Node.js oracle"]
Node --> Sdk["packages/sdk/ TypeScript SDK"]
Oracle --> Ethers["ethers"]
Oracle --> Dotenv["dotenv"]
Sdk --> Ethers2["ethers"]
Sdk --> Nacl["tweetnacl"]
Sdk --> Tsc["typescript"]
Sdk --> Vitest["vitest"]
Diagram sources
Section sources
For local development, performance considerations are mostly about toolchain speed and test scope:
- Foundry caching makes repeated builds faster after the first compilation.
- Default Foundry tests run quickly against an in-memory EVM.
- The CI fuzz profile increases iterations, which is useful for deeper checks but slower locally.
- The Oracle’s
/evidenceendpoint rebuilds Merkle trees and can be expensive; rate limiting protects it in production. - SDK tests run through Vitest and should be fast unless they hit live chains.
When tuning your workflow:
- Use normal
forge testfor quick feedback. - Use the CI profile when investigating fuzz failures.
- Avoid running live integration tests unless you have the required wallet funds and RPC access.
- If
forgeis not recognized, ensure Foundry was installed and added to your system PATH. - If tests fail due to compiler or library issues, confirm that
sh scripts/fetch-deps.shran successfully and thatlib/contains the expected dependencies. If a directory underlib/is at another commit the script stops and says so; it never deletes anything, so remove that directory and run it again. - If deployment scripts fail at fee estimation on Arc, the Arc guide mentions retrying with legacy mode.
Section sources
- The Oracle requires Node.js 18 or newer. If you see engine-related errors, switch to a compatible Node.js version.
- If the Oracle fails to load environment variables, ensure
dotenvis installed and the.envfile exists with the required keys.
Section sources
Common symptoms include runtime errors when connecting to the chain, inability to sign transactions, or the Oracle refusing to start.
Checklist:
- Oracle:
RPC_URL,ORACLE_PRIVATE_KEY,IDENTITY_ADDRESS,REPUTATION_ADDRESS - Quickstart:
OPERATOR_PRIVATE_KEY,RPC_URL, and contract addresses - SDK integration tests:
SIGVARA_RPC_URL,SIGVARA_CHAIN_ID, and contract addresses
Section sources
If the Oracle appears to lose attestations or flags after restarts, check the state path configuration and volume mount. The Oracle README warns that only certain state can be recovered by rescanning, and attestation state may require re-submission. Before each save the file it replaces is kept as <state>.bak. If the state file cannot be read, the oracle starts from the .bak and /health reports stateSource: "backup"; with no usable backup it stops and says why instead of starting empty.
Section sources
If attestations are rejected unexpectedly, verify:
-
PAYMENT_VERIFICATIONmode -
PAYMENT_ASSETaddress - Minimum amount and confirmation settings
- Whether the settlement transaction actually transfers to the agent’s address
Section sources
If the SDK build fails:
- Ensure TypeScript and Vitest are installed via the package manager.
- Run the typecheck script to catch type errors before building.
- Confirm that the SDK’s source files compile into the expected
dist/output.
Section sources
Arc uses USDC as native gas, which differs from typical Ethereum setups. Keep these points in mind:
- Fund the deployer/operator wallet with Arc testnet USDC.
- Be aware that fee estimation may require legacy mode in some cases.
- Do not add unsupported Etherscan-style entries until Foundry supports the chain metadata.
Section sources
You now have a complete view of how to set up Sigvara locally:
- Use Foundry for Solidity contracts, scripts, and tests
- Use Node.js 18+ for the Oracle and SDK
- Configure
foundry.toml, Oracle environment variables, and SDK integration test variables - Build and test all layers: contracts, Oracle, and SDK
- Use the troubleshooting sections to resolve common platform, dependency, and configuration issues
Once the environment is verified, you can proceed to local development, testing, and, if needed, deployment to Arc testnet following the dedicated deployment and quickstart guides.
- Install Foundry and Node.js
- Clone the repository
- Fetch the Solidity dependencies (
sh scripts/fetch-deps.sh) - Build contracts
- Run contract tests
- Install Oracle dependencies and configure
.env - Run Oracle tests
- Start the Oracle locally
- Install SDK dependencies
- Build and test the SDK
- Optionally run SDK integration tests against Arc testnet with the documented environment variables
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