Thank you for your interest in contributing to Recourse! We are building an open protocol that makes AI agents financially accountable through bonded collateral, TEE-attested receipts, and automated slashing on NEAR.
We welcome contributions of all kinds: bug fixes, documentation improvements, new test cases, security hardenings, and feature enhancements.
We want contributing to Recourse to be straightforward and welcoming:
- No bureaucratic gatekeeping: You do not need prior permission or mandatory issue pre-assignment to submit a pull request. If you find a bug, a typo, a missing test, or an improvement, feel free to open a PR directly.
- Clear focus: For larger architecture changes or new protocol features, opening an issue or discussion first is encouraged so we can align on design before you write extensive code.
- Quality over ceremony: We value verified tests, clean code, and reproducible execution over paperwork.
Ensure your local development environment meets the following requirements:
- Node.js:
>= 22.0.0(Recommended:22.23.3, see.nvmrc) - pnpm:
>= 9.12.0(Project package manager:pnpm@9.12.3) - Rust:
1.95.0(specified inrust-toolchain.toml) with thewasm32-unknown-unknowntarget:rustup target add wasm32-unknown-unknown
- cargo-near: For compiling the NEAR smart contracts:
cargo install cargo-near
- Docker & Docker Compose (Optional): Required if running the full containerized demo or clean-room judge environment (especially on Windows where nearcore sandbox binaries are not natively available).
Recourse is organized as a pnpm monorepo with Rust smart contracts:
Recourse/
├── contracts/
│ ├── recourse/ # Primary NEAR smart contract (Rust) — holds bonds, vaults, and handles claims
│ └── test-token/ # Mock NEP-141 token used in integration and invariant tests
├── packages/
│ ├── sdk/ # TypeScript SDK & contract ABI client
│ ├── receipts/ # NEAR AI Cloud Intel TDX TEE receipt verification (RFC-8785 canonical JSON)
│ ├── intents/ # NEAR 1Click cross-chain bridge client
│ ├── adapters/ # Sandbox fixture replays and network adapters
│ ├── config/ # Shared configuration and environment schemas
│ └── jobs/ # Job extraction rubrics, terms, and schemas
├── services/
│ ├── worker-agent/ # AI agent runner (extracts invoices, signs TEE receipts)
│ ├── arbiter/ # LLM dispute arbiter service running published rubrics
│ ├── underwriters/ # Automated underwriting vault & sealed-bid auction market
│ ├── keeper/ # Execution keeper service with generation-fenced leases
│ └── indexer/ # Real-time event indexer and cryptographic tamper-evident audit ledger
├── apps/
│ └── web/ # Next.js 15 frontend application (agent profiles, claims, receipt visualizer)
├── demo/
│ ├── run-demo.ts # Seven end-to-end sandbox scenarios with automated solvency verification
│ ├── scenarios/ # Individual scenario runners (happy path, wrong work, appeals, etc.)
│ └── fixtures/ # Genuine recorded NEAR AI Cloud TEE receipts and mock data
├── tests/
│ └── adversarial/ # Adversarial test suite mapping to entries in THREAT_MODEL.md
└── scripts/
├── judge.ts # Comprehensive automated test runner & verification harness
└── hosted-sandbox.ts # Local sandbox network orchestrator
-
Clone the repository:
git clone https://github.com/devprashant19/Recourse.git cd Recourse -
Install JavaScript/TypeScript dependencies:
pnpm install
-
Configure environment variables (optional for sandbox):
cp .env.example .env
Note: Running
pnpm demoruns entirely on an ephemeral local NEAR sandbox and requires no API keys or.envconfiguration. -
Verify your setup with the judge script:
npm run judge
Recourse maintains high test coverage across smart contracts, services, and integration boundaries.
- Unit and protocol tests:
pnpm test:contract
- Solvency and invariant tests:
pnpm test:invariants
- Integration tests (compiles contract and tests against NEAR Workspaces):
pnpm test:integration
- Vitest service tests:
pnpm test:services
- Adversarial threat model tests:
pnpm test:adversarial
- Type checking across all packages:
pnpm typecheck
- Linting:
pnpm lint
- Run the full 7-scenario demo against a fresh local sandbox:
pnpm demo
- Run the Next.js web application:
Open http://localhost:3000 in your browser.
pnpm web
- Run Playwright end-to-end tests:
pnpm test:e2e
- Write clean, strongly-typed code (
strict: true). Avoidany; useunknownwith type guards where necessary. - Export interfaces and types from their respective packages.
- Always use RFC-8785 canonical JSON formatting (
canonicalize) when calculating hashes over structured data to guarantee cross-language consistency with Rust.
- Format code using
cargo fmt. - Ensure
cargo clippypasses without warnings. - Keep smart contract state transitions explicit and guarded by
require!assertions. - Use checked or saturating 128-bit unsigned integer arithmetic (
u128) for all financial amounts (escrow, bond, payouts, premiums). Never use floating-point numbers for token calculations.
- Maintain docstrings and documentation for public APIs and contracts.
- Document any non-trivial security assumptions or cryptographic assertions.
- Features:
feature/<short-description>orfeat/<short-description> - Bug fixes:
fix/<short-description> - Documentation:
docs/<short-description> - Tests/Refactoring:
refactor/<short-description>ortest/<short-description>
We encourage conventional commit messages:
feat: add retry logic to keeper coordinatorfix: resolve race condition in outbox dispatcherdocs: update setup prerequisites in CONTRIBUTING.mdtest: add invariant test for multi-vault slashing
Before submitting your PR, ensure:
pnpm typecheckandpnpm lintpass cleanly.- Relevant unit and integration tests pass (
pnpm test:contract,pnpm test:services). - You have not committed any private keys,
.envfiles with secrets, or temporary build artifacts. - The PR description clearly explains what changed, why, and how it was tested.
When opening an issue or pull request, GitHub will prompt you with our standardized templates:
- Bug Reports: Detailed reproduction steps, environment details, and relevant logs.
- Feature Requests: Proposed solutions, target components, and alternatives considered.
- Documentation Improvements: Specific guide/file needing clarification or enhancement.
- Pull Requests: A structured checklist linking related issues and confirming local test runs.
Recourse runs an automated, lightweight PR labeler (.github/workflows/labeler.yml). When you open or update a PR, it automatically inspects modified file paths and applies area labels (contracts, frontend, backend, documentation, ci, dependencies) to help maintainers review changes efficiently.
Recourse uses GitHub Dependabot to keep dependencies healthy and secure:
- Automated Monitoring: Dependabot monitors npm/pnpm packages, Cargo crates, and GitHub Actions weekly on Mondays.
- Grouped Pull Requests: Compatible patch and minor updates are automatically grouped to minimize PR noise, while major version upgrades remain isolated for targeted review.
- Security Updates: Vulnerability-related dependency alerts are prioritized and should be reviewed promptly.
- Maintainer Review: Automated merging is disabled. Repository maintainers review, test, and merge all dependency updates manually.
- Lockfile Hygiene: Contributors should avoid manually modifying
pnpm-lock.yamlorCargo.lock. Always update dependencies using the standard package manager commands (pnpm installorcargo update).
Automated checks run on all pull requests and pushes to main via GitHub Actions:
- Jobs & What They Validate:
- Contract (
contract): Formatting (cargo fmt), linting (cargo clippy), unit tests (cargo test --lib), invariant tests (cargo test --test invariants), and wasm compilation. - TypeScript (
typescript): Frozen-lockfile install (pnpm install --frozen-lockfile), type checking (pnpm typecheck), linting (pnpm lint), and service unit tests (pnpm test:services). - Judge (
judge): Keyless sandbox headline verification (npm run judge) running all 7 end-to-end scenarios, solvency checks, adversarial threat defenses, and README parity. Runs aftercontractandtypescriptsucceed. - Secrets Scan (
secrets): History and working tree scan (gitleaks) to prevent credential leakage.
- Contract (
- Excluded from Routine PR CI:
- Live Testnet Execution (
demo:testnet): Requires funded NEAR testnet accounts and network keys. - Mainnet Verification (
mainnet:verify): Awaiting a human-recorded mainnet run. - Browser E2E Tests (
pnpm test:e2e): Requires containerized web services and browser binaries; run locally or during release qualification.
- Live Testnet Execution (
- Running Locally: You can reproduce CI checks locally before opening a PR:
pnpm install --frozen-lockfile pnpm typecheck && pnpm lint && pnpm test:services npm run judge
- Advisory Feedback & Maintainer Discretion: CI checks provide transparent feedback and help catch unintended regressions. They are not configured as hard blocking gates or mandatory status checks. Repository maintainers retain full discretion to review and merge pull requests.
- Reporting CI Issues: If you observe an unexpected CI failure on an advisory check, feel free to comment on your pull request or open an issue using the Bug Report template.
Recourse employs automated security workflows to assist maintainers in maintaining repository security:
- Security Checks:
- Secret Detection: Gitleaks scans commit history in CI to prevent accidental secret leakage.
- Static Analysis (CodeQL): Automated CodeQL scans analyze TypeScript, JavaScript, and Rust for common security vulnerabilities weekly and on pull requests.
- Dependency Review: Evaluates newly added or updated dependencies against known advisory databases on pull requests.
- Advisory Status: All automated security checks are purely advisory to guide review. They are not configured as hard merge gates.
- Handling Dependency Vulnerabilities: When a vulnerability is flagged in a dependency, maintainers triage and update to a secure compatible release via Dependabot. Contributors encountering dependency warnings should report them via an issue.
- Reporting Vulnerabilities: Never report security vulnerabilities or exposed credentials through public GitHub issues or pull requests. Please report privately via GitHub Security Advisories as detailed in SECURITY.md.