Surplus Market Dapp Integration
Surplus is live as a hosted app at https://surplus-market.pages.dev/.
Tangle Cloud should treat it as a first-party link-out until the repo publishes rich blueprintUi metadata and a *.blueprint.tangle.tools iframe host. Do not pretend it has the same iframe contract as Sandbox and Trading yet.
The Surplus repo does not ship a dedicated indexer today. The product app can read protocol state from contracts or a shared protocol indexing layer when one exists, but the venue, order book, settlement outbox, and inference redemption state live in the product/operator path.
Current metadata
The current deployed metadata is minimal:
| Field | Current value |
|---|---|
name | surplus |
category | inference-market |
code_repository | Internal Surplus repository URL |
It does not yet include the rich blueprintUi object used by Sandbox and Trading. The dapp should keep a first-party registry entry for surplus until that changes.
Routing rule
| Route | Behavior |
|---|---|
| Product app | Link to https://surplus-market.pages.dev/. |
| Protocol fallback | Preserve the raw blueprint and service-instance route. |
| Future iframe | Use only after a trusted host and iframe policy are published. |
The product app owns market UX. The protocol fallback owns chain and service inspection.
Protocol state
| State | Why the dapp needs it |
|---|---|
| Blueprint creation and source updates | Find the Surplus operator artifact and metadata. |
| Operator registration | Discover venues, issuers, and attesters. |
| Service requests and instances | Show which operators are serving a market instance. |
| Jobs | Show list_instrument, status, and workflow_tick activity. |
| Endpoint metadata | Route app checks and operator inspection. |
| Heartbeats | Distinguish dead venues from quiet books. |
Product state that is not protocol state
The app needs live product checks for:
- order book depth
- reference price
- operator inventory
- RFQ response
- settlement outbox
- fill settlement
- credit redemption
- attester quorum
- inference backend health
Protocol state can show that a job happened. It cannot prove that a credit lot was redeemed or that a model request was served honestly. Use settlement receipts, spend vouchers, attester signatures, SP1 proofs, or operator API responses for those claims.
User-facing states
| State | Meaning |
|---|---|
| No venue | No operator endpoint is available for the selected market. |
| Venue unreachable | The endpoint is registered, but the app cannot call it. |
| Quote rejected | The risk gate blocked the sidecar quote. |
| Fill pending settlement | The order matched, but the fill is still in the outbox. |
| Credit redeemable | A lot exists and can be spent against a live backend. |
| Credit defaulted | Redemption failed and the settlement/default path must resolve it. |
Those states are the product. Hide them and users cannot reason about the market.