Sheaf documentation

Getting started

1. Create a workspace (you become its Owner) or sign in to the seeded demo organisation.
2. In Settings, confirm the asset and network. In real mode, set the treasury wallet address.
3. Open Batches → New batch, give it a name and an optional deadline.
4. Upload a CSV, fix any flagged rows, prepare routes, then hand it to an approver.

Seeded demo accounts: owner@northwind.example, finance@northwind.example, approver@northwind.example, viewer@northwind.example, password sheaf-demo-2026.

CSV format

Required columns: name, address, amount. Optional: asset, reference. Header aliases such as “Contractor name”, “Wallet address”, “Payment amount” and “Invoice” are recognised. Delimiters: comma, semicolon or tab. Limits: 5 MB, 10,000 rows.

name,address,amount,asset,reference
Ada Okafor,0x1b3f9c2a8e4d6f7a9b0c1d2e3f4a5b6c7d8e9f0a,1250.00,USDC,INV-2026-0912
Mateo Ruiz,0x9f0e1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8e,980.50,USDC,INV-2026-0913

• Amounts are decimal strings. More decimals than the asset supports is an error, never rounded.
• Mixed-case addresses must pass the EIP-55 checksum. All-lowercase addresses are accepted.
• The same wallet twice in one batch is an error on the second row (merge or remove).
• Invalid rows are kept and shown with their errors; they can be corrected or removed in place.

Batch workflow

Statuses move strictly: Draft → Validated → Routes prepared → Approved → Funded → Executing → Completed / Partially failed / Failed. A batch can be cancelled until it is funded. Uploading a CSV never executes anything.

Roles and approvals

With four-eyes enabled (default), the person who last changed the recipient set cannot approve it. Approvals record the approver, the total and a hash of the recipient set; any edit invalidates them.

Demo vs real mode

Demo uses a deterministic mock provider: no network calls, no funds. Every route, funding record, attempt and export row is flagged simulated. Scenario triggers for testers: an address ending in 00 fails permanently, ff fails once then succeeds on retry, ee gets no route, and an amount of exactly 0.13 is refunded.

Real quotes routes from Relay’s public API and requires the configured treasury wallet to sign each route step in the browser. The server never holds a private key. Real mode has been verified for quoting and status polling; no on-chain execution was performed during development. Modes never switch silently: each batch records the mode it was created in and refuses to execute under a different one.

Execution and retries

• One job per payment, claimed with a conditional update so two workers never run the same job.
• Idempotency key exec:batch:recipient:attempt; re-running a crashed job cannot send twice.
• A payment is never retried while its last attempt is pending, submitted or unknown. Unknown status after repeated failed checks stops polling and asks for manual review instead of resending.
• Retries are explicit, limited (default 3) and only offered for provider-classified transient failures.
• Optional spacing (jitter) between submissions is bounded to 30 minutes and never past the batch deadline.

Reconciliation and exports

Successful fills are marked Matched automatically with their reference and fee estimate; failures and refunds become Exceptions. Finance can override any state with a note. The CSV export contains batch, recipient, amount, network, references, statuses, attempts, fees, timestamps and a simulated column.

Known limitations

• Encryption at rest uses one server-side key (no per-organisation KMS keys); the audit table is append-only but not externally anchored.
• EVM addresses only.
• Real mode untested end-to-end on-chain; use Base Sepolia first.
• Public Relay rate limit (50 quotes/min) bounds route preparation speed without an API key.
• The in-process worker suits a single server; multi-instance deployments should trigger POST /api/worker/run from a scheduler instead.
• Same-chain, same-token routes provide no external privacy.