Migrating from @gala-chain/gswap-sdk 1.x to @gala-chain/gala-core-sdk

@gala-chain/gswap-sdk 2.0.0 no longer ships the signing, transport, wallet-helper and base-error layer. It moved, unchanged in behaviour, into @gala-chain/gala-core-sdk (1.0.0-rc.0), which gswap-sdk 2.0 takes as a peer dependency (the range is in gswap-sdk's peerDependencies). There are no re-exports: an app imports each moved symbol from core. This page is the mechanical migration table for any app that imported those symbols from gswap-sdk 1.x.

npm install @gala-chain/gswap-sdk@next @gala-chain/gala-core-sdk@next

Both are release candidates under the next dist-tag (^2 matches no prerelease); an app build pins the exact versions.

Install exactly one copy of core (a peer, never a nested dependency): npm ls @gala-chain/gala-core-sdk must show one version. Two copies would split instanceof GalaSDKError and the signer classes.

1. Imports that change path only (same name, same behaviour)

Every row: import { X } from '@gala-chain/gswap-sdk' becomes import { X } from '@gala-chain/gala-core-sdk'.

Area	Moved exports (values)	Moved exports (types)
Signers	PrivateKeySigner, GalaWalletSigner, BrowserWalletSigner, createLazyPrivateKeySigner, ethereumAddressOfAccount	GalaChainSigner, SignedDto, BrowserWalletProvider, GalaWalletScheme, PrivateKeyProvider, LazyPrivateKeySignerOptions
Signing primitives	serialize, getPayloadToSign, signNative, signSerializedNative, signPersonalMessage, calculatePersonalSignPrefix, personalSignPrefixFor, fixpointPrefixFor, normalizePrivateKey, ethAddressOfPrivateKey
Wallet signing (string keys)	signChainDtoNative, signChainDtoHash, signChainDtoPersonalSign, resolvePersonalSignChainDtoPayload, signRawObject, withPrivateKey, stripEip712DomainType, tokenClassDollarKey, canonicalDecimalString	PersonalSignChainDtoPayload, PrivateKeyInput
EIP-712 and typed data	generateEIP712Types, buildEIP712Payload, eip712DomainFor, EIP712_CAPABLE_METHODS, hashTypedData, signTypedDataPayload	EIP712Types, EIP712DomainValue, TypedDataPayload
Transport adapters	httpRequestorFromAxios, eip1193ProviderFromEthers, isFetchTransportFailure	AxiosLikeInstance, AxiosLikeConfig, AxiosLikeResponse, AxiosRequestorOptions, EthersLikeSigner, EthersLikeProvider, EthersEip1193Options, WireOptions
Token class keys	compositeKeyOf, tryParseCompositeKey, tryParseTokenClassKey	GalaChainTokenClassKey
uniqueKeys	createUniqueKey, assertUniqueKey, resolveUniqueKeyPrefix, isValidUniqueKey, DEFAULT_UNIQUE_KEY_PREFIX	UniqueKeyOptions
Failure views	toFailureView, isWriteView, FAILURE_OUTCOMES	FailureView, FailureOutcome
Error reasons (closed sets)	INVALID_PRIVATE_KEY_REASONS, SIGNING_FAILURE_REASONS	InvalidPrivateKeyReason, SigningFailureReason
Wallet helpers	isWalletUserRejection, walletDeclineCode
Error helpers	parseJson

Everything else stays in @gala-chain/gswap-sdk: GSwap and its services, ChainGateway, GSwapSDKError, isGSwapError, isPreSendError, classifyFailure, mayHaveBeenQueued, the guards (isRelayableRefusal, isNoMarket, chainErrorKeyOf, ...), pendingSwapFateFor, the builders, tick math, getObjectProperty, getStringProperty, UPDATE_REQUIRED_STATUS.

2. Renamed while moving

gswap-sdk 1.x	gala-core-sdk
isGSwapErrorLike	isGalaErrorLike
type GSwapErrorShape	type GalaErrorShape
GSWAP_ERROR_PHASES	GALA_ERROR_PHASES
type GSwapErrorPhase	type GalaErrorPhase
type GSwapErrorContext	type GalaErrorContext
renderGSwapErrorTemplate	renderGalaErrorTemplate
brand Symbol.for('@gala-chain/gswap-sdk/error')	brand Symbol.for('@gala-chain/gala-core-sdk/error')
subpath @gala-chain/gswap-sdk/wallet (isGSwapErrorLike, isWalletUserRejection, walletDeclineCode)	subpath @gala-chain/gala-core-sdk/wallet (isGalaErrorLike, isWalletUserRejection, walletDeclineCode)

The brand change matters only across versions: a gswap-sdk 1.x error object (old brand) is still recognised by isGalaErrorLike / isWalletUserRejection through its shape (a string code and object params), but hasGalaErrorBrand is false for it. Upgrade every bundle that throws or reads SDK errors together.

3. Behaviour an app may rely on, and what changed

• The error class. Core's GalaSDKError is the base class; GSwapSDKError extends GalaSDKError and carries the same fields (code, params, phase, status, body, bodyText, url, uniqueKey, write, shadow, walletCode, retryAfterMs, ...). Errors that core throws itself (a signer, normalizePrivateKey, the fetch requestor's TRANSPORT_ERROR, requestWithTimeout's REQUEST_TIMEOUT, validateTimeoutMs, resolveUniqueKeyPrefix) are plain GalaSDKErrors and not instanceof GSwapSDKError. Replace error instanceof GSwapSDKError with isGSwapError(error) (gswap-sdk; recognises both) or isGalaError(error) (core). isGSwapError(error, 'INVALID_PRIVATE_KEY') keeps working for a core code thrown by core.
• The catalogs are split, one code per catalog. GALA_ERROR_CATALOG (core) holds the 52 signing / transport / wallet / typed-data / uniqueKey codes; gswap-sdk's GSWAP_ERROR_CATALOG, gswapErrorTemplates and GSWAP_ERROR_PHASE_BY_CODE hold only the DEX codes. An app that seeds its translations from the templates merges galaErrorTemplates (core) and gswapErrorTemplates. A GSwapSDKError can carry a code of either catalog (GSwapErrorCode is the union), and classifyFailure / isPreSendError / the guards answer for both exactly as in 1.x.
• No code changed meaning. Every one of the 135 codes of gswap-sdk 1.2 keeps its template, params, phase and classification. One code is new: CSPRNG_UNAVAILABLE (below).
• uniqueKeys are minted with crypto.getRandomValues, never crypto.randomUUID (React Native/Hermes has no randomUUID). The format is unchanged (<prefix><uuid v4>, lowercase 8-4-4-4-12). With no getRandomValues the mint throws CSPRNG_UNAVAILABLE (pre_send): install react-native-get-random-values on React Native. A test that pinned the key by stubbing crypto.randomUUID now stubs crypto.getRandomValues (the 16 bytes of the wanted UUID).
• User-Agent. The default request header is still GalaChain-SDK/<version>, and the version is now core's package version (GALA_CORE_SDK_VERSION), not gswap-sdk's. Set wire.userAgent to pin your own.
• No Node globals. Core's shipped source uses no Node builtin, no Buffer, no process, and never loads ethers, axios or @gala-chain/api (a CI guard, pnpm run check:rn-safety, enforces it). The only polyfill React Native needs is getRandomValues.

4. New in core (no 1.x equivalent)

GalaSDKError, isGalaError, AnyGalaError, GALA_ERROR_CATALOG, galaErrorTemplates, GALA_ERROR_PHASE_BY_CODE, isGalaCatalogCode, hasGalaErrorBrand, templatePlaceholders, signPreSend (the "nothing was sent" wrapper around an app signer), the transport pieces gswap-sdk used internally (fetchRequestor, requestWithTimeout, buildRequestHeaders, buildQueryString, readHeader, readRetryAfter, readBlockNumberHeader, readResponseBody, armTimeout, validateTimeoutMs, types HttpRequestor, HTTPResponse, RequestHeaderParts), the failure-view readers stringParamOf / numberParamOf, splitClassKey, and GALA_CORE_SDK_VERSION.

5. Mechanical migration, per app

1. Add @gala-chain/gala-core-sdk to dependencies next to @gala-chain/gswap-sdk@^2.
2. For every import of a symbol in section 1, change the module to @gala-chain/gala-core-sdk.
3. Apply the renames of section 2 (including @gala-chain/gswap-sdk/wallet → @gala-chain/gala-core-sdk/wallet).
4. Replace instanceof GSwapSDKError with isGSwapError(...) (section 3).
5. Seed translations from galaErrorTemplates and gswapErrorTemplates together.
6. On React Native, import react-native-get-random-values once at startup.