Surplus Market Settlement and Inference
Surplus only works if a bought credit can be redeemed.
The order book can be off-chain. The quote brain can be a sidecar. But the settlement and redemption guarantees have to survive operator mistakes, missing receipts, and issuer default.
Settlement model
The settlement contract clears signed fills atomically:
- debit buyer escrow
- pay seller
- mint or update a collateral-backed credit lot
- enforce redemption/default rules
- slash or penalize when configured conditions fail
The repo supports three rails in the blueprint manifest:
| Rail | Meaning |
|---|---|
router-credits | Router credit balance path. |
shielded | ShieldedCredits path. |
firm | EIP-712 signed orders settled through SurplusSettlement. |
The firm rail is the main settlement spine for signed fills.
Attested and proven batches
| Path | What it verifies |
|---|---|
settleBatchAttested | A configured attester quorum signs the batch. |
settleBatchProven | An SP1 proof verifies the delegated signature check over the batch commitment. |
The SP1 program currently proves the delegated signature check and commits to abi.encode(domainSeparator, fillsHash). Matching logic and account rules remain contract-enforced unless a future state-root rollup extends the proof.
Inference backend
Bonded credit issuance requires an inference backend the operator runs or controls.
| Backend shape | Use |
|---|---|
| Managed vLLM | Operator-controlled model service. |
| OpenAI-compatible API | External or internal API with compatible chat-completions surface. |
| Router fallback | Testing or non-bonded operation only. |
If a lot is bonded, router fallback should fail closed. A credit sold as backed capacity must be redeemable against backed capacity.
Market-making loop
The operator can use a market-making sidecar. The sidecar can run a deterministic Avellaneda-Stoikov quoter or an agentic strategy. Both pass through the same risk gate.
The risk gate is the safety boundary:
| Check | Why |
|---|---|
| quote size | Prevents oversized exposure. |
| inventory | Keeps the operator from selling beyond capacity. |
| deviation | Rejects quotes too far from reference price. |
| spread | Avoids broken or inverted markets. |
| drawdown | Pulls quotes when the session is losing too much. |
| kill switch | Stops quoting when hard limits are crossed. |
The operator places quotes only after the risk verdict allows them.
What is proven locally
The repo’s release checklist names these proof paths:
| Proof | Command |
|---|---|
| Trader path | bash scripts/settlement-e2e.sh |
| Developer spend path | bash scripts/spend-e2e.sh |
| Circuit parity | bash scripts/prove-batch.sh execute |
Those checks cover atomic fill, receipt redemption, collateral default, attested batch settlement, proven batch path, streaming and buffered spend calls, on-chain billing, and forged voucher refusal.
What is still a deployment decision
| Decision | Why it matters |
|---|---|
| 1-of-1 vs M-of-N books | Changes quorum and peer requirements. |
| Attester set | Decides who can sign settlement batches. |
| SP1 verifier and vkey | Enables or disables the proven path on that deployment. |
| Inference backend | Determines whether bonded credits can redeem. |
| Timelock/Gnosis Safe ownership | Controls owner actions such as registering books and rotating attesters. |