MaintPay

Review-gated contractor payouts on NEAR testnet: one stored attempt, one idempotency key, and a final chain receipt before “Paid.”

Live demo: https://maintpay.vercel.app

Demo video: (coming)

Tracks: realworld (contractor/maintainer payouts) and security (scoped wallets, transient credentials, guarded sending and receipt verification).

Problem

Small maintenance jobs end with two disconnected questions: “was this exact change accepted?” and “was the contributor paid?” A merge, wallet balance or provider success label cannot answer both. Retrying an uncertain payment with a new key can also pay twice.

MaintPay connects a written agreement, human acceptance of a GitHub commit, and a verifiable native NEAR transfer. It is a revocable reservation, not escrow: the client can move funds outside the app; acceptance does not lock a balance.

What it does

1. Client saves the repository, task, criteria, contributor/approver emails, recipient, amount, expiry and dedicated 64-hex wallet.
2. Client reads the balance and records a successful inbound native NEAR deposit.
3. Contributor links a public non-draft PR in the agreed repository. Closed-unmerged PRs are refused; merged PRs remain eligible.
4. Designated approver accepts or rejects the exact linked commit. A merge alone is not acceptance.
5. Client prepares an immutable attempt. Claiming rechecks GitHub evidence and the current balance; changed/missing evidence holds the job.
6. Client pastes an OutLayer API credential for Send payment. The server verifies its wallet and the stored body hash, then submits the stored body/key.
7. Success triggers final NEAR receipt verification. Only a matching successful transaction confirms the job and displays Paid with an explorer link.

The client can cancel before an attempt exists. Other participants see read-only payment status. /sample is explicitly illustrative and never sends money.

Why NEAR / OutLayer

• NEAR: exact integer yoctoNEAR amounts (24 decimals), with testnet RPC EXPERIMENTAL_tx_status and wait_until: "FINAL". Confirmation checks final execution, hash, signer, receiver, one native Transfer action and exact amount—not just a provider label.
• OutLayer: documented TEE custody keeps the private signing key outside the browser and MaintPay server. A separate wk_… spending credential is supplied per action. MaintPay does not independently verify TEE attestation.
• Idempotent transfer: OutLayer deduplicates by (wallet, X-Idempotency-Key). Recovery re-sends the stored request/key; a duplicate response points to the original request and is not proof of payment. This is native NEAR transfer, not NEAR Intents or a custom contract.

References: custody API, idempotency/status semantics.

Safety guarantees: mechanisms and boundaries

Boundary	Concrete mechanism
Authorized actors	Server auth middleware, same-site checks, verified-email lookup and per-job email roles. Only the client reads balances, claims, sends, refreshes or confirms. The approver cannot be the client or contributor; contributors cannot approve themselves.
Fixed acceptance	SHA-256 of canonical terms includes expiry and wallet. Decisions bind the terms hash/head SHA. One guarded SQL CTE updates the job and inserts the decision.
No PR/deposit resurrection	Pure lifecycle/expiry guards plus SQL status/version predicates reject cancelled/non-pre-review jobs, decisions and attempts.
Wallet and deposit scope	Partial unique indexes prevent active wallet reuse and duplicate deposit transactions. Wallet reuse is allowed after cancellation, confirmation or rejection. There is no on-chain wallet lock.
No stored API credential	Password input clears on action. wk_… is used in request memory, not saved to the database, browser storage, events or app logs. The private key stays with OutLayer. The registration CLI intentionally prints the API credential for its owner to save securely.
Wrong-wallet refusal	/wallet/v1/address?chain=near must equal the agreed wallet before sending or status lookup.
One attempt; safe recovery	Unique attempt per job, stored body/hash/key, versioned claimed → sending SQL transition and integrity check. Concurrent initial sends have one SQL winner. Recovery uses identical bytes/key. At-most-once provider execution depends on OutLayer's deduplication contract and preserving the recovery database.
Cancel versus claim	Versioned job updates and the unique attempt row prevent both winning the same reservation. Cancellation is blocked once an attempt exists.
Explicit uncertainty	Timeouts stay sending; duplicates become read_original; processing, policy approval, review, wallet-busy and unknown statuses block new sends. Failure stays failed_unproven, even when the provider reports never-executed/submitted.
Receipt-verified Paid	Provider success is not Paid. Matching FINAL receipt checks precede an atomic, versioned SQL update confirming both attempt and job.
Spending limits	Recommended external OutLayer policy, not a MaintPay policy engine. The owner configures a recipient whitelist, cap and approvals. MaintPay submits the agreed recipient/amount and surfaces blocks; it does not install or audit policy.

Quickstart for judges

Try the hosted demo

Open maintpay.vercel.app/login. The three demo accounts in the table below are seeded there with the documented default password. Use separate browser profiles for the client, contributor and approver, then follow the payout walkthrough below. Bring your own dedicated, funded OutLayer testnet wallet; no spending credential is supplied with the demo.

This is the beginning of the README. Read the rest at the original. Read the full README ↗