Skip to content

Code Quality and Contribution Guidelines

Jump to bottom
RunTimeAdmin edited this page Nov 3, 2026 · 25 revisions

Code Quality & Contribution Guidelines

**Referenced Files in This Document** - [README.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/README.md) - [foundry.toml](https://github.com/RunTimeAdmin/Sigvara/blob/main/foundry.toml) - [.github/workflows/ci.yml](https://github.com/RunTimeAdmin/Sigvara/blob/main/.github/workflows/ci.yml) - [.github/dependabot.yml](https://github.com/RunTimeAdmin/Sigvara/blob/main/.github/dependabot.yml) - [SECURITY.md](https://github.com/RunTimeAdmin/Sigvara/blob/main/SECURITY.md) - [oracle/package.json](https://github.com/RunTimeAdmin/Sigvara/blob/main/oracle/package.json) - [packages/sdk/package.json](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/package.json) - [packages/sdk/tsconfig.json](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/tsconfig.json) - [packages/sdk/vitest.config.ts](https://github.com/RunTimeAdmin/Sigvara/blob/main/packages/sdk/vitest.config.ts) - [src/SigvaraIdentity.sol](https://github.com/RunTimeAdmin/Sigvara/blob/main/src/SigvaraIdentity.sol) - [.gitattributes](https://github.com/RunTimeAdmin/Sigvara/blob/main/.gitattributes)

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 defines the code quality standards, contribution workflow, review and merge criteria, documentation requirements, security practices, branching strategy, versioning approach, community guidelines, and maintainer responsibilities for Sigvara. It applies to all layers: Solidity contracts, the TypeScript SDK, and the Node.js oracle and scripts.

Sigvara is a computed-reputation and staked-slashing layer on top of ERC-8004 identity. The repository contains upgradeable Solidity contracts, an oracle service, a TypeScript protocol SDK, site assets, deployment scripts, tests, and operational documentation. Contributions should preserve the project’s focus on cryptographic trust, slashable accountability, and clear, auditable engineering.

Project Structure

The repository is organized by layer and purpose:

  • src/ — Upgradeable Solidity contracts (UUPS proxies).
  • test/ — Foundry unit, fuzz, invariant, E2E, and fork tests.
  • script/ — Foundry deployment and upgrade scripts.
  • scripts/: Repository checks and tools, including fetch-deps.sh (Solidity dependencies) and the checks CI runs.
  • examples/: Worked examples, the MCP-gated tool and a gated marketplace contract.
  • oracle/ — Node.js reputation oracle with tests.
  • packages/sdk/ — TypeScript protocol SDK with Vitest tests.
  • site/: Static website and assets, including the explorer, score epochs and simulation pages.
  • sim/: The labelled testnet simulation described in docs/simulation.md.
  • docs/ — Protocol, architecture, token, brand, and security documentation.
  • .github/workflows/ — CI pipeline configuration.
  • deployments/ — On-chain proxy implementation records.
  • Root-level tooling: foundry.toml, Docker Compose files, and utility scripts.
graph TB
A["Repository Root"] --> B["Solidity Contracts<br/>src/"]
A --> C["Foundry Tests<br/>test/"]
A --> D["Deployment Scripts<br/>script/"]
A --> E["Oracle Service<br/>oracle/"]
A --> F["TypeScript SDK<br/>packages/sdk/"]
A --> G["Static Site<br/>site/"]
A --> H["Documentation<br/>docs/"]
A --> I["CI Pipeline<br/>.github/workflows/"]
A --> J["Configuration<br/>foundry.toml"]
Loading

Diagram sources

Section sources

Core Components

This section summarizes the core components relevant to code quality and contributions.

  • Solidity contracts:
    • Upgradeable UUPS proxies controlled by roles.
    • Identity, reputation, staking, oracle bond, and fee contracts.
    • Extensive Foundry testing including fuzz and invariants.
  • Oracle:
    • Node.js service that reads attestations and writes scores.
    • Uses native Node test runner.
  • TypeScript SDK:
    • Public npm package for agent identity, reputation, and authentication flows.
    • Built with TypeScript strict mode and tested with Vitest.
  • Documentation and site:
    • Contract-driven documentation checks run in CI.
    • Response headers and evidence fixtures are validated.
    • The authorisation matrix is checked against the contracts' modifiers, and the deployed testnet bytecode against the build.

Section sources

Architecture Overview

The system integrates ERC-8004 identity, off-chain reputation computation, and on-chain slashing enforcement. Contributors should understand how changes propagate across contracts, the oracle, the SDK, and the documentation.

graph TB
subgraph "Signal Sources"
CA["CounterAudit Attestations"]
WD["Watchdog Scanners"]
end
subgraph "ERC-8004 Layer"
EID["Identity Registry"]
EREP["Reputation Registry"]
end
subgraph "Sigvara Layer"
OR["Reputation Oracle"]
REP["SigvaraReputation"]
ST["SigvaraStaking"]
ID["SigvaraIdentity"]
end
subgraph "Consumers"
CONS["SDK and On-Chain Consumers"]
end
CA --> OR
WD --> OR
EID --> OR
EREP --> OR
OR --> REP
ST --> REP
ID --> ST
REP --> CONS
Loading

Diagram sources

Detailed Component Analysis

Solidity Contracts

Code quality expectations:

  • Use Foundry as the build, test, and fuzz framework.
  • Keep dependencies pinned through remappings and CI dependency fetching.
  • Maintain upgrade safety via UUPS and careful storage layout.
  • Enforce access control with explicit roles.
  • Write comprehensive tests: unit, fuzz, invariant, and E2E.

Key configuration:

  • Solidity compiler version and optimizer settings are defined centrally.
  • Fuzz runs are tuned per profile; CI uses higher intensity.
  • RPC endpoints for Arc testnet and mainnet are configured.
flowchart TD
Start(["Solidity Change"]) --> Build["forge build"]
Build --> Test["forge test"]
Test --> Fuzz{"Fuzz Profile"}
Fuzz --> |default| DefaultRuns["Default fuzz runs"]
Fuzz --> |ci| CiRuns["CI fuzz runs"]
DefaultRuns --> Pass{"Tests pass?"}
CiRuns --> Pass
Pass --> |No| Fail["Fix failures before PR"]
Pass --> |Yes| Slither["Slither static analysis"]
Slither --> High{"High findings?"}
High --> |Yes| Block["Block merge until resolved"]
High --> |No| Review["Code review"]
Review --> Merge["Merge criteria met?"]
Merge --> |Yes| Done["Approved and merged"]
Merge --> |No| Iterate["Address feedback"]
Loading

Diagram sources

Section sources

TypeScript SDK

Code quality expectations:

  • Strict TypeScript compilation.
  • CommonJS output with declarations and source maps.
  • Vitest-based tests with Node environment.
  • Package metadata includes public publish configuration and repository link.
classDiagram
class TSConfig {
+target ES2020
+module CommonJS
+strict true
+declaration true
+sourceMap true
+rootDir src
}
class VitestConfig {
+globals true
+environment node
}
class PackageJSON {
+name @sigvara/protocol-sdk
+version 1.0.0-alpha.15
+scripts build,test,typecheck
+dependencies ethers,tweetnacl
+devDependencies typescript,vitest
}
TSConfig --> PackageJSON : "builds"
VitestConfig --> PackageJSON : "tests"
Loading

Diagram sources

Section sources

Oracle Service

Code quality expectations:

  • Node.js service using native test runner.
  • Tests validate badge rendering, scoring logic, HTTP helpers, merkle encoding, payments, metrics, jobs, policy watchers, and store behavior.
  • Dependency management via npm and pinned engines.
sequenceDiagram
participant Dev as "Developer"
participant NPM as "npm"
participant Node as "Node Test Runner"
participant Oracle as "Oracle Modules"
Dev->>NPM : npm ci
NPM-->>Dev : Dependencies installed
Dev->>Node : node --test
Node->>Oracle : Run test suite
Oracle-->>Node : Assertions pass/fail
Node-->>Dev : Test results
Loading

Diagram sources

Section sources

Documentation and Site Integrity

Documentation must stay synchronized with contracts and site configuration. CI enforces:

  • Contract-to-docs/site consistency in scripts/check-docs.mjs: selectors, status labels, deployed addresses, factor caps and launch amounts. A selector name the script cannot resolve against src/ is a failure, not a skip.
  • Single source of truth for response headers.
  • Evidence fixture parity between oracle and contract tests.
  • A row in docs/authorisation-matrix.md for every state-changing function, whose caller and pause-guard columns scripts/check-authz.mjs checks against the modifiers.
flowchart TD
Change["Contract or Site Change"] --> DocsCheck["Check docs match contracts"]
Change --> HeadersCheck["Validate single header source"]
Change --> FixtureCheck["Regenerate and compare evidence fixture"]
DocsCheck --> CI{"All checks pass?"}
HeadersCheck --> CI
FixtureCheck --> CI
CI --> |No| Block["Fail CI"]
CI --> |Yes| Proceed["Allow review and merge"]
Loading

Diagram sources

Section sources

Dependency Analysis

External dependencies are managed at multiple levels:

  • Solidity dependencies are fetched by CI with scripts/fetch-deps.sh and pinned to specific commits (a tag can be moved and a branch moves on its own, a commit cannot). lib/ is gitignored and there are no submodules.
  • Node packages are managed per workspace with Dependabot updates.
  • GitHub Actions are updated monthly.
graph TB
A["CI Workflow"] --> B["OpenZeppelin Contracts v5.6.1"]
A --> C["OpenZeppelin Upgradeable v5.6.1"]
A --> D["Forge-Std"]
E["Dependabot"] --> F["Oracle npm deps"]
E --> G["SDK npm deps"]
E --> H["GitHub Actions"]
Loading

Diagram sources

Section sources

Performance Considerations

  • Solidity:
    • Optimizer enabled with configured runs.
    • Fuzz profiles balance coverage and runtime; CI uses more iterations.
  • Oracle:
    • Node.js performance depends on RPC calls and event processing; ensure efficient log filtering and caching where appropriate.
  • SDK:
    • Avoid unnecessary network calls; reuse providers and cache read-only data when safe.
  • Site:
    • Minified vendor assets are shipped verbatim; avoid modifying them unintentionally.

Troubleshooting Guide

Common issues and resolutions:

  • Local vs CI differences:
    • Ensure local Foundry setup matches CI profiles and dependency fetch steps.
  • Line endings:
    • Windows checkouts can introduce CRLF; .gitattributes enforces LF for text files except PowerShell scripts.
  • Documentation drift:
    • If docs or site checks fail, regenerate fixtures and verify selectors/status enums against contracts.
  • Security reports:
    • Report vulnerabilities privately; do not open public issues for unpatched vulnerabilities.

Section sources

Conclusion

Sigvara’s code quality and contribution model emphasizes cryptographic correctness, slashable accountability, and rigorous testing across Solidity, TypeScript, and Node.js layers. CI enforces builds, tests, fuzzing, static analysis, and documentation integrity. Contributors should follow the established workflows, maintain alignment between code and documentation, and treat security as a first-class concern.

Appendices

Pull Request Workflow and Review Process

  • Create a feature branch from main.
  • Implement changes with tests and update documentation if required.
  • Run local checks:
    • Solidity: sh scripts/fetch-deps.sh once, then forge build and forge test.
    • Oracle: cd oracle && node --test.
    • SDK: cd packages/sdk && npm run build && npm test.
  • Open a pull request.
  • CI will:
    • Build contracts and run fuzz tests under CI profile.
    • Build and test SDK.
    • Test oracle.
    • Validate docs/site alignment, response headers, and evidence fixtures.
    • Run Slither and block merges on high findings.
    • Run with read-only repository permissions. A newer push to a pull request replaces the run still going for it, while every push to main keeps its own run, so a burst of merges does not cancel the pending ones.
  • Review criteria:
    • All CI jobs pass.
    • No unresolved high-severity static analysis findings.
    • Tests cover new logic and edge cases.
    • Documentation and site remain consistent with contracts.
    • Security-sensitive changes include threat modeling and audit considerations.
  • Merge:
    • Requires approval from maintainers after addressing feedback.

Section sources

Branching Strategy and Version Management

  • Branching:
    • main is the active development target.
    • Feature branches derive from main; release branches may be used for coordinated deployments.
  • Versioning:
    • SDK uses semantic versioning with pre-release tags (e.g., alpha). npm has 1.0.0-alpha.15 as its latest release, and changes made after it are recorded under an Unreleased heading in packages/sdk/CHANGELOG.md until the next publish.
    • Oracle and other Node packages use npm versioning.
    • Contract upgrades are tracked via UUPS proxies and deployment manifests.
  • Releases:
    • Coordinate contract upgrades, oracle releases, and SDK publishes together.
    • Update deployment manifests and documentation before release.

Section sources

Documentation Requirements

  • Inline comments:
    • Solidity: Use NatSpec for functions, parameters, return values, and important invariants.
    • TypeScript: Provide JSDoc for public APIs and complex logic.
    • Oracle: Comment non-obvious parsing, aggregation, and Merkle logic.
  • API documentation:
    • Keep README sections aligned with current contract interfaces and SDK methods.
    • Include usage examples and integration notes.
  • Changelog maintenance:
    • Track breaking changes, deprecations, and security fixes.
    • For SDK, maintain CHANGELOG.md referenced in package metadata.
  • Contract-to-docs validation:
    • Ensure selectors, status enums, and published addresses match reality.

Section sources

Security Considerations in Code Reviews

  • Vulnerability scanning:
    • Slither runs in CI; high findings block merges.
    • Accepted findings are documented and tracked.
  • Audit preparation:
    • Maintain clear role boundaries and upgrade paths.
    • Preserve evidence roots and payment verification logic.
    • Keep deployment manifests and implementation history accurate.
  • Private reporting:
    • Use the designated security contact for vulnerability reports.
    • Do not disclose unpatched vulnerabilities publicly.

Section sources

Community Guidelines and Maintainer Responsibilities

  • Community:
    • Engage respectfully and transparently.
    • Follow the repository’s scope and licensing.
  • Communication channels:
    • Use issues for bugs and feature requests.
    • Use private email for security disclosures.
  • Maintainers:
    • Enforce CI gates and review standards.
    • Coordinate audits, releases, and incident response.
    • Keep documentation current and aligned with code.

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