Merge pull request #18 from InjectiveLabs/codex/port-trading-frontend-skill-lessons

docs: add client-side RFQ gateway guidance

Author: ckhbtc

skills/injective-rfq-integrations/README.md

@@ -10,6 +10,8 @@ add Injective RFQ taker flows:
 - user grants scoped AuthZ once through Web3Gateway fee payer
 - app sends RFQs with a short quote collection window
 - app settles through the RFQ gateway prepared autosign transaction path
+- advanced apps can move gateway-style quote collection and selection into the
+  browser when latency requires it
 - position close is the same RFQ path with `margin: "0"`
 - TP/SL uses signed RFQ conditional close intents, not orderbook reduce-only
   orders
@@ -24,15 +26,17 @@ Read these in order:
 1. [SKILL.md](./SKILL.md) - the full implementation playbook.
 2. [references/architecture.md](./references/architecture.md) - flow diagrams and state
    boundaries.
-3. [references/frontend-rfq-flow.md](./references/frontend-rfq-flow.md) - quote windows,
+3. [references/client-side-gateway.md](./references/client-side-gateway.md) -
+   moving gateway/indexer duties into a browser latency path.
+4. [references/frontend-rfq-flow.md](./references/frontend-rfq-flow.md) - quote windows,
    ACKs, gateway settlement, and manual TakerStream collection.
-4. [references/quote-probe-uptime.md](./references/quote-probe-uptime.md) - quote uptime
+5. [references/quote-probe-uptime.md](./references/quote-probe-uptime.md) - quote uptime
    probes, market discovery, fanout limits, and frontend eligibility signals.
-5. [references/authz-and-autosign.md](./references/authz-and-autosign.md) - grants,
+6. [references/authz-and-autosign.md](./references/authz-and-autosign.md) - grants,
    ephemeral keys, Web3Gateway fee-payer setup.
-6. [references/conditional-tpsl.md](./references/conditional-tpsl.md) - RFQ
+7. [references/conditional-tpsl.md](./references/conditional-tpsl.md) - RFQ
    TP/SL signed intents.
-7. [references/troubleshooting.md](./references/troubleshooting.md) - common failures.
+8. [references/troubleshooting.md](./references/troubleshooting.md) - common failures.
 
 ## Recommended Integration Path
 
@@ -47,8 +51,9 @@ Most frontend partners should use the RFQ gateway autosign flow:
 6. Broadcast via `TxGrpcApi.broadcast`.
 7. For TP/SL, sign `SignedTakerIntent` EIP-712 and submit conditional orders.
 
-Use the lower-level TakerStream sample only when you need to manually inspect
-ACKs and quotes in the browser.
+Use client-side gateway mode only when latency or custom quote selection is
+worth owning ACK mapping, quote filtering, sequence readiness, broadcast timing,
+optimistic state, and reconciliation in the browser.
 
 ## Production Lessons
 

skills/injective-rfq-integrations/SKILL.md

@@ -4,11 +4,12 @@ description: >-
   Integrate Injective RFQ taker flows into browser apps and operational quote
   monitors. Use this skill when building, reviewing, or debugging RFQ gateway
   autosign settlement, Web3Gateway AuthZ setup, manual TakerStream quote
-  collection, RFQ open/close flows, gateway prefetch, optimistic position
-  updates, conditional TP/SL intents, quote uptime probes, market-readiness
-  checks, or mainnet RFQ frontend integrations. Covers mainnet parameters,
-  canonical decimals, quote windows, signer slots, market discovery,
-  quote-hit diagnostics, and production RFQ gotchas.
+  collection, client-side gateway-style quote selection, RFQ open/close flows,
+  gateway prefetch, optimistic position updates, conditional TP/SL intents,
+  quote uptime probes, market-readiness checks, or mainnet RFQ frontend
+  integrations. Covers mainnet parameters, canonical decimals, quote windows,
+  signer slots, market discovery, quote-hit diagnostics, and production RFQ
+  gotchas.
 license: MIT
 metadata:
   author: ck
@@ -18,9 +19,9 @@ metadata:
 # Injective RFQ Integrations
 
 Use this skill when adding Injective RFQ to a frontend or when building an RFQ
-quote monitoring tool. Keep the main flow simple: prefer the RFQ gateway for
-trade settlement, and use manual TakerStream only when you need raw quote
-diagnostics.
+quote monitoring tool. Keep the main flow simple: use the RFQ gateway when you
+want managed settlement, and use client-side gateway mode only when the app is
+ready to own quote collection, selection, broadcast timing, and reconciliation.
 
 ## Mainnet Parameters
 
@@ -42,7 +43,9 @@ EVM chain ID used in EIP-712 domains, Web3Gateway signatures, and
 
 ## Choose The Path
 
-Use the gateway autosign path for production browser trading:
+Use the managed gateway autosign path for production browser trading when
+latency is acceptable and you want the backend gateway to own quote collection
+and settlement assembly:
 
 1. Connect an EVM wallet and derive the user's Injective address.
 2. Create a local ephemeral autosign key for that wallet.
@@ -54,12 +57,44 @@ Use the gateway autosign path for production browser trading:
 7. Insert both autosign and fee-payer signatures in decoded signer order.
 8. Broadcast and poll the tx for final reconciliation.
 
-Use manual TakerStream only for diagnostics, special routing, quote uptime
-checks, or latency-sensitive liquidation/arbitrage flows that need maker
-allowlists/denylists. It exposes ACK/quote timing and raw maker identity; if
-you accept manually, prefetch account sequence and timeout height before quote
-collection so the signed accept tx can be broadcast immediately after selecting
-a quote.
+Use client-side gateway mode when the browser needs lower click-time latency or
+special quote selection. In that mode, the app is moving gateway/indexer duties
+to the client: TakerStream request ownership, ACK mapping, quote collection,
+quote selection, accept transaction preparation, per-wallet serialization,
+optimistic state, and chain/indexer reconciliation. Read
+[references/client-side-gateway.md](./references/client-side-gateway.md)
+before implementing it.
+
+Use manual TakerStream diagnostics when you only need raw quote behavior,
+maker identity, or quote uptime checks. Diagnostics should not silently turn
+into settlement; settlement requires all client-side gateway responsibilities.
+
+## Client-Side Gateway Mode
+
+Client-side gateway mode is a latency optimization, not just a transport
+choice. The gateway behaves like a coordinator/indexer: it opens RFQs, tracks
+ACKs, collects maker quotes, chooses executable quotes, assembles settlement,
+and reconciles state. A browser implementation must replace those duties
+explicitly instead of only opening a WebSocket.
+
+- Keep one active taker stream owner per wallet/session and reconnect
+  deliberately on wallet changes.
+- Track `clientId -> rfqId` ACK replacement. Quotes can arrive before ACK, and
+  ACK ids may differ from local client ids.
+- Use short, bounded collection windows. Start the window from ACK or the first
+  matching quote, not from arbitrary UI time.
+- Sort executable quotes deterministically: lower price is better for long
+  takers, higher price is better for short takers.
+- Validate quote freshness, signed payload fields, maker eligibility, market,
+  direction, quantity, TTL, chain ids, contract, and worst-price guardrails.
+- Prefetch account sequence and timeout height before selection when quote TTLs
+  are tight. Avoid post-selection RPCs in sub-second paths.
+- Serialize accepts per wallet. Parallel accepts can race account sequence even
+  when they target different markets.
+- Treat optimistic position state as provisional until chain/indexer data
+  confirms it. Roll back cleanly on post-match broadcast or chain failure.
+- Keep a managed gateway fallback or recovery path unless the product has
+  operational monitoring for quote hit rate, maker failures, and stuck state.
 
 ## Production Rules
 
@@ -131,6 +166,21 @@ of user-facing states and serialize trade submission:
   of the grid. Filtering can resize the target card and make the trading form
   feel unstable.
 
+## Prequote Price Semantics
+
+Separate display prices from RFQ guardrails:
+
+- Button prices should show the best live maker quote when available.
+- Fallback display prices can use index price plus or minus the user's
+  slippage setting, but label them as estimates.
+- Prequote RFQ `worstPrice` does not have to equal user slippage. A client-side
+  gateway can use tighter RFQ prequote tiers for quote discovery, then escalate
+  after misses.
+- User slippage still belongs in final submit guardrails and can affect sizing
+  indirectly when quantity is derived from quote notional.
+- Worst price is a guardrail, not an expected execution price. Seeing better
+  maker quotes than the guardrail is normal.
+
 ## RFQ Input Rules
 
 For open requests, derive quantity from stake, leverage, and mark price:
@@ -258,6 +308,8 @@ editing or canceling a lane, re-query before signing fresh intents.
 
 ## References
 
+- [references/client-side-gateway.md](./references/client-side-gateway.md): moving
+  gateway/indexer duties into a browser latency path.
 - [references/frontend-rfq-flow.md](./references/frontend-rfq-flow.md): gateway vs manual
   TakerStream, quote filters, and signer rules.
 - [references/authz-and-autosign.md](./references/authz-and-autosign.md): Web3Gateway

skills/injective-rfq-integrations/references/client-side-gateway.md

@@ -0,0 +1,167 @@
+# Client-Side Gateway Mode
+
+Use this reference when a browser app moves RFQ gateway/indexer duties into the
+client to reduce click-time latency. Keep the guidance generic: do not depend
+on private app routes, private maker lists, or project-specific flags.
+
+## Mental Model
+
+The gateway is not only a transaction helper. It behaves like a short-lived RFQ
+coordinator:
+
+- opens RFQ requests
+- maps local client ids to acknowledged RFQ ids
+- collects signed maker quotes
+- filters invalid or stale quotes
+- selects executable quotes
+- prepares or signs settlement context
+- broadcasts quickly enough for quote TTLs
+- reconciles selected quotes against chain and indexer state
+
+Client-side gateway mode is safe only when the frontend owns those same duties.
+Opening a TakerStream and displaying quotes is not enough.
+
+## When To Use It
+
+Use client-side gateway mode for:
+
+- latency-sensitive browser trading where managed gateway prepare is too slow
+- maker-routed flows that need explicit allowlists, denylists, or selection
+  policy
+- products that need immediate optimistic fills from selected quotes
+- operational experiments where quote ACK timing and maker response timing are
+  part of the product signal
+
+Prefer the managed RFQ gateway when:
+
+- the product does not need custom quote selection
+- the app cannot own account sequence and timeout-height readiness
+- monitoring cannot detect quote-hit drops, maker failures, or reconciliation
+  drift
+- the team wants backend-owned transaction assembly and fee-payer behavior
+
+## Request Lifecycle
+
+1. Build canonical RFQ input from market metadata, quantity, margin, direction,
+   and worst-price guardrail.
+2. Attach a unique `clientId` for local tracking.
+3. Connect one taker stream per wallet/session.
+4. Send the prequote or firm request.
+5. Track the ACK. Replace local `clientId` with acknowledged `rfqId` when the
+   stream returns one.
+6. Accept quotes for both the original `clientId` and acknowledged `rfqId`
+   during the transition because quotes can arrive before ACK.
+7. Start the quote collection window on ACK or first matching quote.
+8. Filter quotes before sorting.
+9. Select enough quotes to fill the requested quantity.
+10. Broadcast without post-selection RPCs when quote TTLs are tight.
+11. Emit optimistic state only after quote selection or match, then reconcile
+    against chain/indexer state.
+
+## Quote Validation Checklist
+
+Reject a quote unless all required fields match the active request:
+
+- signature is present
+- maker address is present
+- taker address matches the active wallet/session
+- market id matches
+- direction matches
+- RFQ id or client id matches the active request
+- Cosmos chain id is `injective-1`
+- EVM chain id, when present, is `1776`
+- contract address is the canonical RFQ contract
+- quantity is positive and can fill the requested amount after aggregation
+- price is inside the worst-price guardrail
+- expiry leaves enough TTL for broadcast and inclusion
+- maker is allowed by the current routing policy
+
+Sort valid quotes deterministically:
+
+- long taker: lower price first
+- short taker: higher price first
+- equal price: preserve stable ordering or use explicit secondary criteria such
+  as quantity or TTL
+
+## Price And Slippage Semantics
+
+Keep these concepts separate:
+
+- **display quote**: best current maker quote shown in the UI
+- **fallback display estimate**: index price plus or minus user slippage when no
+  maker quote is present
+- **prequote worst price**: quote-discovery guardrail sent to makers
+- **final submit worst price**: user-facing execution guardrail
+
+Do not assume prequote worst price equals user slippage. A latency-focused app
+can start prequote discovery with tighter RFQ-specific tiers, then widen after
+misses. User slippage still belongs in final submit validation and can affect
+derived sizing when the user enters a quote notional instead of a base
+quantity.
+
+## Sequence, Timeout, And TTL
+
+For manual accept paths, quote TTL can be shorter than the time needed to fetch
+account state after selection. Prepare the broadcast path before collecting:
+
+- account number
+- sequence
+- timeout height or timeout timestamp
+- gas limit
+- fee payer or broadcaster context
+- signer order and pubkey normalization
+
+If quote TTLs are sub-second or low-second, avoid fetching sequence or block
+height after quote selection. Select, sign, and broadcast immediately.
+
+## State And Concurrency
+
+Serialize firm accepts per wallet. Per-market locks are not enough because two
+parallel accepts can consume or invalidate the same account sequence.
+
+Track active state explicitly:
+
+- stream connection generation
+- latest request ids by market and direction
+- in-flight firm accept id
+- selected quote ids
+- optimistic fills
+- rollback timeout
+- reconciliation status
+
+Optimistic UI should update from selected or matched quote data, not requested
+input alone. Clear provisional state on real indexer insert/update/delete,
+explicit rollback, account reset, or expiry.
+
+## Portability Pattern
+
+Before moving any gateway/indexer behavior into a client, write down what the
+gateway currently owns and split it into three buckets:
+
+- protocol correctness: signing bytes, signer order, chain ids, decimal
+  canonicalization, AuthZ grants
+- latency path: prequote, quote collection, quote selection, sequence
+  readiness, broadcast timing
+- observability: ACK timing, quote-hit rate, maker failures, stale state, user
+  copy
+
+Move only the latency-critical pieces client-side first. Keep a managed gateway
+or backend fallback until the client path has parity tests and production
+metrics.
+
+## Tests To Add
+
+Cover these before calling the client-side gateway production-ready:
+
+- quote before ACK is accepted for the active request
+- ACK replacement updates latest RFQ id without dropping matching quotes
+- long quotes sort lowest price first
+- short quotes sort highest price first
+- invalid chain id, market id, direction, contract, maker, stale expiry, and
+  outside-worst-price quotes are rejected
+- collection window closes on timeout and selects enough quantity
+- account sequence race is blocked by per-wallet serialization
+- selected quote data drives optimistic filled state
+- failed post-selection broadcast rolls back optimistic state once
+- managed gateway fallback or retry path is reachable when no valid quotes are
+  collected