Surplus Market Operator Requirements

A Surplus operator can be a venue, an attester, a market maker, a bonded issuer, or some combination of those roles. The obligations are different.

Do not run as a bonded issuer unless you can redeem the credits you sell.

Base host

Requirement	Why
Rust operator build	Runs `surplus-operator-lite` or `surplus-operator`.
Persistent venue state	Keeps books, outbox, inventory, settlement state, and operator config.
Chain RPC	Reads contracts and submits settlement when chain mode is enabled.
Supervised process	The venue should restart without losing book/accounting state.
HTTP endpoint	Serves the market API used by the app and other clients.
Private key storage	Protects issuer, attester, and submitter keys.

Key separation matters. The operator key signs issuer/attester actions. The submitter key can be a separate gas/nonce key.

Inference backend

Bonded issuance needs real inference capacity.

Setting	Use
`SURPLUS_VLLM_MODEL`	Managed vLLM model backend.
`SURPLUS_INFERENCE_URL`	OpenAI-compatible inference endpoint.
`SURPLUS_INFERENCE_API_KEY`	Credential for that endpoint.

Router-proxy mode is useful for tests and non-bonded flows. A bonded issuer must not rely on router fallback because the credit lot must be backed by capacity the issuer runs or controls.

Settlement keys and config

Setting	Use
`SURPLUS_CHAIN_ID`	Chain ID used in EIP-712 and settlement calls.
`SURPLUS_SETTLEMENT_ADDR`	Settlement contract address.
`SURPLUS_RPC_URL`	RPC endpoint for settlement submissions.
`SURPLUS_OPERATOR_KEY`	Issuer or attester key.
`SURPLUS_SUBMITTER_KEY`	Optional separate transaction key.

Do not put these in frontend env. They are operator secrets.

Shared CLOB and attesters

For shared books, configure:

Setting	Use
`SURPLUS_CLOB_OPERATORS`	Peer operator list.
`SURPLUS_CLOB_BOOK`	Book identifier.
`SURPLUS_CLOB_THRESHOLD`	Attestation threshold.
`SURPLUS_ATTESTER_ONLY=1`	Runs a quorum member that attests but does not issue.

The CLOB path depends on operator signatures. Peers must prove their operator address by signature recovery before joining the transport.

Privacy mode

Surplus can publish and use onion endpoints through Arti, the Rust Tor implementation.

Setting	Use
`SURPLUS_ONION_URL`	Fixed onion endpoint.
`SURPLUS_ONION_FILE`	Path where Arti writes the generated onion hostname.
`PRIVACY_MODE=tor`	Route outbound operator calls through Tor.

This is Tor, not custom cryptography. The privacy goal is to avoid concentrating a seller’s redemptions on the same identifiable operator endpoint.

Operator preflight

Run the repo proof paths before claiming a venue is ready:

pnpm -r test
cargo test --workspace
cd contracts && forge test

For settlement and spend paths, the repo uses:

bash scripts/settlement-e2e.sh
bash scripts/spend-e2e.sh
bash scripts/prove-batch.sh execute

Those prove more than “the server boots.” They exercise atomic fill settlement, redemption, collateral default, attested batch settlement, spend billing, and circuit parity.

Overview Settlement and Inference