\n\n# Solana Trading SDK\n\n## Test coverage\n\n| Statements | Branches | Functions | Lines |\n| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n|  |  |  |  |\n\n`@cowprotocol/sdk-trading-solana` is CoW Protocol's Solana settlement client: it turns a quote\ninto an on-chain `CreateOrder` instruction against the CoW Protocol Solana\nsettlement program.\n\n**Experimental.** The settlement program (`cow-settlement-interface` / `solana-programs`) is a young,\nactively evolving deployment — expect breaking changes to the intent wire format, PDA seeds and this\npackage's API across minor versions. The currently deployed program id is exported as\n[`SOLANA_SETTLEMENT_PROGRAM_ID`](https://github.com/cowprotocol/cow-sdk/blob/main/packages/config/src/chains/const/contracts.ts)\nfrom `@cowprotocol/sdk-config` — see it on\n[Solana Explorer](https://explorer.solana.com/address/FYp8R5K4B3B1Kfr7QuWzMz4TwoT7wptjYtxgCrY5sRXb).\n\n```\nnpm install @cowprotocol/sdk-trading-solana\n```\n\nA runnable end-to-end example lives in [`examples/nodejs/solana`](../../examples/nodejs/solana).\n\n## Making a trade\n\n### Step 0 — approve the settlement program as SPL delegate\n\nThe settlement program moves funds out of the seller's token account via a CPI, which SPL Token\nonly allows for an approved `delegate`. Before any order on a given sell-token account can settle,\nthat account's owner must approve the settlement **state PDA** (not the program id itself) as\ndelegate, for at least the amount being sold. `approveCowProtocol` builds that instruction without\nsending it, deriving the sell-token account and delegate for you:\n\n```ts\nconst sdk = new SolanaTradingSdk() // same env as the SDK instance used for the quote below\n\nconst approveInstruction = sdk.approveCowProtocol({\n ownerAddress: owner,\n sellTokenAddress: sellMint,\n approveAmount, // at least the order's sellAmount\n})\n```\n\nThis approval is **not one-time**: like any SPL delegate, each settled order decrements the\ndelegate's remaining allowance by the amount actually transferred, so approving once for exactly one\norder's `sellAmount` leaves nothing for the next one. Check the sell-token account's current\n`delegate`/`delegatedAmount` before building an order, and reapprove (topping the allowance back up)\nwhenever it's insufficient — approving a new amount replaces the previous allowance rather than\nadding to it. Separately, because the delegate PDA is derived from the settlement program's\nmajor/minor version (`getSettlementSeed`), a program upgrade that bumps that version changes the\ndelegate address entirely, requiring a fresh approval regardless of remaining allowance. This step\ncan be sent as its own transaction ahead of time, or bundled with the `CreateOrder` instruction in\nthe same transaction — see [Step 2](#step-2--create-the-order) below.\n\n### Step 1 — get a quote\n\nQuoting needs no signer, just the addresses and amount:\n\n```ts\nimport { OrderKind } from '@cowprotocol/sdk-order-book'\nimport { SolanaTradingSdk } from '@cowprotocol/sdk-trading-solana'\n\nconst sdk = new SolanaTradingSdk() // pass `{ env: 'staging' }` to target staging\n\nconst { quoteResults, solanaQuote, buildOrder, postSwapOrderFromQuote } = await sdk.getQuote({\n ownerAddress, // the seller's wallet — signs the CreateOrder transaction\n sellTokenAddress,\n sellTokenDecimals,\n buyTokenAddress,\n buyTokenDecimals,\n amount, // bigint — sell-side amount for a SELL order, buy-side amount for a BUY order\n kind: OrderKind.SELL,\n})\n```\n\n- `quoteResults` mirrors the EVM SDK's [`QuoteResults`](../trading/src/types.ts) (trade parameters, suggested slippage, amounts\n and costs) so UI code can share formatting logic across chains.\n- `solanaQuote` is the Solana-specific quote: the order **intent** that was built from the quote\n response, its encoded bytes, its `uid`, the order PDA it will live at, and the raw upstream quote\n (real amounts/slippage) the intent was derived from.\n- Native SOL is accepted as the sentinel address; it's substituted with wrapped SOL (WSOL) before\n quoting and building the intent, since Solana has no native-token mint to reference on-chain.\n- Passing `sellTokenProgramId` / `buyTokenProgramId` (e.g. `TOKEN_2022_PROGRAM_ID`) is required for\n Token-2022 mints, since the associated token account address differs by program.\n\n### Step 2 — create the order\n\nTwo ways to get the order on-chain, depending on whether you need to bundle it with other\ninstructions:\n\n**Let the SDK submit it as its own transaction** — pass a signing/sending function at the point of\nsigning:\n\n```ts\nconst result = await postSwapOrderFromQuote(signAndSend)\n// result.orderId, result.txHash / result.signature\n```\n\n`signAndSend` has the shape `(instruction: TransactionInstruction) => Promise<{ signature: string }>`\n— build, sign and send the transaction however fits your app (a `Connection` + `Keypair`, a wallet\nadapter, a Squads/Safe-style multisig flow, etc).\n\n**Bundle the order with your own instructions** — a Solana order is created by a single instruction,\nso it can share one transaction with, say, the Step 0 delegate approval, a native-SOL wrap, or\nanything else. `buildOrder` returns that instruction without sending it:\n\n```ts\nconst { instruction, orderId, orderPda, uid } = await buildOrder()\n\nawait sendMyTransaction([approveInstruction, instruction])\n```\n\nThis is the recommended path whenever the sell-token account's delegate allowance needs\ntopping up for this trade, since it lets the delegate approval and the order creation land\natomically in one transaction.\n\nBoth paths accept the same optional `advancedSettings` (currently `quoteRequest.receiver` and\n`quoteRequest.validTo`) and apply them identically — overriding `receiver` or `validTo` re-derives\nthe order's `uid` and PDA so they still match the intent actually being created:\n\n```ts\nawait postSwapOrderFromQuote(signAndSend, { quoteRequest: { receiver: otherWallet.toBase58() } })\n```\n\n### Step 3 — read back the result\n\nBoth `postSwapOrderFromQuote` and `buildOrder` return an `orderId` — the `uid` as the `0x`-prefixed\nhex string the CoW order-book API uses for EVM orders too, so it can be handled uniformly by shared\nUI/state code. `solanaQuote.orderPda` is the on-chain account the order lives at once the\n`CreateOrder` instruction lands.\n\n## Cancelling an order\n\n`cancelOrder` builds the `CancelOrder` instruction for an order at a given PDA, without sending it.\nCancelling is idempotent — cancelling an already-cancelled order does nothing:\n\n```ts\nconst sdk = new SolanaTradingSdk()\n\nconst cancelInstruction = sdk.cancelOrder({\n ownerAddress: owner, // must match the order's intent owner; signs the transaction\n orderPda, // from buildOrder / buildLimitOrder / findOrderPda\n})\n\nawait sendMyTransaction([cancelInstruction])\n```\n\nThis is the cheaper, common form: it requires the order to already be on-chain — its data is recovered\nfrom `orderPda` and only its `cancelled` flag is set. If the order might not exist on-chain yet (e.g.\ncancelling before its `CreateOrder` instruction has landed), pass `intent` too; the instruction then\ncreates the order already cancelled instead of failing, funding its rent from `createdByAddress`\n(defaults to `ownerAddress`), which must sign in that case:\n\n```ts\nsdk.cancelOrder({ ownerAddress: owner, orderPda, intent, createdByAddress: sponsor })\n```\n\n### Cancelling several orders in one transaction\n\nThe settlement program has no dedicated batch-cancel instruction, but a Solana transaction holds\nmultiple instructions natively, so cancelling several orders atomically just means bundling their\nindividual `CancelOrder` instructions into one transaction. `cancelOrders` builds one instruction per\nentry — accounts shared across entries (`owner`, `createdBy`, the System Program) get deduplicated when\nthe transaction is compiled, so batches for a single owner are cheap:\n\n```ts\nconst cancelInstructions = sdk.cancelOrders([\n { ownerAddress: owner, orderPda: orderPdaA },\n { ownerAddress: owner, orderPda: orderPdaB },\n])\n\nawait sendMyTransaction(cancelInstructions)\n```\n\nA legacy transaction is capped at 1232 bytes total, so very large batches may need to be split across\nmultiple transactions.\n\n## Limit orders\n\n`getQuote`'s `buildOrder` always signs the market-quoted amount (± slippage) — correct for a swap,\nbut wrong for a limit order that should rest on-chain at a price the caller chooses, not a snapshot\nof the market at signing time. `buildLimitOrder` builds that same kind of `CreateOrder` instruction\ndirectly from the caller's own `sellAmount`/`buyAmount`, without calling `getQuote` at all:\n\n```ts\nimport { OrderKind } from '@cowprotocol/sdk-order-book'\nimport { SolanaTradingSdk } from '@cowprotocol/sdk-trading-solana'\n\nconst sdk = new SolanaTradingSdk()\n\nconst { instruction, orderId, orderPda, uid } = await sdk.buildLimitOrder({\n ownerAddress,\n sellTokenAddress,\n buyTokenAddress,\n sellAmount, // bigint — the caller's own price, not a quoted amount\n buyAmount,\n kind: OrderKind.SELL,\n validTo, // unix timestamp, seconds — when the order expires\n partiallyFillable,\n appData, // exactly 32 bytes, used as-is — see below\n})\n\nawait sendMyTransaction([approveInstruction, instruction])\n```\n\n- Takes the same token-account/mint resolution as `getQuote` (native SOL → WSOL substitution,\n `receiverAddress` defaulting to `ownerAddress`, `sellTokenProgramId`/`buyTokenProgramId` for\n Token-2022 mints), but needs no upstream quote and no signer to build.\n- `appData` is used exactly as given — no hashing, no doc, no merging against a quoted value.\n Solana has no agreed `appData` convention yet.\n `hashAppDataDoc` is available if you want to derive them from an app-data doc yourself.\n- Still requires [Step 0](#step-0--approve-the-settlement-program-as-spl-delegate) before the order\n can settle, and the returned `instruction` can be bundled with that approval the same way\n `buildOrder`'s can.\n- Uses the `env` the `SolanaTradingSdk` instance was constructed with, unless overridden per call via\n `env` in the params.\n\n## The intent model\n\nEvery Solana order is, at its core, a `SolanaOrderIntent` — a fixed-layout struct that is the direct\nTypeScript counterpart of `OrderIntent` in `cow-settlement-interface` (`interface/src/data/intent.rs`).\nUnlike an EVM order (an EIP-712 message the owner signs off-chain and the order-book stores), a\nSolana intent is never signed as data — it's written directly into an on-chain account by an\ninstruction the owner's wallet signs.\n\n```ts\ninterface SolanaOrderIntent {\n owner: PublicKey // signs the CreateOrder transaction\n buyTokenAccount: PublicKey // receives the buy-side proceeds — implicitly encodes the receiver\n buyMint: PublicKey\n sellTokenAccount: PublicKey // funds pulled from here — must be owned by `owner`; implicitly encodes the spender\n sellMint: PublicKey\n sellAmount: bigint\n buyAmount: bigint\n validTo: number // unix timestamp, seconds\n kind: OrderKind // SELL | BUY\n partiallyFillable: boolean\n createdOnChain: boolean // must be true — see \"Authentication\" below\n appData: Uint8Array // exactly 32 bytes, opaque to the settlement program; no convention defined yet, sent as zeroes\n}\n```\n\n### Encoding\n\n`encodeOrderIntent` packs the intent into the exact 213-byte (`ENCODED_ORDER_INTENT_SIZE`) little-endian\nlayout the settlement program reads (`EncodedOrderIntent::from(&OrderIntent)`):\n\n| Bytes | Field |\n| ----- | --------------------------------- |\n| 32 | `owner` |\n| 32 | `buyTokenAccount` |\n| 32 | `buyMint` |\n| 32 | `sellTokenAccount` |\n| 32 | `sellMint` |\n| 8 | `sellAmount` (u64 LE) |\n| 8 | `buyAmount` (u64 LE) |\n| 4 | `validTo` (u32 LE) |\n| 1 | flags (bit 0 `createdOnChain`, bit 1 `kind === BUY`, bit 2 `partiallyFillable`) |\n| 32 | `appData` |\n\n### Identity: uid and the order PDA\n\n`hashOrderIntent` takes the SHA-256 digest of the encoded intent bytes. That 32-byte digest is both:\n\n- the order's **uid** (`toOrderId` formats it as the `0x`-prefixed id used across the SDK), and\n- the middle seed of the order's **program-derived address** (`findOrderPda`), alongside a\n version-embedded settlement seed (`getSettlementSeed`, `\"settlement v\" + version`, padded to a\n fixed width so seeds from different versions can't collide) and a trailing `\"order\"` seed.\n\nBecause the uid is a hash of the intent's content, any change to the intent — including an\n`advancedSettings` override to `receiver` or `validTo` — changes the uid and therefore the PDA the\norder will be created at. `buildSolanaSwapOrder` re-derives both whenever `advancedSettings`\nactually changes the intent, so the instruction it returns always targets the PDA matching the\nintent it encodes.\n\n### The `CreateOrder` instruction\n\n`buildCreateOrderInstruction` builds the instruction that writes the intent on-chain, matching\n`CreateOrder::into::()`:\n\n- **data**: `[discriminator = 2, ...213 intent bytes]`\n- **accounts**: `owner` (readonly signer), `createdBy` (writable signer — funds the new order PDA's\n rent; may equal `owner`), `orderPda` (writable), the System Program\n\n### The `CancelOrder` instruction\n\n`buildCancelOrderInstruction` (used by `SolanaTradingSdk.cancelOrder`) builds the counterpart\ninstruction that cancels an order, matching `CancelOrder::into::()` — the `intent_bytes`\nfield on the wire is optional (`cow-settlement-interface` v0.4.1):\n\n- **data**: `[discriminator = 11]` alone to cancel an order already on-chain (its data is recovered\n from `orderPda`), or `[discriminator = 11, ...213 intent bytes]` to also create it already cancelled\n if `orderPda` doesn't exist yet\n- **accounts**: `owner` (readonly signer), `createdBy`, `orderPda` (writable), the System Program —\n `createdBy` is a writable signer only in the create-cancelled form, since only that form moves rent\n- Idempotent: cancelling an already-cancelled order does nothing\n\n### Authentication: why `createdOnChain` must be `true`\n\n`cow-settlement-interface` supports two ways an intent can be authenticated: created on-chain (the\nowner signs the `CreateOrder` transaction themselves) or via an off-chain Ed25519-presigned order\nthat anyone can submit on the owner's behalf. This SDK only implements the former —\n`encodeOrderIntent` always sets the on-chain flag, and the settlement program authenticates the\norder against the transaction's own signature rather than a separate signed payload. This is the\nSolana counterpart of an EVM `PRESIGN` order (`buildSolanaSwapOrder` reports\n`signingScheme: SigningScheme.PRESIGN` for exactly this reason) rather than an EIP-712 `EIP712` one.\n\n## Example app\n\n[`examples/nodejs/solana`](../../examples/nodejs/solana) is a runnable, end-to-end demo: it gets a\nquote, approves the settlement program's delegate, builds the `CreateOrder` instruction, bundles\nboth into one transaction and submits it. **It targets mainnet-beta by default and trades real\nfunds** — see that example's own README for setup, including how to point it at devnet instead.\n\n## Why Solana trading looks different from EVM trading\n\nOn EVM chains, `TradingSdk` gets a quote from the CoW order-book API, has the caller sign an\nEIP-712 typed order, and POSTs the signed order to the order-book, which later settles it. Solana\nhas neither an order-book API to post to nor an implicit global signer:\n\n- **Quotes don't come from the CoW order-book (yet).** `SolanaTradingSdk.getQuote` currently sources\n pricing and route discovery from an external quoting API, then builds a CoW Protocol order\n **intent** from the result. That API is used for quoting only — orders are never submitted through\n it, only ever created via the CoW settlement program. This is expected to move onto the CoW\n order-book API directly as Solana support matures.\n- **Orders are created entirely on-chain.** There is no signed order body to POST. Creating an order\n means submitting a single `CreateOrder` instruction that writes the order intent into a new\n program-derived account (the order PDA). The transaction signature that lands on-chain *is* the\n order's authentication.\n- **No bound signer.** The EVM SDK gets its signer from a global adapter set once at app startup.\n This package has no such adapter: quoting needs no signer at all, and a signing/sending function\n (`SolanaSignAndSend`) is passed only at the point of actually submitting a transaction. That also\n means a quote can be turned into a raw `TransactionInstruction` (via `buildOrder`) without ever\n involving a signer, so it can be composed into a larger transaction built and sent by the caller.\n","readmeFilename":""}
![\"CoW](\"https://github.com/cowprotocol/cow-sdk/raw/main/docs/images/CoW.png\")
\n