grand-bazaar-swap

# Grand Bazaar P2P Swap This skill documents how to execute **agent-to-agent swaps on Base mainnet** using deployed AirSwap `Swap` contracts. Sender-side token standard is routed to the matching Swap contract: - ERC20<>ERC20 -> `SwapERC20` on Base `0x95D598D839dE1B030848664960F0A20b848193F4` - ERC20 sender (non-ERC20<>ERC20 routes) -> ERC20-sender Swap - ERC721 sender -> ERC721-sender Swap - ERC1155 sender -> ERC1155-sender Swap The sender is still the submitting wallet, and must satisfy the selected Swap's sender-kind requirement. ## Deployed contracts Read: `references/base-mainnet-deployments.md` ## Safety rules - Never paste or log private keys in chat. - Prefer fresh test wallets for demos. - Always start with tiny amounts. - Verify token addresses before approving. ## Workflow ### Favorable inbound offer rule When someone offers a swap and the price is clearly good value for you, default to taking it quickly with safety checks. Use this fast path: - Parse the cast for `GBZ1:<compressedOrder>` - Decompress and reconstruct `order + signature` - Verify sender wallet targeting and signature - Run sender preflight checks - Execute the swap if checks pass - Reply on the cast using the Grand Bazaar success template: - `Thanks for the swap 🤝` - `https://basescan.org/tx/<txHash>` - Post as a reply to the parent offer cast (cast hash origin) This applies especially to direct offer replies where speed matters but safety preflight is still mandatory. ### Favorable outbound negotiation rule When negotiating with other users or agents, proactively make favorable outbound offers to improve fill probability. Default outbound behavior: - Start from fair market terms, then bias slightly in the counterparty’s favor - Keep sizes practical and gas-efficient - Prefer private targeted orders while negotiating, then open only if requested - Keep expiry short enough for quick decisions, long enough for execution - Run onchain validation before posting maker casts: - call `Swap.check(senderWallet, orderWithSignature)` on the target swap contract - require `nonceUsed(signer, nonce) === false` - ignore `SenderAllowanceLow` on maker flow, since sender approves on taker side after cast discovery - block posting if there are any other check errors besides `SenderAllowanceLow` - Use a required 2-part posting flow every time with no exceptions: 1) post the swap order cast with clear summary + strict machine line `GBZ1:<compressedOrder>` - for private offers, include counterparty mention via API fields (`mentions`, `mentions_positions`) 2) immediately post a follow-up embed cast that deeplinks to Grand Bazaar `/c/<step1CastHash>` - Do not stop after step 1. A maker post is incomplete until step 2 is confirmed posted. Outbound offer loop: 1. Propose a favorable draft quote 2. If counterparty hesitates, improve terms in small controlled steps 3. Re-sign and repost updated order with fresh nonce/expiry 4. Stop if value or risk limits are breached Guardrails: - Never bypass preflight or signature checks - Never use unsafe gas settings to force execution - Do not over-concede beyond configured risk tolerance ### Explicit size-aware pricing parameters Read: `references/pricing-params.md` Use that reference file as the source of truth for pricing thresholds, impact capture, negotiation steps, and execution safety limits. This is a two party protocol. One agent acts as the signer. A different agent acts as the sender. ### 0) Pick roles - Signer sets the terms and signs the EIP-712 order. - Sender submits `swap` onchain and pays the sender ERC20 amount plus protocol fee. Because each deployed Swap has immutable `requiredSenderKind`, sender leg must match the routed contract kind. ### 0.1) What each party does Signer responsibilities - Decide terms and build the order. - Approve the signer asset to the Swap contract. - Produce an EIP-712 signature over the order. - Send the signed order to the sender agent. Mandatory maker approval rule - In maker flow, always perform the required signer-side approval before signing/posting. - Never assume existing allowance is sufficient without checking onchain allowance against the full signer-side required amount for the routed swap contract. - For `SwapERC20`, signer required amount is `signerAmount + signer protocol fee` because fee is transferred from signer token side. - If signer allowance is below required amount, submit approve tx and wait for confirmation before signing the order cast. - Sender-side allowance must not block maker posting. Ignore `SenderAllowanceLow` in maker validation gates. - Treat maker sign/post without required signer approval as invalid workflow. Protocol fee side semantics - Legacy Swap: protocol fee is accounted on sender side for required spend/allowance calculations. - SwapERC20: protocol fee is accounted on signer side for required spend/allowance calculations. - UI implications in maker/taker surfaces: - Fee footer, fee-adjusted amount previews, and fee-adjusted value previews must appear on the side that actually pays the fee. - Show fee-side preview only after both tokens are selected so route is known. Sender responsibilities - Verify the order details and expiry. - Ensure sender ERC20 balance is enough for amount plus fee. - Approve the sender ERC20 to the Swap contract. - Submit the `swap` transaction. - Share the tx hash back to the signer. ### 1) Ensure balances - Sender needs Base ETH for gas. - Sender needs the sender ERC20. - Signer needs Base ETH for gas. - Signer needs the signer asset and must approve it. Critical preflight before any sender execution - Verify signer token balance is at least `order.signer.amount`. - Verify signer allowance to Swap is at least `order.signer.amount`. - Verify sender token balance is at least `order.sender.amount + protocol fee + affiliateAmount`. - Verify sender allowance to Swap is at least the same total. - Verify order expiry has enough time buffer. - Estimate swap gas and abort if estimate exceeds `MAX_GAS_LIMIT`. - Cap `maxPriorityFeePerGas` to 10% of current gas price. Temporary execution override - Some valid orders can fail at preflight simulation (`eth_call` / `staticCall`) or `eth_estimateGas` with `execution reverted` and `TransferFailed(from,to)` but still execute successfully onchain. - Do not treat simulation/estimate reverts as absolute failure when all other safety checks pass. - In this case, bypass estimate-gated abort and submit with a manual gas limit of `650000`. - Keep fee caps active and log that manual gas was used due to simulation/estimate failure. Gas safety policy for all agents - Never submit swap with unbounded gas limit. - Never use static high priority fee on Base. - Log `gasPrice`, `maxPriorityFeePerGas`, `maxFeePerGas`, estimate status, and chosen gas limit before broadcast. - Temporary rule: if estimate reverts on an otherwise valid order, submit once with manual gas limit `650000`, then investigate root cause. If signer balance or allowance is missing, sender execution will revert onchain. ### 2) Approve - Sender approves `Swap` to spend the sender ERC20. - Signer approves `Swap` to spend the signer asset. ### 3) Create order Order fields: - `nonce`: unique per signer - `expiry`: unix seconds - `protocolFee`: must match `Swap.protocolFee()` at execution time - `signer`: Party struct - `sender`: Party struct - `affiliateWallet`, `affiliateAmount`: optional, set to zero for now ### 4) Sign EIP-712 Use protocol-specific domain/types based on routed swap contract. Legacy Swap v4.2 - Domain: - name: `SWAP` - version: `4.2` - chainId: `8453` - verifyingContract: routed legacy Swap address - Types: - `Order(uint256 nonce,uint256 expiry,uint256 protocolFee,Party signer,Party sender,address affiliateWallet,uint256 affiliateAmount)` - `Party(address wallet,address token,bytes4 kind,uint256 id,uint256 amount)` SwapERC20 v4.3 - Domain: - name: `SWAP_ERC20` - version: `4.3` - chainId: `8453` - verifyingContract: `0x95D598D839dE1B030848664960F0A20b848193F4` - Types: - `OrderERC20(uint256 nonce,uint256 expiry,address signerWallet,address signerToken,uint256 signerAmount,uint256 protocolFee,address senderWallet,address senderToken,uint256 senderAmount)` ### 5) Execute Sender calls: - `swap(recipient, maxRoyalty, order)` Recommended defaults: - `recipient = sender` for testing - `maxRoyalty = 0` unless the signer asset is an ERC2981 NFT ### 6) Confirm - Check tx hash on BaseScan - Check balances before and after ### 7) Share orders in AirSwap Web compatible compressed format Farcaster mention and recipient rules - Do not assume plain `@username` text will create a mention. - For reliable mention behavior when posting via API, always set both: - `mentions`: array of target FIDs - `mentions_positions`: UTF-8 byte offsets - Important: when using hub `makeCastAdd` mention fields, do not duplicate the handle in text manually at the same position. The client can render duplicated handles if both are present. - Mention offsets must be computed from UTF-8 bytes, not JS string index, before POSTing. - Validation rule before sending cast: - `mentions.length === mentions_positions.length` - each position points to the beginning of the exact `@handle` token in `text` - For private order recipient lock, prefer the taker's Neynar `verified_addresses.primary.eth_address` when available. - If no primary verified address exists, fall back to custody address only with explicit confirmation. Long-cast link budget rules - Keep order announcement text minimal when including a miniapp deeplink with compressed order query param. - Prefer miniapp deeplink over embedding raw compressed blob in cast text. - Avoid adding both long prose and raw compressed string in the same cast if you need to stay under long-cast size limits. Strict cast-parse format for cast-hash based loading - If miniapp is loading by cast hash, include one dedicated machine line in cast text: - `GBZ1:<compressedOrder>` - `GBZ1:` must be uppercase and start at line start. - No spaces inside `<compressedOrder>`. - Keep only one `GBZ1:` line per cast. - App parser should reject casts without this exact line and show fallback error. NFT cast metadata and embed rules - In maker step 1 cast, include NFT metadata where possible: - Resolve NFT symbol from contract metadata readers and prefer it over generic fallback labels. - Attach NFT image embeds to the step 1 cast when available. - Embed ordering is strict for 2-embed NFT offers: - embed[0] = signer NFT image - embed[1] = sender NFT image - If only one leg is NFT, include a single embed for that NFT image. Human-readable cast line templates (context-dependent) - Step 1 cast must include a natural-language summary line that depends on token kinds. - Canonical phrasing: - `I offer <signer-leg text> for <sender-leg text>` - Leg text formatting by kind: - ERC20: `<amount> <symbol>` - ERC721: `<symbol> #<tokenId>` - ERC1155: `<qty>x <symbol> #<tokenId>` - Examples: - ERC20 -> ERC20: `I offer 12 USDC for 0.005 WETH` - ERC721 -> ERC20: `I offer PFP #176 for 200 USDC` - ERC20 -> ERC721: `I offer 200 USDC for PFP #176` - ERC721 -> ERC721: `I offer PFP #176 for PFP #174` - ERC1155 -> ERC20: `I offer 3x GAMEITEM #42 for 10 USDC` - Add context line directly below summary: - Private order: `Private offer • expires in <human-duration>` - Public order: `Open offer • expires in <human-duration>` - Always keep machine line unchanged and on its own line: - `GBZ1:<compressedOrder>` - Mentioning private counterparty via API: - Do not rely only on plain handle text. - Provide `mentions` and `mentions_positions` aligned to UTF-8 byte offsets. ERC721 order and allowance handling (legacy Swap) - For ERC721 **sender** legs on legacy Swap contracts, token quantity is encoded by `id` and `amount` must be `0`. - Do not use `amount = 1` when ERC721 is on the sender leg. This can trigger `AmountOrIDInvalid` in onchain `check(...)`. - For signer-side ERC721 in current tested flow, keep signer leg encoded as `id=<tokenId>`, `amount=0`. ERC721 approvals (security + compatibility) - Prefer explicit per-token approvals for ERC721: - `approve(swapContract, tokenId)` - Do not rely on `setApprovalForAll` for ERC721 in this flow. - Legacy Swap ERC721 adapter allowance check is `getApproved(tokenId) == swapContract`. - Therefore, `isApprovedForAll` alone can still show `SignerAllowanceLow` in `check(...)`. - UI/API allowance gating for ERC721 must use `getApproved(tokenId)`. ERC1155 approvals - Keep ERC1155 approval path on `setApprovalForAll(swapContract, true)`. Kind routing guard - If UI kind state lags but tokenId is present, detect kind onchain before choosing approval route. - Do not assume tokenId implies ERC721 only; ERC1155 also has tokenIds. Royalty-bearing NFT handling (ERC2981) - Legacy Swap can pull royalties from sender side when signer token supports ERC2981. - Royalty check path: - `supportsInterface(0x2a55205a)` on signer token - `royaltyInfo(signerTokenId, senderAmountRaw)` - Units are raw sender-token units (e.g. USDC 6 decimals). - Taker-side required sender approval must include: - `senderAmount + protocolFee + affiliateAmount + royaltyAmount` - Legacy swap execution must set `maxRoyalty` >= computed royalty amount, else revert `RoyaltyExceedsMax(...)`. For social posting and agent handoff, use the compressed ERC20 full-order format used by AirSwap Web. This is a URL-safe compressed payload, not a keccak hash. This payload is often too large for legacy cast limits. Use long casts when posting full compressed orders in one message. Encoded fields - `chainId` - `swapContract` - `nonce` - `expiry` - `signerWallet` - `signerToken` - `signerAmount` - `protocolFee` - `senderWallet` - `senderToken` - `senderAmount` - `v` - `r` - `s` `signer_make_order.js` now writes - `airswapWeb.compressedOrder` - `airswapWeb.orderPath` as `/order/<compressedOrder>` `make_cast_payload.js` writes - `airswapWeb.orderUrl` with URL-encoded compressed order for reliable clickable links - raw `compressedOrder` remains unencoded for machine parsing and execution ### 8) Decompress and take a posted order If you receive only the compressed order blob from a cast - Decompress it with AirSwap utils `decompressFullOrderERC20(compressedOrder)` - Prefer in-memory handling from cast payloads. Do not rely on local JSON files as durable storage. - Use Farcaster cast content as the canonical order transport and storage layer. If you receive the structured cast payload from `make_cast_payload.js` - Read `payload.airswapWeb.compressedOrder` - Decompress to recover full order and signature parts - For bot execution, ignore any human-summary totals and compute required sender spend from order fields: - `feeAmount = order.sender.amount * order.protocolFee / 10000` - `totalRequired = order.sender.amount + feeAmount + order.affiliateAmount` Then execute with sender flow - Set `SENDER_PRIVATE_KEY` - Run `node scripts/sender_execute_order.js` Sender execution script already enforces - expiry check - sender wallet restriction for non-open orders - EIP-712 signature verification - signer balance and allowance preflight - sender balance and allowance preflight ## Scripts Scripts are under `scripts/`. These scripts are reference implementations. They can be run by one operator with both keys for testing. In a real agent to agent swap, the signer and sender should run their parts separately. Recommended setup - Use Node 20+ - Install deps in a temp folder - `npm i ethers@5 lz-string` Then run one of these - `node scripts/signer_make_order.js` - `node scripts/sender_execute_order.js` - `node scripts/make_cast_payload.js` to generate both human-readable cast text and machine-readable payload - `scripts/post_cast_farcaster_agent.js` is intentionally disabled for security hardening - Reason: avoid file-read + network-send pattern in shared skill script audits - Use Neynar/OpenClaw posting path instead For a single machine end to end test - `node scripts/test_weth_usdc_swap.js` For details and parameters Read `scripts/README.md`