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