relayworkslab/relayworks-recovery

What it does

RelayWorks Recovery is the recovery engine behind the RelayWorks service. It targets structured-data agent jobs such as JSON or CSV enrichment, extraction and normalization that fail partway through. Completed chunks are sealed instead of discarded; only the remaining chunks are handed to a restricted worker, and an independent verifier checks that finished rows were preserved byte-for-byte before the customer pays in USDC on Solana through x402 (project overview).

The README describes a job state machine covering expiry, failure, cancellation, retry, dispute, refund and reconciliation. Customer files stay in Postgres and an artifact store; only provider identity, feedback and the USDC payment go on-chain (recovery flow).

The repository is the server engine and Python worker; the website and console are in a separate relayworks repository. It suits teams that already run chunked data-processing agents and want resumable execution with an explicit acceptance and settlement stage, not a general-purpose job scheduler.

Recovery flow

A run follows six stages (README):

1. Package: sign in with a Solana wallet and submit a versioned package with input digests, completed and remaining chunk IDs, failure details, adapter version and acceptance checks.
2. Quote: a curated provider returns a fixed quote; the customer sets a spend ceiling and deadline.
3. Lease: one worker holds an exclusive execution lease, with chunk-level idempotency keys preventing duplicate work.
4. Resume: the restricted worker processes only the authorized remaining chunks, running no shell commands and no customer code.
5. Verify: the verifier checks schema, unit count, unique IDs and byte-level preservation of completed chunks.
6. Accept, then settle: acceptance and settlement are separate records; USDC settles through x402, the payout goes out on Solana, and outcome feedback is written to the 8004 agent registry.

Run locally

Requirements are Node 24+, Python 3.10+ and Docker (local setup):

docker compose up -d          # Postgres 16
cp .env.example .env
cd server
npm install
npm run dev                   # builds, then serves on :8787

In another terminal, start the worker after WORKER_TOKEN matches .env (worker command):

RELAYWORKS_API=http://127.0.0.1:8787 WORKER_TOKEN=<token> python worker/main.py

SETTLEMENT_MODE=fake and REPUTATION_MODE=fake keep everything off-chain. Switching to SETTLEMENT_MODE=x402 and REPUTATION_MODE=solana enables real USDC settlement and 8004 feedback; mainnet configuration rejects placeholder tokens and mismatched networks or treasury wallets (settlement modes).

npm run build also bundles the browser x402 payment helper to server/build/browser/x402-pay.js; set X402_BUNDLE_OUT to redirect it, for example into the web repo's dist/x402-pay.js.

Tests and operations

Test suites run from server/: npm test covers the memory store, worker and x402 adapters, --postgres adds a throwaway Postgres database, and --browser drives the console in headless Chrome using RELAYWORKS_WEB_DIST (default ../dist) (testing). The suites cover package rejection, single-lease execution, verifier preservation, payment refused before acceptance, replay-safe idempotency, settlement surviving restarts and database failures, simultaneous payout and refund retries, and real x402 signing.

Operational commands include npm run preflight, one-time npm run register-provider, npm run refund -- RW-1001, and reconcile-payment / reconcile-payout (operations).

Constraints

• Local development needs Docker for Postgres 16; without it you would have to provide the database yourself.
• Real settlement requires Solana wallet setup, treasury configuration and x402 mode; the fake modes are for local work only.
• The browser test suite needs a checkout of the separate web repository's dist/ folder; it cannot run from this repo alone.
• The worker is a restricted Python process, so data jobs must fit the chunked JSON/CSV model with acceptance checks rather than arbitrary code execution.
• Licensed MIT (license).

HotRepo's take

RelayWorks Recovery entered HotRepo's new-project list for TypeScript on 2026-11-05, gaining 103 stars and 11 forks in a window starting 2026-11-04 21:32 UTC and observed through 2026-11-05 06:45 UTC. That is a single early snapshot with no best all-language daily rank recorded, so it shows initial attention rather than a trend. The design choice that stands out is separating acceptance from settlement and verifying preservation of already-finished chunks — the part most resume systems skip — while keeping customer files off-chain and limiting on-chain data to payment and reputation.