Migrate to Nexus SDK v2
Migrate from @avail-project/nexus-core 1.x to 2.x — factory client, param renames, per-operation hooks, and plan-based events.
@avail-project/nexus-core 2.0.0 is a full rewrite of the SDK surface. The package name is unchanged — upgrading the dependency is the whole install step — but most call sites need mechanical renames. This page walks you through the breaking changes and how to update for each. The full migration reference is the complete, version-pinned list — including simulation and event-level detail, every changed field, and a step-by-step checklist.
Installation
pnpm add @avail-project/nexus-core@^2
Client lifecycle
initialize(provider). v2 uses a factory function with a two-step init, so you can fetch deployment data before a wallet connects:
// v1
const sdk = new NexusSDK({ network: "mainnet" });
await sdk.initialize(provider);
await sdk.deinit();
// v2
const client = createNexusClient({ network: "mainnet" });
await client.initialize(); // fetches deployment info
await client.setEVMProvider(provider); // connects wallet (can be called later)
client.destroy(); // synchronousinitialize() + setEVMProvider() — triggerAccountChange() is removed.
Parameter renames
bridge, bridgeAndTransfer, and bridgeAndExecute:
| v1 field | v2 field |
|---|---|
token | toTokenSymbol |
amount | toAmountRaw |
sourceChains | sources |
// v1
await sdk.bridge({ token: "USDC", amount: 1000000n, toChainId: 8453, sourceChains: [1, 42161] });
// v2
await client.bridge({ toTokenSymbol: "USDC", toAmountRaw: 1000000n, toChainId: 8453, sources: [1, 42161] });toAmountRaw is in raw base units as a bigint, not a human amount — 1 USDC (6 decimals) is 1000000n, not 1. Convert with client.convertTokenReadableAmountToBigInt(amount, tokenSymbol, chainId), whose signature is unchanged from v1.
In bridgeAndExecute, the execute block no longer takes its own toChainId — it inherits the top-level one.
Swap inputs were renamed too, and each variant has its own field changes:
| v1 type | v2 type | field changes |
|---|---|---|
ExactInSwapInput | SwapExactInParams | from → sources, from[].amount → sources[].amountRaw |
ExactOutSwapInput | SwapExactOutParams | fromSources → sources, toAmount → toAmountRaw, toNativeAmount → toNativeAmountRaw |
MaxSwapInput | SwapMaxParams | fromSources → sources |
Hooks: global setters → per-operation options
'min').
// v1
sdk.setOnIntentHook((data) => data.allow());
sdk.setOnAllowanceHook((data) => data.allow(data.sources.map(() => "min")));
await sdk.bridge(params);
// v2
await client.bridge(params, {
hooks: {
onIntent: (data) => data.allow(),
onAllowance: (data) => data.allow(data.sources.map(() => "min")),
},
});Events: step callbacks → plan-based events
{ name, args } union (STEPS_LIST, STEP_COMPLETE, …) is replaced by a typed discriminated union: status, plan_preview, plan_confirmed, and plan_progress. Detect a skipped bridge via result.bridgeSkipped — there are no *_SKIPPED events. See Bridge Events for the full v2 event reference.
Results and errors
- Operations throw typed
NexusErrorsubclasses on failure instead of returning{ success: false }— use try/catch and branch onerror.category/error.code. - Operation results nest transactions:
executeResponse→execute,executeTransactionHash→execute.txHash,explorerUrl→intentExplorerUrl. - Bridge
result.sourceTxsis now an array (was a single object):sourceTxs.hash→sourceTxs[].txHash,sourceTxs.explorerUrl→sourceTxs[].txExplorerUrl. - User-denial error codes were renamed. Match with
error instanceof UserActionError, or branch on the specificerror.code:
| v1 code | v2 code |
|---|---|
USER_DENIED_INTENT | USER_INTENT_HOOK_DENIED |
USER_DENIED_ALLOWANCE | USER_ALLOWANCE_APPROVAL_DENIED |
USER_DENIED_INTENT_SIGNATURE | USER_INTENT_SIGNATURE_DENIED |
USER_DENIED_SIWE_SIGNATURE | USER_SIWE_SIGNATURE_DENIED |
Balance APIs
getBalancesForBridge()— same call shape; elements are nowTokenBalanceinstead ofUserAssetDatum.getBalancesForSwap()— theonlyNativesAndStablesboolean was removed; call it with no arguments.
UserAsset → TokenBalance row below for the field renames (icon → logo, balanceInFiat → value, breakdown → chainBalances).
Type and API renames
| v1 | v2 |
|---|---|
getMyIntents(page) | listIntents({ page, status }) → { intents, total } (page size fixed at 20) |
ReadableIntent | BridgeIntent (sources → selectedSources, allSources → availableSources) |
UserAsset / UserAssetDatum | TokenBalance (icon → logo, balanceInFiat → value, breakdown → chainBalances) |
RFF / RequestForFunds | IntentRecord (id → requestHash, status booleans collapsed into status) |
SuccessfulSwapResult | SwapResult |
getSwapSupportedChains() | removed — getSupportedChains() includes per-chain token info |
CHAIN_METADATA / TOKEN_METADATA constants | removed — use client.chainList |
sdk.utils.isSupportedChain(...) | client.isSupportedChain(chainId) |
Full reference
How is this guide?