Spoolis docs

Quickstart

Name: Spoolis
Brand: Spoolis

Produce and verify a signed demo Outcome Receipt for 100 records, with 98 accepted, 2 rejected, and $98.00 earned.

Sandbox limits

Sessions are short-lived and have compile, Spool, verify, input-size, and record limits. Always inspect the stable code and status envelope, including on HTTP 200. If a session expires or reaches a limit, mint a fresh one with step 1 and repeat the flow.

1. Mint a sandbox session

Run one request and keep the returned token.

terminal

curl -sS -X POST https://spoolis.com/api/sandbox/session > session.json

Expected checkpoint: session.json contains token, expires_at, and limits.
Keep: token.

2. Compile the agreement

Compile exact economics and two Live deterministic checks. See the single method-status table. Schema acceptance does not mean an executor is live.

terminal

TOKEN=$(node -p 'require("./session.json").token') && curl -sS https://spoolis.com/api/sandbox/compile -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"source":"A buyer pays for 100 enrichment records at $1.00 per accepted record, total $100.00. Exactly 100 records are required. Every record must include id and status.","economics":{"unitization":{"total_units":100,"unit_amount_cents":100}},"conditions":[{"description":"Exactly 100 records","required":true,"verification_method":"deterministic","deterministic_check":{"checker":"row_count","expected":100}},{"description":"Each record must include id and status","required":true,"verification_method":"deterministic","deterministic_check":{"checker":"completeness","required_fields":["id","status"]}}]}' > compile.json

Expected checkpoint: status is compiled and spool.environment is demo.
Keep: the Spool ID and both condition IDs.

3. Accept the demo Spool

Model acceptance in the sandbox.

terminal

TOKEN=$(node -p 'require("./session.json").token') && SPOOL_ID=$(node -p 'require("./compile.json").spool.id') && curl -sS -X POST "https://spoolis.com/api/sandbox/spools/$SPOOL_ID/accept" -H "Authorization: Bearer $TOKEN" > accept.json

Expected checkpoint: status is completed.
Keep: the same Spool ID.

4. Submit row-count evidence

Send 100 complete rows to the row-count condition.

terminal

TOKEN=$(node -p 'require("./session.json").token') && SPOOL_ID=$(node -p 'require("./compile.json").spool.id') && BODY=$(node -e 'const x=require("./compile.json");const condition_id=x.spool.conditions.find(c=>c.deterministic_check?.checker==="row_count").id;const rows=Array.from({length:100},(_,i)=>({id:"record-"+(i+1),status:"accepted"}));process.stdout.write(JSON.stringify({condition_id,type:"dataset",source:"100 enrichment records",metadata:{rows}}))') && curl -sS -X POST "https://spoolis.com/api/sandbox/spools/$SPOOL_ID/evidence" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "$BODY" > count-evidence.json

Expected checkpoint: status is completed.
Keep: count-evidence.json for troubleshooting.

5. Submit completeness evidence

Send 98 complete rows and 2 rows missing status.

terminal

TOKEN=$(node -p 'require("./session.json").token') && SPOOL_ID=$(node -p 'require("./compile.json").spool.id') && BODY=$(node -e 'const x=require("./compile.json");const condition_id=x.spool.conditions.find(c=>c.deterministic_check?.checker==="completeness").id;const rows=Array.from({length:100},(_,i)=>i<98?{id:"record-"+(i+1),status:"accepted"}:{id:"record-"+(i+1)});process.stdout.write(JSON.stringify({condition_id,type:"dataset",source:"98 accepted and 2 rejected enrichment records",metadata:{rows}}))') && curl -sS -X POST "https://spoolis.com/api/sandbox/spools/$SPOOL_ID/evidence" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "$BODY" > fields-evidence.json

Expected checkpoint: status is completed.
Keep: fields-evidence.json for troubleshooting.

6. Verify the delivery

Run verification and save the signed receipt.

terminal

TOKEN=$(node -p 'require("./session.json").token') && SPOOL_ID=$(node -p 'require("./compile.json").spool.id') && curl -sS -X POST "https://spoolis.com/api/sandbox/spools/$SPOOL_ID/verify" -H "Authorization: Bearer $TOKEN" > verify.json && node -e 'const x=require("./verify.json");if(x.code||x.status==="limit_reached"||x.status==="resting")throw new Error(JSON.stringify(x));if(x.verdict!=="PARTIAL"||x.receipt.units.accepted!==98||x.receipt.units.rejected!==2||x.receipt.amounts.earned!=="98.00")throw new Error(JSON.stringify(x));require("node:fs").writeFileSync("outcome-receipt.json",JSON.stringify(x.receipt,null,2)+"
")'

Expected checkpoint: verdict PARTIAL, 98 accepted, 2 rejected, and earned 98.00.
Keep: outcome-receipt.json and its receipt ID.

7. Verify the receipt offline

Verify schema spoolis/outcome-receipt@1 with the CLI. The CLI automatically selects the demo trust set. Library callers use @spoolis/receipt-verifier with a caller-selected expected environment and its matching trust set.

terminal

npx -y @spoolis/cli verify outcome-receipt.json

Expected checkpoint: the CLI reports a valid demo receipt.
Keep: the verified receipt for the consuming system.

Spoolis determines earned value and signs the Outcome Receipt. A wallet, marketplace, payment system, or configured integration may verify and consume it, then act under its own authorization and settlement policy. Demo artifacts cannot move production funds. The optional online status call is documented in verify a receipt.