@gala-chain/launchpad-sdk 8.1.0 → 9.0.0-rc.0

package/CHANGELOG.md

@@ -1,5 +1,367 @@
 # Changelog
 
+## 9.0.0-rc.0
+
+launchpad-sdk is launchpad-only. Everything that speaks to the GalaChain gateway generically is
+`@gala-chain/gala-core-sdk`'s (a peer dependency: install it beside launchpad-sdk); everything that
+speaks to the swap backend (dex-backend) is `@gala-chain/gswap-sdk`'s, and launchpad-sdk no longer
+depends on it in any way. **[MIGRATING-TO-9.0.md](./MIGRATING-TO-9.0.md)** lists every export and
+`LaunchpadSDK` member 8.1.0 had that 9.0.0 does not, with its new home; it is generated from the
+built declarations of both versions (`pnpm docs:migration`).
+
+### BREAKING CHANGES (9.0 cut)
+
+- **The `Sign` header goes to the launchpad backend only.** The clients for the GalaChain gateway,
+  dex-api (referrals, bridgeable and wrappable token lists), the swap backend (prices) and the
+  bundler no longer send it: none of those hosts reads it (the gateway's own signature is in each
+  write's body; dex-api reads `x-wallet-address`), and every header cost a wallet signature per
+  request, a prompt for browser wallets. The clients keep the wallet identity (`getAddress`,
+  `signTypedData`) services read from them. `HttpClient` takes `{ signRequests }` as its third
+  constructor argument (default true: the launchpad backend client). Gateway read goldens
+  (`gateway-reads`, `token-discovery`) lost exactly their recorded `Sign` header and nothing else;
+  `tests/http-client-sign-header.test.ts` pins both behaviours.
+- **No DEX at all, not even as a devDependency.** The 46 DEX demos and their npm scripts (`demo:dex*`,
+  `demo:liquidity*`, `demo:fees*`, the pool watchers, `test:demos:dex`, `test:demos:fees`) moved to
+  `packages/gswap-sdk/examples/demos` (on gswap-sdk's own client, type-checked by its
+  `check:examples`), and the stage live test's DEX checks to gswap-sdk's live test.
+  `tests/product-boundary.test.ts` scans `src`, `tests`, `examples` and `scripts` with the TypeScript
+  scanner, refuses gswap-sdk in every dependency field and resolves it from the package with plain
+  Node (MODULE_NOT_FOUND); the CI dist check refuses it in every bundle.
+- **Prices: launchpad tokens only.** Of the two swap-backend price readers launchpad-sdk had, only the
+  launchpad-token one stays: `fetchTokenPrice({ tokenName })` (the bonding-curve price, or the
+  token's swap-backend price once it graduated; GALA's USD price and a graduated token's price are
+  read with a thin `GET /market/price` documented as launchpad-backend-adjacent). REMOVED, as
+  generic swap-backend reads that gswap-sdk's `market` already makes:
+  `fetchTokenPrice({ tokenId })` (a `tokenId` is now refused with a `ValidationError` before
+  anything is sent) and its 400/404 "launchpad fallback" (the recorded golden vector shows it never
+  fired: the 404 was wrapped before the check), `fetchGalaPrice()`, `fetchPriceHistory()`,
+  `fetchAllPriceHistory()` and their types (`FetchPriceHistoryOptions`, `PriceHistoryResult`,
+  `PriceSnapshot`, `PriceSortOrder`). Use `gSwap.market.getPrice(tokenId)` and
+  `gSwap.market.getPriceSeries(await sdk.resolveTokenClassKey(name), timeframe)`.
+  Decision and evidence (callers grepped in mcp-server, the apps, examples and docs): the only
+  callers of the removed reads were the MCP price tools, the examples and the docs. The MCP tools
+  (`gala_launchpad_fetch_token_spot_price` with `tokenId`, `..._fetch_gala_spot_price`,
+  `..._fetch_price_history`, `..._fetch_all_price_history`) keep their names, inputs and outputs on
+  the MCP server's own GSwap client, and replay the 13 recorded 8.1 vectors of these reads (same
+  endpoint and query, same outputs). What differs on the wire: no launchpad `Sign` header on these
+  public reads, the `$` of a class key sent as `%24`, and a backend failure's inner text (gswap-sdk's).
+- **Dependencies are the source's import graph** (`tests/dependency-graph.test.ts`): `@gala-chain/api`,
+  `axios`, `bignumber.js`, `ethers`, `socket.io-client`, `uuid`, `web-file-polyfill`; peers
+  `@gala-chain/gala-core-sdk` (`>=1.0.0-rc.3 <2`), `zod` (now `^4.3.6`: the peer said `^3` while the
+  schemas are zod 4, and it is no longer also a dependency) and the shared libraries. No longer
+  dependencies: `@solana/web3.js`, `@solana/spl-token`, `dotenv`, `@modelcontextprotocol/sdk` (and,
+  since the bridge move, `bs58` and `json-stringify-deterministic`).
+- **The bridge loads Solana only when used.** The bridge, balance-on-chain, token-list and wrap methods
+  load `@gala-chain/gala-core-sdk/bridge` (the one core entry that loads `ethers`,
+  `@solana/web3.js` and `@solana/spl-token`, core's optional peers) with `import()` at their first
+  call: an app that never bridges never loads Solana and need not install it; an app that bridges
+  installs those peers (a missing one is a `ConfigurationError` naming them). The CommonJS bundles
+  `require` it and the UMD bundle requires it or takes the `GalaCoreSDKBridge` global, so there is
+  one core copy in every build. A bridge or wrap call made with one wallet is refused
+  (`ConfigurationError`, nothing sent) if `setWallet` / `setWalletProvider` runs while `/bridge`
+  loads, rather than running as the next wallet. `getSupportedBridgeTokens()` is `async`.
+- **The public surface re-exports nothing** (`tests/public-surface.test.ts` pins both entries' export
+  lists and fails on any export declared outside `src/`). Removed from the main and `/native`
+  entries: `generateEIP712Types` and `GalaChainSigner` (core's), the duplicate EIP-712 types
+  `EIP712Types`, `EIP712TypeField`, `EIP712Domain` (core's `EIP712Types`, `EIP712DomainValue`),
+  `HttpRequestor` (the bundler transport takes core's `HttpRequestor` type), `GALA_TOKEN_CLASS_KEY`
+  (core's), `generateUniqueKey` (core's `createUniqueKey`), and the demo `.env` loaders `getEnv`,
+  `getEnvOrThrow`, `loadEnvWithFallback`.
+
+### Fixes
+
+- `graduateToken` bought `calculateBuyAmountForGraduation`'s `amount` (the GALA cost of the
+  remaining tokens) as the exact-buy token quantity. It buys `remainingTokens`, with the GALA cost
+  as `expectedAmount` (the slippage cap).
+- `subscribeToTokenCreations`: an event field that is missing or not a string is its fallback
+  (`''`, `preBuyQuantity` `'0'`), never `undefined`; `isFinalized` is `true` only for `true`.
+- Demo tooling: `demo:run` ran every selection interactively and counted failed demos as
+  successes (booleans tested with `!= null`); the registry maps each demo's SDK methods, leaves
+  the tooling out (130 demos) and `demo:run:method` / `demo:run:endpoint` exist. 131 more boolean
+  `!= null` tests in the demos and tests (write demos ran their transfer, wrap and unwrap whatever
+  their `EXECUTE_*` flag said) are plain boolean tests, and `tests/constant-boolean-null-check.test.ts`
+  refuses the shape.
+
+### The `/bundle` signing schemes (unchanged bytes; for Andy)
+
+Two schemes post to the bundler's `/bundle`, and both have callers, so both stay:
+`sdk.launchpad.buyWithNative / buyExactToken / sellWithNative / sellExactToken / createSale`
+(`BundlerTransport`) signs EIP-712 typed data (`signTypedData`, the GalaChain domain; pinned by
+`tests/golden/bundler-typed-data.golden.json`): what the live launchpad frontend
+(launchpad-frontend-v3, `signTypedData` / `eth_signTypedData`) and the MCP trading tools send.
+`sdk.buy()` / `sdk.sell()` (`BundleService.buyToken / sellToken`) sign with the signer's
+`signObject` (native for a private key, personal-sign for a browser wallet): the native app calls
+these (`src/sdk/facades/trade.ts`), as do the examples. Retiring `BundleService`'s trade methods
+needs the native app moved to `sdk.launchpad.*` first (which changes the bytes it sends).
+
+### What moved to gala-core-sdk (the extraction steps, from the 8.1.0 baseline)
+
+The gateway token writes (transfer GALA, transfer a token, burn, lock, unlock) moved to
+`@gala-chain/gala-core-sdk` 1.0.0-rc.1 (`GatewayWrites`). `transferGala`, `transferToken`,
+`burnTokens`, `lockTokens` and `unlockTokens` keep their names, signatures, input checks, result
+shapes and error classes and delegate to it; their requests are byte-identical (golden vectors)
+and still go through the SDK's gateway `HttpClient` (the `Sign` header included).
+
+The gateway token READS moved to `@gala-chain/gala-core-sdk` 1.0.0-rc.2 (`GatewayReads`):
+`fetchGalaBalance`, `fetchTokenBalance` (tokenId and MUSIC/GMUSIC routes), `fetchTokenDetails`,
+`fetchTokenClassesWithSupply` and the NFT reads keep their names and signatures and delegate to it,
+through the same clients as before (balances and NFT reads through the gateway `HttpClient` with
+its `Sign` header, token classes through the unauthenticated gateway axios instance). The core peer
+range is now `>=1.0.0-rc.3 <2`.
+
+The wallet providers and the React hooks moved to `@gala-chain/gala-core-sdk` 1.0.0-rc.3
+(`/providers`, `/react`). `LaunchpadSDKConfig.walletProvider`, `setWalletProvider` and
+`SignatureAuth` take core's `WalletProvider`; a core `PrivateKeyProvider` still gives the SDK's
+services their key.
+
+The bridge moved to `@gala-chain/gala-core-sdk` 1.0.0-rc.3 (`/bridge`): `BridgeService`, the
+Ethereum and Solana strategies, `GalaConnectClient`, the bridgeable and wrappable token services
+(with their caches and the offset pagination), `WrapService`, the bridge constants and types, and
+`createSolanaWallet`. `src/bridge/` and those services are gone from launchpad-sdk; the SDK's
+bridge, balance, token-list and wrap methods build core's services (from the SDK's wallet, its
+native signer and its DEX API client) and keep their names. The bridge-out signed payloads are
+byte-identical (golden vectors, unchanged); every GalaConnect request, Ethereum and Solana
+transaction, token-list read and wrap request replays the recorded vectors, and
+`LaunchpadSDK.wrapToken` sends exactly the recorded wrap. `/native` is 337,915 bytes (was 403,450).
+
+#### Breaking (the moves)
+
+- **The bridge is gala-core-sdk's.** Every bridge export of the browser and node entries is
+  REMOVED; import it from `@gala-chain/gala-core-sdk/bridge` (same name unless listed):
+
+  | Was (launchpad-sdk) | Now (`@gala-chain/gala-core-sdk/bridge`) |
+  | --- | --- |
+  | `BaseBridgeStrategy`, `EthereumBridgeStrategy`, `SolanaBridgeStrategy`, `GalaConnectClient`, `BridgeStatusCode`, the constants (`CHAIN_IDS`, `GALACHAIN_CHANNELS`, `ETHEREUM_TOKENS_PROD` / `_STAGE`, `DEFAULT_SOLANA_TOKENS`, `ERC20_ABI`, `BRIDGE_CONTRACT_ABI`, ...), the EIP-712 constants, the token math (`toBaseUnits`, `fromBaseUnits`, `formatTokenAmount`, `compareAmounts`), `stripHexPrefix`, and every bridge, bridgeable-token and wrappable-token type | the same name |
+  | `BRIDGE_TOKEN_METADATA` | `STATIC_TOKEN_METADATA` |
+  | `BridgeRateLimiter` | `RateLimiter` |
+  | `DEFAULT_ETHEREUM_TOKENS` (deprecated alias) | `ETHEREUM_TOKENS_PROD` |
+  | `GalaConnectHttpError` | `GalaSDKError` with code `GALACONNECT_HTTP_ERROR` (`error.status`, `params.serverMessage`) |
+  | `createSolanaWallet`, `GeneratedSolanaWallet` | the same name (it was in the browser and node entries) |
+  | `WrapUnwrapStatus`, `WrapUnwrapStatusResult` | removed: a wrap resolves only once completed |
+
+  `BridgeService`, `BridgeableTokenService`, `WrappableTokenService` and `WrapService`, which
+  launchpad-sdk did not export, are exported there too.
+- **Bridge and wrap failures are typed `GalaSDKError`s** (`isGalaError(error, code)`), not
+  `ValidationError` / `NetworkError` / `TransactionError` / `GalaConnectHttpError` or a text:
+  `INVALID_BRIDGE_AMOUNT`, `INVALID_WALLET_ADDRESS`, `INVALID_TOKEN_REFERENCE`,
+  `UNSUPPORTED_BRIDGE_TOKEN`, `BRIDGE_NOT_CONFIGURED`, `INVALID_BRIDGE_OPTION`,
+  `INSUFFICIENT_BRIDGE_BALANCE`, `GALACONNECT_HTTP_ERROR`, `BRIDGE_REQUEST_REJECTED`,
+  `BRIDGE_RESPONSE_INVALID`, `BRIDGE_READ_RESPONSE_INVALID`, `BRIDGE_TOKEN_NOT_FOUND`,
+  `TOKEN_NOT_WRAPPABLE`, `INVALID_WRAP_DIRECTION`, `BRIDGE_CHAIN_READ_FAILED`, and, once something
+  may have moved (never repeat it), `BRIDGE_WRITE_OUTCOME_UNKNOWN`, `BRIDGE_OUT_OUTCOME_UNKNOWN`
+  (with the bridge request id and the `uniqueKey`), `BRIDGE_DEPOSIT_OUTCOME_UNKNOWN`,
+  `BRIDGE_STATUS_TIMEOUT`.
+- **`wrapToken` / `unwrapToken` throw instead of returning `success: false`**: `WrapUnwrapResult`
+  is the completed result (`success: true`, `transactionId` and `completedAt` always set; `error`
+  and `fee` removed). Their options have no `memo` (it was never sent). **`getWrapStatus` is
+  REMOVED** (it always answered "completed" for any id).
+- **`getBridgeStatus(hash)`** takes no chain hint (one GalaConnect read answers for either chain);
+  **`estimateBridgeFee`** takes no `amount` (the fee never depended on it).
+- Behaviour on the way: a GalaConnect write is sent again only after a 429 (a 5xx or a failure in
+  transit may have been applied: outcome unknown); an `eth|0x...` recipient is accepted; the
+  caller's own input (token id, amount, recipient, an unconfigured chain) is refused before any
+  read; a malformed RPC URL, contract, wallet address or program id option is refused when the
+  service is built.
+- `bs58` and `json-stringify-deterministic` are no longer dependencies (nor, with the 9.0 cut above,
+  `@solana/web3.js` and `@solana/spl-token`: core's `/bridge` loads them, at the first bridge
+  call). `LaunchpadSDK`'s own
+  declarations need no Node types (a consumer of it compiles with TypeScript 6 and 7 without
+  them); an app that imports `/bridge` types naming `@solana/web3.js` (e.g. `BridgeServiceConfig`)
+  needs Node's types, since `@solana/web3.js`'s declarations import `http` / `https`.
+
+- **`@gala-chain/launchpad-sdk/wallet` and `@gala-chain/launchpad-sdk/react` are REMOVED**, and so
+  are the wallet exports of the browser entry. Import from core instead (same names unless listed):
+
+  | Was (launchpad-sdk) | Now (gala-core-sdk) |
+  | --- | --- |
+  | `/wallet` and the browser entry: `PrivateKeyProvider`, `ExternalWalletProvider`, `GalaWalletProvider`, `detectWallets`, `getWalletByRdns`, `hasAnyWallet`, `isWalletAvailable`, `subscribeToWalletChanges`, `getInjectedEip1193Provider`, `KNOWN_WALLET_RDNS`, `createWalletProvider`, `createProviderFromEip1193`, `ensureConnected`, `getPrivateKeyIfAvailable`, `isPrivateKeyProvider`, `isExternalProvider`, `isEip1193Provider` and the types (`WalletProvider`, `Eip1193Provider`, `DetectedWallet`, ...) | `@gala-chain/gala-core-sdk/providers` |
+  | `WalletProviderError`, `WalletProviderErrorCode` | `GalaSDKError` from `@gala-chain/gala-core-sdk`, branched with `isGalaError(error, 'WALLET_CONNECTION_FAILED' \| 'WALLET_NOT_CONNECTED' \| 'SIGNING_FAILED' \| ...)` |
+  | `createProviderFromWallet(wallet)`, `walletToProvider(wallet)` | `PrivateKeyProvider.fromWallet(wallet)` |
+  | `providerToWallet(provider)` | `isPrivateKeyProvider(p) ? new Wallet(p.exportPrivateKey()) : undefined` (ethers stays the app's) |
+  | `/react`: `WalletProvider`, `WalletContext`, `useWallet`, `useWalletContext`, `useWalletConnection`, `useWalletDetection`, `useWalletAddress`, `useGalaAddress`, `useWalletProvider`, `useIsWalletConnected` and their types | `@gala-chain/gala-core-sdk/react` |
+  | `/react`'s re-exports `detectWallets`, `ExternalWalletProvider`, `KNOWN_WALLET_RDNS`, `PrivateKeyProvider`, type `WalletProviderInterface` | `@gala-chain/gala-core-sdk/providers` (`WalletProviderInterface` is `WalletProvider`) |
+
+  A custom `WalletProvider` now needs `getSigner()` (core's interface). `react` is no longer a peer
+  of launchpad-sdk (it is an optional peer of core's `/react`).
+- **The Ethereum wallet helpers are gala-core-sdk's.** `createWallet`, `getPublicKeyFromPrivateKey`,
+  `getEthereumAddressFromPrivateKey` and the type `PublicKeyResult` are REMOVED from launchpad-sdk
+  (browser, node and `/native` entries): import them from `@gala-chain/gala-core-sdk`. Core's
+  `createWallet` returns `{ privateKey, address, galaAddress, mnemonic }` without the ethers
+  `.wallet`: `new Wallet(createWallet(input).privateKey)`. Refusals are core `GalaSDKError`s
+  (`INVALID_WALLET_INPUT`, `INVALID_PRIVATE_KEY`) instead of `ValidationError` / ethers errors; the
+  test-mode fake key (`NODE_ENV=test`) is gone. `createSolanaWallet` moved with the bridge (above).
+  `AgentConfig` builds its wallets with core's `createWallet`; its wallet type is exported as
+  `AgentWallet` (core's wallet plus the ethers `wallet`). The internal `WalletUtils` is gone.
+
+- **The token-class and hold types are gala-core-sdk's.** `fetchTokenClassesWithSupply` returns
+  `GalaChainTokenClass[]` (was `TokenClassWithSupply`, whose `authorities` were typed as objects:
+  GalaChain sends user refs, strings) and `fetchTokenDetails` returns `GalaChainTokenDetails` (was
+  launchpad's `GalaChainTokenDetails`, whose `chatEnabled` was never set: a token's chat status is
+  `getTokenConfig(tokenName).chatEnabled`). A hold in `TokenBalanceResult` / `LockedBalanceResult`
+  is `GalaChainTokenHold` (`name` and `vestingPeriodStart` are optional, as GalaChain stores them).
+  Removed exports: `TokenClassWithSupply`, `TokenHold`, the zod `tokenHoldSchema`; import the types
+  from `@gala-chain/gala-core-sdk`. A token class carries GalaChain's documented fields only (an
+  undocumented field is no longer passed on).
+- **`TokenClassKey` and `TokenInstanceKey` REMOVED**: every signature uses gala-core-sdk's
+  `GalaChainTokenClassKey` / `GalaChainTokenInstanceKey` (same four fields, plus `instance`), so
+  import those from `@gala-chain/gala-core-sdk`. `TokenId` stays (`string | GalaChainTokenClassKey
+  | GalaChainTokenInstanceKey`). The bridge's `isTokenClassKey` export is removed: use core's
+  `isTokenClassKey` (the same check: four non-empty strings).
+- `ENVIRONMENT_URLS` takes `gatewayBaseUrl` and `dexApiBaseUrl` from core's
+  `GALA_CHAIN_ENVIRONMENTS` (same URLs); `Environment` is core's `GalaChainEnv` (`'prod' | 'stage'`).
+- **The DEX is gswap-sdk's, not launchpad-sdk's.** launchpad-sdk no longer depends on
+  `@gala-chain/gswap-sdk` (product SDKs never import each other). Removed: `sdk.dex` (the `GSwap`
+  client) and the `GSwap` re-export; the swap-backend reads `fetchAllDexSeasons`,
+  `fetchCurrentDexSeason`, `fetchDexLeaderboardBySeasonId`, `fetchCurrentDexLeaderboard`,
+  `fetchDexAggregatedVolumeSummary` and the pool poller `onDexPoolCreation`; the types `DexSeason`,
+  `LeaderboardEntry`, `LeaderboardResult`, `MasteryTitle`, `DexAggregatedVolumeSummary`. Migration:
+
+  ```typescript
+  import { PrivateKeySigner } from '@gala-chain/gala-core-sdk';
+  import { GSwap } from '@gala-chain/gswap-sdk';
+
+  const gSwap = new GSwap({ env, signer: new PrivateKeySigner(key), walletAddress: sdk.getAddress() });
+  // sdk.dex.quoting / swaps / pools / positions / symbols / assets -> gSwap.quoting / swaps / ...
+  // sdk.fetchAllDexSeasons()               -> gSwap.leaderboard.getSeasons()
+  // sdk.fetchCurrentDexSeason()            -> gSwap.leaderboard.getCurrentSeason()
+  // sdk.fetchDexLeaderboardBySeasonId(id)  -> gSwap.leaderboard.getLeaderboard(id)  ({ seasonId, entries })
+  // sdk.fetchCurrentDexLeaderboard()       -> gSwap.leaderboard.getCurrentLeaderboard()
+  // sdk.fetchDexAggregatedVolumeSummary()  -> gSwap.market.getVolumeSummary()       (8 fields)
+  // sdk.onDexPoolCreation(cb, { minTVL })  -> gSwap.pools.watchNewPools(cb, { minTvl })
+  ```
+
+  The gswap reads follow the backend's real answers: an answer of another shape is an error, not
+  `[]`; an unusable row is skipped (reported to `onInvalidEntry`), not filled with `''` / `0`; a
+  leaderboard has no `totalEntries` (`entries.length`) and a wallet without an XP breakdown has
+  `totalXp: null` (was `'0'`). `sdk.dex` was also never rebuilt by `setWallet` (it kept the first
+  wallet's signer): an app's own `GSwap` is built from the signer it means.
+  (The price reads went with the 9.0 cut above: only `fetchTokenPrice({ tokenName })` stays.)
+
+- **`sdk.tokens` and `TokenWrites` REMOVED**, with the types `ChainResult`, `TransferInput`,
+  `LockInput`, `TokenAmountInput` and `TokenIdentifier`. They were a second implementation of the
+  same writes. Migration:
+
+  ```typescript
+  // Removed
+  const result = await sdk.tokens.transfer({ to, tokenClassKey: 'GALA|Unit|none|none', quantity: '1' });
+
+  // Now (the SDK's wallet, or a { signer, walletAddress } SDK)
+  const { transactionId, blockNumber } = await sdk.transferToken({ to, tokenId: 'GALA|Unit|none|none', amount: '1' });
+  // sdk.tokens.burn / lock / unlock -> sdk.burnTokens / lockTokens / unlockTokens({ tokens: [...] })
+  ```
+
+  What the services do not take that `sdk.tokens` did: a `client|` or `eth|0x...` recipient (spell
+  an Ethereum recipient `eth|<40 hex>` or `0x<40 hex>`), any `uniqueKey` (transfer keys keep the
+  `galaswap-operation-` / `galaconnect-operation-` prefix rule), a `$`-joined `tokenId`. For
+  those, use `GatewayWrites` from `@gala-chain/gala-core-sdk` directly.
+
+#### Added
+
+- An SDK configured with `{ signer, walletAddress }` (no `wallet`) can make token writes through
+  the five methods: signed by that signer and made as the declared identity (an `eth|` account or
+  a `client|` alias). With a `wallet` nothing changed.
+- `LockTokensResult`, `UnlockTokensResult` and `BurnTokensResult` carry the gateway's
+  `x-transaction-id` as `transactionId` (preferred over a `Data` item's id) and `blockNumber`
+  from `x-block-number`, like the transfer receipts.
+
+#### Changed
+
+- Auto-generated `uniqueKey`s are `galaconnect-operation-<uuid v4>` (58 characters, CSPRNG) instead
+  of `galaconnect-operation-<ms>_<26 hex>` (62). An empty `uniqueKey` means "none" (a key is
+  minted); it used to be signed as `""` and refused by the chain.
+- A caller's `uniqueKey` on `lockTokens` / `unlockTokens` / `burnTokens` (never checked before), and
+  one with characters outside `A-Za-z0-9._:-` on a transfer, is refused before signing.
+- Quantities must be plain decimal strings (no exponent, hex or spaces); they are still signed as
+  written, never scaled.
+- A pipe `tokenId` with a non-decimal fifth part (`Token|Unit|X|client|launchpad`, read as instance
+  `launchpad`) or a `TokenInstanceKey` with a non-decimal `instance` is refused before signing
+  instead of being signed as a different token.
+- Token writes go through the SDK's gateway `HttpClient` (axios, the `Sign` header) as the five
+  methods always did; `config.httpRequestor`, which `sdk.tokens` used, is not used for them (it
+  still serves the bundler path). An app that must send token writes through its own
+  requestor uses core's `GatewayWrites` (`httpRequestor` option).
+- `setWallet` / `setWalletProvider` now rebuild the token-write services, so a transfer, burn,
+  lock or unlock signs as the new wallet (before, the services kept signing as the wallet the SDK
+  was constructed with); a declared `{ signer, walletAddress }` identity no longer applies once the
+  wallet changes.
+- A refusal of the core write before anything is sent maps to the service's error class
+  (`SIGNING_FAILED` -> `SIGNATURE_FAILED`, a token reference -> `TOKEN_NOT_FOUND`, a quantity ->
+  `INVALID_AMOUNT`, others -> the validation type).
+
+#### Fixed (wallet changes)
+
+- After `setWallet` / `setWalletProvider` nothing signs as, or sends from, the previous wallet:
+  the bundle trades (`buyTokens`, `sellTokens`) are rebuilt for the new wallet (they kept the
+  construction wallet, so an SDK started read-only could never trade), and the bridge service, the
+  wrap service and the GalaConnect client (built at first use with that wallet's address and key,
+  then kept forever) are dropped and rebuilt for the new wallet at their next use.
+- An identity declared at construction (`walletAddress`, `galaChainAddress`, e.g. a `client|`
+  alias) named the construction key and is dropped on a wallet change: `getAddress()` was still
+  the old one, so the rebuilt services would have paired the new key with the old identity.
+- `SignatureAuth.setWalletProvider` with a key-holding provider (`PrivateKeyProvider`) knows the
+  address at once, as `setWallet` does (the synchronous getters threw until `cacheAddress()`); a
+  wallet-backed provider still needs `cacheAddress()` and never reports the previous account.
+
+#### Fixed (gateway reads)
+
+- `fetchGalaBalance` and `fetchTokenBalance` (tokenId and MUSIC/GMUSIC routes) work against the
+  real gateway again: their `FetchBalances` body carried `instance: "0"`, which mainnet and testnet
+  refuse with HTTP 400 ("whitelistValidation: property instance should not exist", recorded
+  2026-10-13), so every such call threw a `NetworkError`. The body is now the chain DTO
+  (`owner, collection, category, type, additionalKey`).
+- A balance record of another owner than the one asked for is never reported as theirs (the read
+  answers `null`); a missing owner is refused instead of reading every owner's balances.
+- `availableQuantity` / `lockedQuantity` / `inUseQuantity` are never in exponent form
+  (`0.00000001`, not `1e-8`).
+- `fetchNftCollections`, `isNftCollectionAvailable`, `fetchNftTokenClasses` and `fetchNftBalances`
+  read GalaChain (`FetchNftCollectionAuthorizationsWithPagination`,
+  `FetchTokenClassesWithPagination`, `FetchBalances`, page by page and bounded); they were
+  placeholders that always answered `[]` / `true`. `isNftCollectionAvailable` throws when the read
+  fails (never "available"), so `claimNftCollection` refuses a name that is already claimed. The
+  NFT writes (`claimNftCollection`, `createNftTokenClass`, `mintNft`) still do not reach GalaChain:
+  they return a locally made transaction id with status `pending`.
+
+#### Fixed (price history; these reads are now the MCP server's, on gswap-sdk, which keeps the fixes)
+
+- `fetchAllPriceHistory` reads the series once. It paged it through `fetchPriceHistory` with the
+  page NUMBER as the offset (0, 1, 2, ... with 50 per page), so a series over 50 points was
+  refetched in full per page (a 120-point series: about 100 requests) and came back with
+  overlapping, repeated snapshots; a series that changed between two requests shifted the pages.
+  A caller's `offset` / `limit` do not apply to it.
+- `fetchPriceHistory` refuses a `limit` or `pageSize` outside 1-50 and a negative or fractional
+  `offset` before any request (`ValidationError`). A `limit` of 0 used to answer `page: NaN`,
+  `totalPages: Infinity` (JSON `null`).
+
+#### Changed (gateway reads)
+
+- A `FetchBalances` / `FetchTokenClasses` answer that is not GalaChain's (a numeric quantity, a hold
+  or class missing its fields) is refused whole: a balance is then `null` (as for any unusable
+  answer), a token class a `NetworkError`. A token-class answer without the class asked for is a
+  `NetworkError` ("Token not found on GalaChain", 404) instead of returning another class.
+  `fetchTokenClassesWithSupply` answers one class per key in the order asked (1 to 1000 keys).
+
+#### Removed (internal)
+
+- `api/dto/{TransferTokenDto,BurnTokensDto,LockTokenDto,UnlockTokenDto}` (and with them
+  `@gala-chain/api`'s `ChainCallDTO` on these paths), `utils/token-instance-key.ts`.
+- `GalaChainBalanceService`'s `sumHoldQuantities` / `filterHolds` / `calculateAvailableQuantity`
+  (core totals the holds), the `GalaChainTokenBalance` / `InternalGalaChainFetchBalancesResponse` /
+  `InternalFetchTokenClassesWithSupplyResponse` types, `BalanceQueryParams.instance`, and
+  `@gala-chain/api`'s `TokenClass` on the token-class paths.
+- Dead code: `utils/token-parser` `parseToken` (no caller), `isDelimited`, `isValidTokenFormat`,
+  `isPlainTokenSymbol` and its `isTokenClassKey`; `delimiter-parser` `validateTokenObject` (only
+  `parseToken` used it); `tokenNormalizer`'s `isTokenClassKeyStrict` re-export, `isTokenInstanceKey`
+  and `isTokenIdString`; `unique-key-generator` `generateOperationKey` (no caller; its keys held a
+  `|` and exceeded 64 characters); the unimported modules `types/token.types.ts` and
+  `types/galachain-api.types.ts` (a third and fourth `TokenClassKey` / `isTokenClassKey`).
+- The GSwap error wrappers `GSwapQuoteError`, `GSwapSwapError`, `GSwapPoolError`,
+  `GSwapAssetError`, `GSwapPositionError`, `DexQuoteError`, `DexPoolNotFoundError` and
+  `handleGSwapErrorGeneric` (not exported, never thrown: gswap-sdk's `GSwapSDKError` is the DEX
+  error); `DexService`'s season, leaderboard and volume reads; `scripts/stage-verify-dex-reads.ts`
+  (`verify:stage-dex-reads`, which checked `sdk.dex`).
+- `@gala-chain/gswap-sdk` was then a devDependency only (the examples and the live stage test); with
+  the 9.0 cut above it is no dependency of any kind.
+
 ## 6.0.0
 
 ### BREAKING CHANGES