Dev Updates

Buyers paying USDC from the order page could remain stuck in awaiting payment even after a successful on-chain transfer, because matching logic treated only the custody wallet owner as the destination while tokens actually credit that wallet’s USDC balance account. The payment panel now explains that confirmation follows backend processing (not the moment an explorer shows finality), shows the site hostname and custody vault on a block explorer before you pay, and blocks the flow if the mint does not match this deployment’s expected USDC. Local smoke guidance states that observer and reconcile jobs must keep running for orders to advance during development.

Production can now ingest on-chain USDC vault transfers into the same payment-event path reconciliation already trusts. A scheduled one-shot worker discovers recent inbounds via Solscan-style APIs, then reads each transaction on Solana RPC to recover the Solana Pay reference account wallets attach, matches it to pending intents, and records a raw transfer observation—without changing how orders move to paid. Operators gain a dedicated Procfile process, a small cursor table so reruns do not thrash the same signatures, and configuration for source mode (hybrid, RPC-only, or Solscan-only discovery). Reconcile stays DB-only; a narrow fix removes an unnecessary RPC requirement from that worker. This is backend and ops wiring only; buyer UI polling is unchanged.

Operators now have a closed gate for how payment intent reference keys line up with the read-only account wallets attach on vault transfers, without changing runtime code. A deterministic cross-runtime check confirms the same public key the buyer wallet shows is what the backend can expect when matching confirmed payments. The write-up chooses PASS B: use third-party explorer APIs for vault transfer discovery, but read the reference account from chain RPC transaction payloads because vendor transfer feeds do not surface instruction accounts needed for that field. Documentation and verification JSON only—no observer worker ships in this commit.

The earlier payment-observer preflight assumed raw Solana RPC as the first chain-read path. A focused delta pass checks whether Solscan Pro API can serve production observation instead: filtered vault transfer discovery, standard pagination, and parsed transaction detail for the risky reference-key step. The write-up maps Solscan account-transfer and transaction-detail endpoints to the fields `record_observed_payment` already needs, calls out Solscan’s mainnet-only stance so dev and staging still need an RPC fallback, and recommends a very small source adapter so indexer response shapes never leak into reconciliation. This remains documentation and planning only—no observer code ships yet.

Buyer-facing payment polling can only reflect what the backend already knows. The new operator preflight maps the full intended chain from Solana Pay intent through persisted payment events, reconciliation, and order state transitions, and names the single missing production rail: something must observe finalized vault transfers and record them as transfer events before the existing reconcile worker can mark intents confirmed. The document recommends starting with a narrow Solana RPC polling worker against the marketplace vault, documents the exact match fields already enforced in reconciliation (reference, recipient, mint, amount). No on-chain observer ships in this change set; this is planning and release hygiene only.

After placing an order and sending payment, buyers had to manually refresh the page to see whether the payment was confirmed, expired, or failed. The payment block on the order detail page now polls the lightweight payment-intent endpoint automatically while the intent is pending, using a step-function backoff schedule that starts at five seconds and gradually widens to fifteen seconds. Polling pauses when the browser tab is hidden and resumes promptly when the tab becomes visible again. When the backend reports a terminal status change the parent order detail page re-fetches so the header badge, fulfillment section, and other order fields all update in place without a manual reload. The confirmed and expired states now have dedicated visual treatments instead of relying solely on the countdown timer.

The automated `generate-dev-update` script had two sharp edges: every `Docs:` commit reused a long fixed “Ascended Heroes” audit paragraph unrelated to the actual change, and any commit that mentioned the word “endpoint” (even “no new endpoint”) could emit generic “new API endpoint” bullets. The generator now reserves that audit copy for messages that explicitly mention Ascended Heroes, builds a disclosure-safe summary from the rest of generic documentation commits, and runs documentation bullets before the API template so negated endpoint language does not hijack the change list. Commits scoped as `fix(tooling):` that only touch `generate-dev-update` are no longer lumped into the unrelated “sales refresh worker” tooling narrative, so bingo-driven releases stay faithful to what actually shipped.

We added operator-facing documentation that audits how buyer order payment state is represented today and how a future polling implementation should behave without overloading the API. The preflight names the true fields (`MarketplacePaymentIntent.status` plus aligned `order.state` / `order.payment_status`), compares full order detail versus the lightweight payment-intent endpoint, and ties refresh expectations to worker-driven reconciliation rather than sub-second magic. The bingo release script was also tightened so documentation-only commits under `docs/` still generate dev updates (they were previously misclassified as internal-only and skipped), and so automated runs no longer block forever on the interactive “press Enter” review step when stdin is not a TTY—use `BINGO_NONINTERACTIVE=1` to skip the pause explicitly.

The "Open in wallet" link on the order payment page used a solana: deep-link URI that only worked on mobile devices. Desktop browsers have no registered handler for the protocol, so clicking the link did nothing. The payment block now uses the already-connected Solana wallet adapter to build a real USDC SPL token transfer transaction and pop open the Phantom approval dialog directly in the browser. If no wallet is connected, clicking "Pay with wallet" opens the wallet selection modal first, then proceeds with the transaction once connected. The raw Solana Pay URL is still available under a "Manual payment options" toggle for mobile users or anyone who wants to copy and paste the link into a wallet app.

After selecting Phantom in the wallet modal, nothing happened because the adapter library only marks the wallet as "selected" without actually opening a connection when auto-connect is off. The link flow now explicitly calls connect() once a wallet is selected and the user intended to link, which surfaces the Phantom approval popup and then the signature request as expected. The button also shows a "Connecting…" state during the handshake so the user knows the app is waiting on the extension, and the effect chain is structured so each step—select, connect, sign, verify—fires in the correct order without racing or silently dropping.

Checkout already required that the paying wallet belong to the signed-in account, but email-first members had no supported way to add that wallet without legacy paths. The app now issues a short-lived link challenge, verifies an Ed25519 signature on the exact message bytes, and stores Solana addresses in user_wallets with correct base58 casing so lookups stay honest. On the profile page you can connect Phantom (or extend adapters later), complete the signature, and see linked wallets listed. The buy sheet loads those wallets into a simple pick list and sends the exact on-chain string to order creation. Local seed data uses a real generated public key, and Alembic defaults now match the psycopg2 driver the repo already ships so migrations run cleanly against a typical developer database.

Buyer checkout already insists the paying wallet is one the signed-in account has on file, which keeps the marketplace honest about who is authorizing spend. The development buyer persona created for manual smoke signs in with email only, so that account had no linked Solana wallet and could not complete the flow even when everything else was wired—without weakening the same rule production relies on. The marketplace test-user seed now adds a single deterministic Solana wallet association for that buyer in a way that can be run repeatedly without duplicates, prints the address for operators to paste at checkout, and documents that this is strictly a local convenience until a first-class wallet-link experience ships under the current authentication approach.