Storefront and listing management

Outcome. You can publish signing-address-attributed listings from your storefront's commercial inventory through authenticated requests, verify them at both the storefront and the Registry, understand which state the storefront actually owns, and pause or resume selling deliberately.

Prerequisites

• A running storefront (Seller quickstart — mock mode is enough for everything on this page).
• A Registry to publish to, with a write token if it gates writes.

What the storefront owns

The storefront owns market-facing state: listings, negotiation and deal records, and seller policy. It does not own physical inventory — it loads trusted capacity projections from each configured provisioning site, and authoritative admission happens at the site authority (POOLS capacity management). Publisher attribution is your signing-wallet address: there is no separate Registry registration step; every publish request carries an EIP-191 operation signature, and the Registry creates a publisher record from the first valid signature. Signature recovery attributes the request to that address; it does not verify a real-world person, organization, capacity, availability, or performance.

Commercial listing input

Listing input arrives through resources.csv: one row per sellable shape, referencing a projected pool_id or resource_id, with the commercial fields (min_price as a human whole-token hourly rate, token as the ERC-20 contract, max_duration_seconds) and the sellable attributes (gpu_model, gpu_count, vcpu_count, ram_gb, disk_gb, region). Never publish vm_host, authority URLs, API keys, or internal capacity-bucket IDs. The synchronized field-by-field treatment is in the seller quickstart.

Publish and verify

Warning

Publishing is an external mutation attributed to your signing address. The named public preproduction Registry in the synchronized guides was only observed as a read target; this site did not verify or grant write access. Publish only to a Registry you operate or to an endpoint and credential its operator explicitly authorized for your signing address.

docker compose -f compose/seller.yml exec seller-storefront \
  market-storefront publish --inventory /app/resources.csv

Verify from both authorities — your storefront's own listing surface and the Registry's:

curl -s http://<YOUR_PUBLIC_IP>:8001/api/v1/listings | jq '.listings[]'

curl -s "http://<REGISTRY_HOST>/listings?publisher=<YOUR_WALLET_ADDRESS>" \
  | jq '.items[]'

Re-run publish after importing resource or capacity changes so stale listings close and newly available listings reopen.

Pause and resume

A globally paused storefront rejects every new negotiation with 503 {"reason":"global"}. Global pause is durably persisted and separate from per-listing pause. Both operations use the authenticated VM storefront admin surface:

curl -X POST -H "X-Admin-Key: <admin_api_key>" \
  http://<YOUR_PUBLIC_IP>:8001/api/v1/admin/pause

curl -X POST -H "X-Admin-Key: <admin_api_key>" \
  http://<YOUR_PUBLIC_IP>:8001/api/v1/admin/resume

The first response carries "paused": true; the second carries "paused": false. Confirm the current value through GET /api/v1/system/status before accepting new buyer traffic.

Operational state

GET /api/v1/system/status reports storefront health, including resource_count (zero usually means the resource importer wrote a different SQLite database than the storefront reads — align the importer --db-path or STOREFRONT_DB_PATH) and negotiation_strategy (which catches a broken rl policy setup at startup). Stage events are visible through /api/v1/system/events and its SSE stream.

Expected output

• publish exits zero and the Registry query returns your listings under the publisher record attributed to your signing-wallet address.
• Storefront listings carry your domain's versioned offer_resource kind — for example bare_metal.v1 rows include machine_id, physical_host_id, and access_method: "ssh".

Troubleshoot

• 409 no_matching_inventory on every buy — the storefront sees no resources; check resource_count and the importer database path.
• Registry rejects the publish — the write gate is on and your [registry.auth] write token is missing or does not exactly match the configured URL.
• Fresh restarts re-register on chain — pin onchain_agent_id so an empty pin does not re-register at every start (gas cost).

Next steps

• Decouple a sellable shape from machine assignment: POOLS capacity management.
• Follow delivery after payment settlement: Fulfillment and seller delivery.
• Review the exact machine boundary: Machine-readable records.

Source and revision

Storefront authority boundaries: storefront-publication specification; settings schema: settings.toml; pause and resume routes: admin controller.