wikideck/docs/market-host-configuration.md

# Optional market hosting and host fee wallet

These are **server runtime** environment variables, forwarded by the single-node, three-node, gated mainnet and persistent custody Compose files. They do not enable real payments.

| Variable | Default | Effect |
| --- | --- | --- |
| `WIKIDECK_MARKET_ENABLED` | `1` | `0` removes public listings and rejects new listings, bids, purchases, custody reservations and fictitious funding. Node validation, mining, peer sync and free transfers/trades continue unchanged. |
| `WIKIDECK_MARKET_TRADING_ENABLED` | `1` | `0` pauses new trading/funding but keeps public listings browsable. Useful for maintenance/read-only operation. |
| `WIKIDECK_MARKET_HOST_FEE_ADDRESS` | Fixed project author XMR address | Public Monero recipient for the **hosting commission**, independently of the fixed additional author commission. |
| `WIKIDECK_MARKET_FEE_BPS` | `250` | Existing hosting commission rate, in basis points; range 0–5000. |
| `WIKIDECK_CUSTODY_MODE` | `off` in the application | Existing custody-service control: `off` or testnet-only `sandbox`. The dedicated custody Compose stack deliberately enables `sandbox` and provisions PostgreSQL. |

Booleans accept exactly `0`/`1`; malformed or empty flags fail startup. The fee address must be a checksum-valid **mainnet Monero standard address or subaddress** under the current XMR policy; integrated addresses, URLs, other networks and blank values are rejected. It is not a private key, buyer deposit address, or proof of ownership. No RPC/wallet access is needed to validate it.

Default wallet:

44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv

Set the variables in the shell/Compose environment or a local Compose environment file, then recreate the intended app container. They are not browser build variables. Merely restarting a container does not replace its environment. Existing Compose defaults preserve current hosting behavior. In the three-node configuration shared values apply to all nodes; per-service environment overrides allow different hosts/fees. Do not point independent markets at a shared financial schema.

## Existing obligations remain available

Disabling market hosting is **not a funds freeze or deletion**. Signed private activity, existing-order mock payment/delivery/refund, listing retirement/cancellation, custody cancellation and withdrawal-hold requests remain available under their existing checks. Reconciliation continues and data is retained. PostgreSQL remains required if that node already has PostgreSQL-backed liabilities; the switch is not a shortcut to abandoning custody responsibilities. Existing valid command receipts remain replayable without creating another mutation.

A peer that never wants custody can leave `WIKIDECK_CUSTODY_MODE=off` and use the ordinary single/three-node stack with `WIKIDECK_MARKET_ENABLED=0`; it does not need the dedicated PostgreSQL stack. Do not turn custody off merely to hide pre-existing liabilities; first resolve them under a reviewed shutdown procedure. The marketplace UI retains an activity/resolution surface and displays the disabled/paused policy rather than hiding recovery controls.

## Fee recipient and signature compatibility

New native-XMR listings and custody listings snapshot the configured host fee address. Buyer checkout/reservation must authorize that same recipient. Both UIs show it during review and include it in signed terms. Recipient tampering invalidates the signature, and an unsigned/omitted recipient is accepted **only as the historical default author address**, never as authorization for an arbitrary configured wallet.

Existing signature bytes remain valid: omission retains the original message; explicitly supplied recipients add a domain-tagged fee tuple. Old USD/native-XMR records are not rewritten. Changing the environment changes **new listings**, not existing listings/orders or accumulated revenue. New checkout against an old listing follows its original recipient. For a new recipient, cancel/relist with fresh seller authorization. Hosting rate and the fixed 1% author policy remain separate; defaulting both recipients to the same wallet does not merge the rates.

The custody SQLite fixture records newly settled simulated host revenue under its snapshotted recipient. PostgreSQL production settlement/host withdrawals are still unimplemented: configuring an address does not create automatic transfers. Historical unallocated host revenue remains historical; it is not silently reassigned. The offline sale-lock candidate now preserves the hosting recipient in a tagged signed-terms extension. A [disposable PostgreSQL accounting rehearsal](custody-sale-rehearsal.md) verifies that the signed snapshot receives simulated revenue even after current host policy changes; this is not active-chain delivery or a live host withdrawal service.

Validation: current TypeScript/Vite build, 172 offline regressions and 31 PostgreSQL integration tests passed. Tests cover strict flag/address validation, paused/disabled behavior, continuing existing-order delivery, preserved balances/cancellations, signed-recipient tampering and recipient snapshots across config changes, including the isolated accounting rehearsal. Real XMR remains disabled.