@cowprotocol/sdk-trading-solana 0.7.0 → 0.8.0

package/README.md

@@ -10,51 +10,232 @@
 | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
 | ![Statements](https://img.shields.io/badge/statements-85.64%25-yellow.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-94.44%25-brightgreen.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-58.13%25-red.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-93.78%25-brightgreen.svg?style=flat) |
 
-CoW Protocol's Solana settlement support: Jupiter-sourced quotes and on-chain `CreateOrder`
-posting against the CoW Protocol Solana settlement program.
+`@cowprotocol/sdk-trading-solana` is CoW Protocol's Solana settlement client: it turns a quote
+into an on-chain `CreateOrder` instruction against the CoW Protocol Solana
+settlement program.
 
-**Experimental.** The Solana settlement program this package targets isn't deployed anywhere
-reachable yet. See `docs/superpowers/specs/2026-09-01-sdk-trading-solana-extraction-design.md` in
-the `cowswap` repo for background.
+**Experimental.** The settlement program (`cow-settlement-interface` / `solana-programs`) is a young,
+actively evolving deployment — expect breaking changes to the intent wire format, PDA seeds and this
+package's API across minor versions. The currently deployed program id is exported as
+[`SOLANA_SETTLEMENT_PROGRAM_ID`](https://github.com/cowprotocol/cow-sdk/blob/main/packages/config/src/chains/const/contracts.ts)
+from `@cowprotocol/sdk-config` — see it on
+[Solana Explorer](https://explorer.solana.com/address/FYp8R5K4B3B1Kfr7QuWzMz4TwoT7wptjYtxgCrY5sRXb).
 
-## Usage
+```
+npm install @cowprotocol/sdk-trading-solana
+```
+
+A runnable end-to-end example lives in [`examples/nodejs/solana`](../../examples/nodejs/solana).
+
+## Making a trade
+
+### Step 0 — approve the settlement program as SPL delegate
+
+The settlement program moves funds out of the seller's token account via a CPI, which SPL Token
+only allows for an approved `delegate`. Before any order on a given sell-token account can settle,
+that account's owner must approve the settlement **state PDA** (not the program id itself) as
+delegate, for at least the amount being sold. `approveCowProtocol` builds that instruction without
+sending it, deriving the sell-token account and delegate for you:
+
+```ts
+const sdk = new SolanaTradingSdk() // same env as the SDK instance used for the quote below
+
+const approveInstruction = sdk.approveCowProtocol({
+  ownerAddress: owner,
+  sellTokenAddress: sellMint,
+  approveAmount, // at least the order's sellAmount
+})
+```
 
-Quoting needs no signer:
+This approval is **not one-time**: like any SPL delegate, each settled order decrements the
+delegate's remaining allowance by the amount actually transferred, so approving once for exactly one
+order's `sellAmount` leaves nothing for the next one. Check the sell-token account's current
+`delegate`/`delegatedAmount` before building an order, and reapprove (topping the allowance back up)
+whenever it's insufficient — approving a new amount replaces the previous allowance rather than
+adding to it. Separately, because the delegate PDA is derived from the settlement program's
+major/minor version (`getSettlementSeed`), a program upgrade that bumps that version changes the
+delegate address entirely, requiring a fresh approval regardless of remaining allowance. This step
+can be sent as its own transaction ahead of time, or bundled with the `CreateOrder` instruction in
+the same transaction — see [Step 2](#step-2--create-the-order) below.
+
+### Step 1 — get a quote
+
+Quoting needs no signer, just the addresses and amount:
 
 ```ts
+import { OrderKind } from '@cowprotocol/sdk-order-book'
 import { SolanaTradingSdk } from '@cowprotocol/sdk-trading-solana'
 
-const sdk = new SolanaTradingSdk()
+const sdk = new SolanaTradingSdk() // pass `{ env: 'staging' }` to target staging
+
 const { quoteResults, solanaQuote, buildOrder, postSwapOrderFromQuote } = await sdk.getQuote({
-  ownerAddress,
-  receiverAddress,
+  ownerAddress, // the seller's wallet — signs the CreateOrder transaction
   sellTokenAddress,
   sellTokenDecimals,
   buyTokenAddress,
   buyTokenDecimals,
-  amount,
-  kind,
+  amount, // bigint — sell-side amount for a SELL order, buy-side amount for a BUY order
+  kind: OrderKind.SELL,
 })
 ```
 
-### Let the SDK submit the order
+- `quoteResults` mirrors the EVM SDK's [`QuoteResults`](../trading/src/types.ts) (trade parameters, suggested slippage, amounts
+  and costs) so UI code can share formatting logic across chains.
+- `solanaQuote` is the Solana-specific quote: the order **intent** that was built from the quote
+  response, its encoded bytes, its `uid`, the order PDA it will live at, and the raw upstream quote
+  (real amounts/slippage) the intent was derived from.
+- Native SOL is accepted as the sentinel address; it's substituted with wrapped SOL (WSOL) before
+  quoting and building the intent, since Solana has no native-token mint to reference on-chain.
+- Passing `sellTokenProgramId` / `buyTokenProgramId` (e.g. `TOKEN_2022_PROGRAM_ID`) is required for
+  Token-2022 mints, since the associated token account address differs by program.
 
-`signAndSend` is passed at the point of signing:
+### Step 2 — create the order
+
+Two ways to get the order on-chain, depending on whether you need to bundle it with other
+instructions:
+
+**Let the SDK submit it as its own transaction** — pass a signing/sending function at the point of
+signing:
 
 ```ts
 const result = await postSwapOrderFromQuote(signAndSend)
+// result.orderId, result.txHash / result.signature
+```
+
+`signAndSend` has the shape `(instruction: TransactionInstruction) => Promise<{ signature: string }>`
+— build, sign and send the transaction however fits your app (a `Connection` + `Keypair`, a wallet
+adapter, a Squads/Safe-style multisig flow, etc).
+
+**Bundle the order with your own instructions** — a Solana order is created by a single instruction,
+so it can share one transaction with, say, the Step 0 delegate approval, a native-SOL wrap, or
+anything else. `buildOrder` returns that instruction without sending it:
+
+```ts
+const { instruction, orderId, orderPda, uid } = await buildOrder()
+
+await sendMyTransaction([approveInstruction, instruction])
 ```
 
-### Bundle the order with your own instructions
+This is the recommended path whenever the sell-token account's delegate allowance needs
+topping up for this trade, since it lets the delegate approval and the order creation land
+atomically in one transaction.
 
-A Solana order is created by a single instruction, so it can share a transaction with, say, a wrap and a
-token delegation. `buildOrder` returns that instruction without sending it:
+Both paths accept the same optional `advancedSettings` (currently `quoteRequest.receiver` and
+`quoteRequest.validTo`) and apply them identically — overriding `receiver` or `validTo` re-derives
+the order's `uid` and PDA so they still match the intent actually being created:
 
 ```ts
-const { instruction, orderId } = await buildOrder()
+await postSwapOrderFromQuote(signAndSend, { quoteRequest: { receiver: otherWallet.toBase58() } })
+```
+
+### Step 3 — read back the result
+
+Both `postSwapOrderFromQuote` and `buildOrder` return an `orderId` — the `uid` as the `0x`-prefixed
+hex string the CoW order-book API uses for EVM orders too, so it can be handled uniformly by shared
+UI/state code. `solanaQuote.orderPda` is the on-chain account the order lives at once the
+`CreateOrder` instruction lands.
 
-await sendMyTransaction([...wrapInstructions, approveInstruction, instruction])
+## The intent model
+
+Every Solana order is, at its core, a `SolanaOrderIntent` — a fixed-layout struct that is the direct
+TypeScript counterpart of `OrderIntent` in `cow-settlement-interface` (`interface/src/data/intent.rs`).
+Unlike an EVM order (an EIP-712 message the owner signs off-chain and the order-book stores), a
+Solana intent is never signed as data — it's written directly into an on-chain account by an
+instruction the owner's wallet signs.
+
+```ts
+interface SolanaOrderIntent {
+  owner: PublicKey // signs the CreateOrder transaction
+  buyTokenAccount: PublicKey // receives the buy-side proceeds — implicitly encodes the receiver
+  buyMint: PublicKey
+  sellTokenAccount: PublicKey // funds pulled from here — must be owned by `owner`; implicitly encodes the spender
+  sellMint: PublicKey
+  sellAmount: bigint
+  buyAmount: bigint
+  validTo: number // unix timestamp, seconds
+  kind: OrderKind // SELL | BUY
+  partiallyFillable: boolean
+  createdOnChain: boolean // must be true — see "Authentication" below
+  appData: Uint8Array // exactly 32 bytes, opaque to the settlement program; no convention defined yet, sent as zeroes
+}
 ```
 
-Both paths apply `advancedSettings` identically — overriding `receiver` or `validTo` re-derives the order's
-`uid` and PDA so they still match the intent actually being created.
+### Encoding
+
+`encodeOrderIntent` packs the intent into the exact 213-byte (`ENCODED_ORDER_INTENT_SIZE`) little-endian
+layout the settlement program reads (`EncodedOrderIntent::from(&OrderIntent)`):
+
+| Bytes | Field                            |
+| ----- | --------------------------------- |
+| 32    | `owner`                           |
+| 32    | `buyTokenAccount`                 |
+| 32    | `buyMint`                         |
+| 32    | `sellTokenAccount`                |
+| 32    | `sellMint`                        |
+| 8     | `sellAmount` (u64 LE)             |
+| 8     | `buyAmount` (u64 LE)              |
+| 4     | `validTo` (u32 LE)                |
+| 1     | flags (bit 0 `createdOnChain`, bit 1 `kind === BUY`, bit 2 `partiallyFillable`) |
+| 32    | `appData`                         |
+
+### Identity: uid and the order PDA
+
+`hashOrderIntent` takes the SHA-256 digest of the encoded intent bytes. That 32-byte digest is both:
+
+- the order's **uid** (`toOrderId` formats it as the `0x`-prefixed id used across the SDK), and
+- the middle seed of the order's **program-derived address** (`findOrderPda`), alongside a
+  version-embedded settlement seed (`getSettlementSeed`, `"settlement v" + version`, padded to a
+  fixed width so seeds from different versions can't collide) and a trailing `"order"` seed.
+
+Because the uid is a hash of the intent's content, any change to the intent — including an
+`advancedSettings` override to `receiver` or `validTo` — changes the uid and therefore the PDA the
+order will be created at. `buildSolanaSwapOrder` re-derives both whenever `advancedSettings`
+actually changes the intent, so the instruction it returns always targets the PDA matching the
+intent it encodes.
+
+### The `CreateOrder` instruction
+
+`buildCreateOrderInstruction` builds the instruction that writes the intent on-chain, matching
+`CreateOrder::into::<Instruction>()`:
+
+- **data**: `[discriminator = 2, ...213 intent bytes]`
+- **accounts**: `owner` (readonly signer), `createdBy` (writable signer — funds the new order PDA's
+  rent; may equal `owner`), `orderPda` (writable), the System Program
+
+### Authentication: why `createdOnChain` must be `true`
+
+`cow-settlement-interface` supports two ways an intent can be authenticated: created on-chain (the
+owner signs the `CreateOrder` transaction themselves) or via an off-chain Ed25519-presigned order
+that anyone can submit on the owner's behalf. This SDK only implements the former —
+`encodeOrderIntent` always sets the on-chain flag, and the settlement program authenticates the
+order against the transaction's own signature rather than a separate signed payload. This is the
+Solana counterpart of an EVM `PRESIGN` order (`buildSolanaSwapOrder` reports
+`signingScheme: SigningScheme.PRESIGN` for exactly this reason) rather than an EIP-712 `EIP712` one.
+
+## Example app
+
+[`examples/nodejs/solana`](../../examples/nodejs/solana) is a runnable, end-to-end demo: it gets a
+quote, approves the settlement program's delegate, builds the `CreateOrder` instruction, bundles
+both into one transaction and submits it. **It targets mainnet-beta by default and trades real
+funds** — see that example's own README for setup, including how to point it at devnet instead.
+
+## Why Solana trading looks different from EVM trading
+
+On EVM chains, `TradingSdk` gets a quote from the CoW order-book API, has the caller sign an
+EIP-712 typed order, and POSTs the signed order to the order-book, which later settles it. Solana
+has neither an order-book API to post to nor an implicit global signer:
+
+- **Quotes don't come from the CoW order-book (yet).** `SolanaTradingSdk.getQuote` currently sources
+  pricing and route discovery from an external quoting API, then builds a CoW Protocol order
+  **intent** from the result. That API is used for quoting only — orders are never submitted through
+  it, only ever created via the CoW settlement program. This is expected to move onto the CoW
+  order-book API directly as Solana support matures.
+- **Orders are created entirely on-chain.** There is no signed order body to POST. Creating an order
+  means submitting a single `CreateOrder` instruction that writes the order intent into a new
+  program-derived account (the order PDA). The transaction signature that lands on-chain *is* the
+  order's authentication.
+- **No bound signer.** The EVM SDK gets its signer from a global adapter set once at app startup.
+  This package has no such adapter: quoting needs no signer at all, and a signing/sending function
+  (`SolanaSignAndSend`) is passed only at the point of actually submitting a transaction. That also
+  means a quote can be turned into a raw `TransactionInstruction` (via `buildOrder`) without ever
+  involving a signer, so it can be composed into a larger transaction built and sent by the caller.

package/dist/index.d.mts

@@ -29,16 +29,16 @@ declare class JupiterAPI {
 }
 
 /**
- * TS port of `cow-settlement-interface`'s `OrderIntent` (interface/src/data/intent.rs, v0.3.0).
+ * TS port of `cow-settlement-interface`'s `OrderIntent` (interface/src/data/intent.rs, v0.4.0).
  * Every field here has a Rust counterpart with the same name; keep them in sync if the settlement
  * program's wire format changes.
  */
 interface SolanaOrderIntent {
     owner: PublicKey;
-    buyTokenAccount: PublicKey;
-    buyMint: PublicKey;
     sellTokenAccount: PublicKey;
     sellMint: PublicKey;
+    buyTokenAccount: PublicKey;
+    buyMint: PublicKey;
     sellAmount: bigint;
     buyAmount: bigint;
     /** Unix timestamp seconds. */
@@ -73,7 +73,6 @@ declare function toOrderId(uid: Uint8Array): string;
 
 interface SolanaQuoteParameters {
     ownerAddress: PublicKeyInitData;
-    receiverAddress: PublicKeyInitData;
     sellTokenAddress: PublicKeyInitData;
     sellTokenDecimals: number;
     buyTokenAddress: PublicKeyInitData;
@@ -81,6 +80,7 @@ interface SolanaQuoteParameters {
     /** Sell-side amount for a SELL order, buy-side amount for a BUY order — same convention as Jupiter's `amount`. */
     amount: bigint;
     kind: OrderKind;
+    receiverAddress?: PublicKeyInitData;
     partiallyFillable?: boolean;
     /** Order lifetime from now, in seconds. Defaults to 30 minutes. */
     validForSeconds?: number;
@@ -217,6 +217,15 @@ declare function postSolanaSwapOrderFromQuote(quote: SolanaSwapOrderQuote, signA
 interface SolanaTradingSdkOptions {
     env?: CowEnv;
 }
+interface ApproveCowProtocolParams {
+    ownerAddress: PublicKeyInitData;
+    sellTokenAddress: PublicKeyInitData;
+    /** Amount to approve, at least the order's `sellAmount`. */
+    approveAmount: bigint;
+    /** Token program owning the sell mint's accounts (classic SPL Token vs Token-2022). Defaults to the
+     * classic SPL Token program — pass `TOKEN_2022_PROGRAM_ID` explicitly for Token-2022 mints. */
+    sellTokenProgramId?: PublicKeyInitData;
+}
 /**
  * Solana counterpart to `QuoteAndPost`. It additionally exposes `solanaQuote` and `buildOrder`, because a
  * Solana order is a plain instruction: callers may want to bundle it with a wrap or a token delegation and
@@ -239,7 +248,14 @@ interface SolanaQuoteAndPost {
 declare class SolanaTradingSdk {
     private readonly options;
     constructor(options?: SolanaTradingSdkOptions);
+    /**
+     * Builds the SPL `approve` instruction that delegates `sellAmount` of `sellTokenAddress` to the
+     * settlement program, without sending it — see "Step 0" in the README for why this is required
+     * before an order on a given sell-token account can settle. Bundle it with `buildOrder`'s
+     * instruction in the same transaction the first time a wallet trades a given token.
+     */
+    approveCowProtocol(params: ApproveCowProtocolParams): TransactionInstruction;
     getQuote(params: SolanaQuoteParameters): Promise<SolanaQuoteAndPost>;
 }
 
-export { type CreateOrderInstructionParams, ENCODED_ORDER_INTENT_SIZE, JupiterAPI, type JupiterOrderRequest, type JupiterOrderResponse, ORDER_SEED, type SolanaOrderIntent, type SolanaQuote, type SolanaQuoteAndPost, type SolanaQuoteParameters, type SolanaSignAndSend, type SolanaSwapOrder, type SolanaSwapOrderQuote, SolanaTradingSdk, type SolanaTradingSdkOptions, buildCreateOrderInstruction, buildSolanaSwapOrder, encodeOrderIntent, findOrderPda, findSettlementStatePda, getSettlementSeed, getSolanaDelegateAuthority, getSolanaQuote, getSolanaSettlementProgramId, hashOrderIntent, postSolanaSwapOrderFromQuote, toHex, toOrderId };
+export { type ApproveCowProtocolParams, type CreateOrderInstructionParams, ENCODED_ORDER_INTENT_SIZE, JupiterAPI, type JupiterOrderRequest, type JupiterOrderResponse, ORDER_SEED, type SolanaOrderIntent, type SolanaQuote, type SolanaQuoteAndPost, type SolanaQuoteParameters, type SolanaSignAndSend, type SolanaSwapOrder, type SolanaSwapOrderQuote, SolanaTradingSdk, type SolanaTradingSdkOptions, buildCreateOrderInstruction, buildSolanaSwapOrder, encodeOrderIntent, findOrderPda, findSettlementStatePda, getSettlementSeed, getSolanaDelegateAuthority, getSolanaQuote, getSolanaSettlementProgramId, hashOrderIntent, postSolanaSwapOrderFromQuote, toHex, toOrderId };

package/dist/index.d.ts

@@ -29,16 +29,16 @@ declare class JupiterAPI {
 }
 
 /**
- * TS port of `cow-settlement-interface`'s `OrderIntent` (interface/src/data/intent.rs, v0.3.0).
+ * TS port of `cow-settlement-interface`'s `OrderIntent` (interface/src/data/intent.rs, v0.4.0).
  * Every field here has a Rust counterpart with the same name; keep them in sync if the settlement
  * program's wire format changes.
  */
 interface SolanaOrderIntent {
     owner: PublicKey;
-    buyTokenAccount: PublicKey;
-    buyMint: PublicKey;
     sellTokenAccount: PublicKey;
     sellMint: PublicKey;
+    buyTokenAccount: PublicKey;
+    buyMint: PublicKey;
     sellAmount: bigint;
     buyAmount: bigint;
     /** Unix timestamp seconds. */
@@ -73,7 +73,6 @@ declare function toOrderId(uid: Uint8Array): string;
 
 interface SolanaQuoteParameters {
     ownerAddress: PublicKeyInitData;
-    receiverAddress: PublicKeyInitData;
     sellTokenAddress: PublicKeyInitData;
     sellTokenDecimals: number;
     buyTokenAddress: PublicKeyInitData;
@@ -81,6 +80,7 @@ interface SolanaQuoteParameters {
     /** Sell-side amount for a SELL order, buy-side amount for a BUY order — same convention as Jupiter's `amount`. */
     amount: bigint;
     kind: OrderKind;
+    receiverAddress?: PublicKeyInitData;
     partiallyFillable?: boolean;
     /** Order lifetime from now, in seconds. Defaults to 30 minutes. */
     validForSeconds?: number;
@@ -217,6 +217,15 @@ declare function postSolanaSwapOrderFromQuote(quote: SolanaSwapOrderQuote, signA
 interface SolanaTradingSdkOptions {
     env?: CowEnv;
 }
+interface ApproveCowProtocolParams {
+    ownerAddress: PublicKeyInitData;
+    sellTokenAddress: PublicKeyInitData;
+    /** Amount to approve, at least the order's `sellAmount`. */
+    approveAmount: bigint;
+    /** Token program owning the sell mint's accounts (classic SPL Token vs Token-2022). Defaults to the
+     * classic SPL Token program — pass `TOKEN_2022_PROGRAM_ID` explicitly for Token-2022 mints. */
+    sellTokenProgramId?: PublicKeyInitData;
+}
 /**
  * Solana counterpart to `QuoteAndPost`. It additionally exposes `solanaQuote` and `buildOrder`, because a
  * Solana order is a plain instruction: callers may want to bundle it with a wrap or a token delegation and
@@ -239,7 +248,14 @@ interface SolanaQuoteAndPost {
 declare class SolanaTradingSdk {
     private readonly options;
     constructor(options?: SolanaTradingSdkOptions);
+    /**
+     * Builds the SPL `approve` instruction that delegates `sellAmount` of `sellTokenAddress` to the
+     * settlement program, without sending it — see "Step 0" in the README for why this is required
+     * before an order on a given sell-token account can settle. Bundle it with `buildOrder`'s
+     * instruction in the same transaction the first time a wallet trades a given token.
+     */
+    approveCowProtocol(params: ApproveCowProtocolParams): TransactionInstruction;
     getQuote(params: SolanaQuoteParameters): Promise<SolanaQuoteAndPost>;
 }
 
-export { type CreateOrderInstructionParams, ENCODED_ORDER_INTENT_SIZE, JupiterAPI, type JupiterOrderRequest, type JupiterOrderResponse, ORDER_SEED, type SolanaOrderIntent, type SolanaQuote, type SolanaQuoteAndPost, type SolanaQuoteParameters, type SolanaSignAndSend, type SolanaSwapOrder, type SolanaSwapOrderQuote, SolanaTradingSdk, type SolanaTradingSdkOptions, buildCreateOrderInstruction, buildSolanaSwapOrder, encodeOrderIntent, findOrderPda, findSettlementStatePda, getSettlementSeed, getSolanaDelegateAuthority, getSolanaQuote, getSolanaSettlementProgramId, hashOrderIntent, postSolanaSwapOrderFromQuote, toHex, toOrderId };
+export { type ApproveCowProtocolParams, type CreateOrderInstructionParams, ENCODED_ORDER_INTENT_SIZE, JupiterAPI, type JupiterOrderRequest, type JupiterOrderResponse, ORDER_SEED, type SolanaOrderIntent, type SolanaQuote, type SolanaQuoteAndPost, type SolanaQuoteParameters, type SolanaSignAndSend, type SolanaSwapOrder, type SolanaSwapOrderQuote, SolanaTradingSdk, type SolanaTradingSdkOptions, buildCreateOrderInstruction, buildSolanaSwapOrder, encodeOrderIntent, findOrderPda, findSettlementStatePda, getSettlementSeed, getSolanaDelegateAuthority, getSolanaQuote, getSolanaSettlementProgramId, hashOrderIntent, postSolanaSwapOrderFromQuote, toHex, toOrderId };

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -66,10 +76,10 @@ function encodeOrderIntent(intent) {
     offset += 8;
   };
   writePubkey(intent.owner);
-  writePubkey(intent.buyTokenAccount);
-  writePubkey(intent.buyMint);
   writePubkey(intent.sellTokenAccount);
   writePubkey(intent.sellMint);
+  writePubkey(intent.buyTokenAccount);
+  writePubkey(intent.buyMint);
   writeU64LE(intent.sellAmount);
   writeU64LE(intent.buyAmount);
   view.setUint32(offset, intent.validTo, true);
@@ -228,7 +238,7 @@ async function getSolanaQuote(params, options = {}) {
   const {
     slippageBps: slippageBpsOverride,
     ownerAddress,
-    receiverAddress,
+    receiverAddress = ownerAddress,
     sellTokenDecimals,
     buyTokenDecimals,
     amount,
@@ -352,27 +362,49 @@ async function getSolanaQuote(params, options = {}) {
 var import_sdk_order_book3 = require("@cowprotocol/sdk-order-book");
 var import_spl_token2 = require("@solana/spl-token");
 var import_web36 = require("@solana/web3.js");
+
+// src/appData.ts
+var import_sdk_app_data = require("@cowprotocol/sdk-app-data");
+var import_deepmerge = __toESM(require("deepmerge"));
+async function mergeAppData(doc, override) {
+  const clearedDoc = {
+    ...doc,
+    metadata: {
+      ...doc.metadata,
+      ...override.metadata?.hooks ? { hooks: {} } : {},
+      ...override.metadata?.userConsents ? { userConsents: [] } : {}
+    }
+  };
+  const merged = (0, import_deepmerge.default)(clearedDoc, override);
+  const fullAppData = await (0, import_sdk_app_data.stringifyDeterministic)(merged);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(fullAppData));
+  return new Uint8Array(digest);
+}
+
+// src/buildSwapOrder.ts
 async function buildSolanaSwapOrder({ quoteResults, solanaQuote }, advancedSettings) {
-  const intent = { ...solanaQuote.intent };
-  let uid = solanaQuote.uid;
-  let orderPda = solanaQuote.orderPda;
-  if (advancedSettings?.quoteRequest) {
-    const { validTo, receiver } = advancedSettings.quoteRequest;
-    if (receiver) {
-      intent.buyTokenAccount = (0, import_spl_token2.getAssociatedTokenAddressSync)(
-        intent.buyMint,
+  const { validTo, receiver } = advancedSettings?.quoteRequest ?? {};
+  const overrides = {
+    ...receiver && {
+      buyTokenAccount: (0, import_spl_token2.getAssociatedTokenAddressSync)(
+        solanaQuote.intent.buyMint,
         new import_web36.PublicKey(receiver),
         false,
         solanaQuote.buyTokenProgramId
-      );
-    }
-    if (validTo)
-      intent.validTo = validTo;
-    if (receiver || validTo) {
-      const intentBytes = encodeOrderIntent(intent);
-      uid = await hashOrderIntent(intentBytes);
-      [orderPda] = findOrderPda(solanaQuote.programId, uid);
+      )
+    },
+    ...validTo && { validTo },
+    ...advancedSettings?.appData && {
+      appData: await mergeAppData(quoteResults.appDataInfo.doc ?? {}, advancedSettings.appData)
     }
+  };
+  const intent = { ...solanaQuote.intent, ...overrides };
+  let uid = solanaQuote.uid;
+  let orderPda = solanaQuote.orderPda;
+  if (Object.keys(overrides).length > 0) {
+    const intentBytes = encodeOrderIntent(intent);
+    uid = await hashOrderIntent(intentBytes);
+    [orderPda] = findOrderPda(solanaQuote.programId, uid);
   }
   const instruction = buildCreateOrderInstruction({
     programId: solanaQuote.programId,
@@ -408,10 +440,26 @@ async function postSolanaSwapOrderFromQuote(quote, signAndSend, advancedSettings
 }
 
 // src/solanaTradingSdk.ts
+var import_spl_token3 = require("@solana/spl-token");
+var import_web37 = require("@solana/web3.js");
 var SolanaTradingSdk = class {
   constructor(options = {}) {
     this.options = options;
   }
+  /**
+   * Builds the SPL `approve` instruction that delegates `sellAmount` of `sellTokenAddress` to the
+   * settlement program, without sending it — see "Step 0" in the README for why this is required
+   * before an order on a given sell-token account can settle. Bundle it with `buildOrder`'s
+   * instruction in the same transaction the first time a wallet trades a given token.
+   */
+  approveCowProtocol(params) {
+    const owner = new import_web37.PublicKey(params.ownerAddress);
+    const sellMint = new import_web37.PublicKey(params.sellTokenAddress);
+    const tokenProgramId = params.sellTokenProgramId ? new import_web37.PublicKey(params.sellTokenProgramId) : void 0;
+    const sellTokenAccount = (0, import_spl_token3.getAssociatedTokenAddressSync)(sellMint, owner, false, tokenProgramId);
+    const delegate = getSolanaDelegateAuthority(this.options.env);
+    return (0, import_spl_token3.createApproveInstruction)(sellTokenAccount, delegate, owner, params.approveAmount, void 0, tokenProgramId);
+  }
   async getQuote(params) {
     const quote = await getSolanaQuote(params, { env: this.options.env });
     return {

package/dist/index.mjs

@@ -24,10 +24,10 @@ function encodeOrderIntent(intent) {
     offset += 8;
   };
   writePubkey(intent.owner);
-  writePubkey(intent.buyTokenAccount);
-  writePubkey(intent.buyMint);
   writePubkey(intent.sellTokenAccount);
   writePubkey(intent.sellMint);
+  writePubkey(intent.buyTokenAccount);
+  writePubkey(intent.buyMint);
   writeU64LE(intent.sellAmount);
   writeU64LE(intent.buyAmount);
   view.setUint32(offset, intent.validTo, true);
@@ -189,7 +189,7 @@ async function getSolanaQuote(params, options = {}) {
   const {
     slippageBps: slippageBpsOverride,
     ownerAddress,
-    receiverAddress,
+    receiverAddress = ownerAddress,
     sellTokenDecimals,
     buyTokenDecimals,
     amount,
@@ -313,27 +313,49 @@ async function getSolanaQuote(params, options = {}) {
 import { SigningScheme } from "@cowprotocol/sdk-order-book";
 import { getAssociatedTokenAddressSync as getAssociatedTokenAddressSync2 } from "@solana/spl-token";
 import { PublicKey as PublicKey6 } from "@solana/web3.js";
+
+// src/appData.ts
+import { stringifyDeterministic } from "@cowprotocol/sdk-app-data";
+import deepmerge from "deepmerge";
+async function mergeAppData(doc, override) {
+  const clearedDoc = {
+    ...doc,
+    metadata: {
+      ...doc.metadata,
+      ...override.metadata?.hooks ? { hooks: {} } : {},
+      ...override.metadata?.userConsents ? { userConsents: [] } : {}
+    }
+  };
+  const merged = deepmerge(clearedDoc, override);
+  const fullAppData = await stringifyDeterministic(merged);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(fullAppData));
+  return new Uint8Array(digest);
+}
+
+// src/buildSwapOrder.ts
 async function buildSolanaSwapOrder({ quoteResults, solanaQuote }, advancedSettings) {
-  const intent = { ...solanaQuote.intent };
-  let uid = solanaQuote.uid;
-  let orderPda = solanaQuote.orderPda;
-  if (advancedSettings?.quoteRequest) {
-    const { validTo, receiver } = advancedSettings.quoteRequest;
-    if (receiver) {
-      intent.buyTokenAccount = getAssociatedTokenAddressSync2(
-        intent.buyMint,
+  const { validTo, receiver } = advancedSettings?.quoteRequest ?? {};
+  const overrides = {
+    ...receiver && {
+      buyTokenAccount: getAssociatedTokenAddressSync2(
+        solanaQuote.intent.buyMint,
         new PublicKey6(receiver),
         false,
         solanaQuote.buyTokenProgramId
-      );
-    }
-    if (validTo)
-      intent.validTo = validTo;
-    if (receiver || validTo) {
-      const intentBytes = encodeOrderIntent(intent);
-      uid = await hashOrderIntent(intentBytes);
-      [orderPda] = findOrderPda(solanaQuote.programId, uid);
+      )
+    },
+    ...validTo && { validTo },
+    ...advancedSettings?.appData && {
+      appData: await mergeAppData(quoteResults.appDataInfo.doc ?? {}, advancedSettings.appData)
     }
+  };
+  const intent = { ...solanaQuote.intent, ...overrides };
+  let uid = solanaQuote.uid;
+  let orderPda = solanaQuote.orderPda;
+  if (Object.keys(overrides).length > 0) {
+    const intentBytes = encodeOrderIntent(intent);
+    uid = await hashOrderIntent(intentBytes);
+    [orderPda] = findOrderPda(solanaQuote.programId, uid);
   }
   const instruction = buildCreateOrderInstruction({
     programId: solanaQuote.programId,
@@ -369,10 +391,26 @@ async function postSolanaSwapOrderFromQuote(quote, signAndSend, advancedSettings
 }
 
 // src/solanaTradingSdk.ts
+import { createApproveInstruction, getAssociatedTokenAddressSync as getAssociatedTokenAddressSync3 } from "@solana/spl-token";
+import { PublicKey as PublicKey7 } from "@solana/web3.js";
 var SolanaTradingSdk = class {
   constructor(options = {}) {
     this.options = options;
   }
+  /**
+   * Builds the SPL `approve` instruction that delegates `sellAmount` of `sellTokenAddress` to the
+   * settlement program, without sending it — see "Step 0" in the README for why this is required
+   * before an order on a given sell-token account can settle. Bundle it with `buildOrder`'s
+   * instruction in the same transaction the first time a wallet trades a given token.
+   */
+  approveCowProtocol(params) {
+    const owner = new PublicKey7(params.ownerAddress);
+    const sellMint = new PublicKey7(params.sellTokenAddress);
+    const tokenProgramId = params.sellTokenProgramId ? new PublicKey7(params.sellTokenProgramId) : void 0;
+    const sellTokenAccount = getAssociatedTokenAddressSync3(sellMint, owner, false, tokenProgramId);
+    const delegate = getSolanaDelegateAuthority(this.options.env);
+    return createApproveInstruction(sellTokenAccount, delegate, owner, params.approveAmount, void 0, tokenProgramId);
+  }
   async getQuote(params) {
     const quote = await getSolanaQuote(params, { env: this.options.env });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cowprotocol/sdk-trading-solana",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CowProtocol Solana trading: Jupiter-sourced quotes and on-chain CreateOrder posting against the Solana settlement program",
   "repository": {
     "type": "git",
@@ -37,11 +37,13 @@
     "ts-jest": "^29.0.0"
   },
   "dependencies": {
-    "@cowprotocol/sdk-config": "2.6.0",
-    "@cowprotocol/sdk-order-book": "4.0.5",
-    "@cowprotocol/sdk-trading": "2.5.0",
+    "@cowprotocol/sdk-app-data": "6.0.5",
+    "@cowprotocol/sdk-config": "2.7.0",
+    "@cowprotocol/sdk-order-book": "4.0.6",
+    "@cowprotocol/sdk-trading": "2.6.0",
     "@solana/spl-token": "0.4.14",
-    "@solana/web3.js": "1.98.4"
+    "@solana/web3.js": "1.98.4",
+    "deepmerge": "^4.3.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",