Migration guide

​

SDK v2 to v3

npm install @rhinestone/sdk@3.0.0 viem@^2.55.0

​

Nest account configuration by VM

import { RhinestoneSDK } from '@rhinestone/sdk'

const rhinestone = new RhinestoneSDK({
  auth: { mode: 'apiKey', apiKey: process.env.RHINESTONE_API_KEY! },
})

const account = await rhinestone.createAccount({
  owners: { type: 'ecdsa', accounts: [owner] },
})
const address = account.getAddress()

const account = await rhinestone.createAccount({
  evm: {
    owners: { type: 'ecdsa', accounts: [owner] },
  },
})
const address = account.getAddress('evm')

​

Use VM-specific imports

import { OWNABLE_VALIDATOR_ADDRESS, solanaMainnet } from '@rhinestone/sdk'
import { walletClientToAccount, wrapParaAccount } from '@rhinestone/sdk/utils'

import {
  OWNABLE_VALIDATOR_ADDRESS,
  walletClientToAccount,
  wrapParaAccount,
} from '@rhinestone/sdk/evm'
import { solanaMainnet } from '@rhinestone/sdk/solana'

​

Name one source and one destination

import { arbitrum, base } from 'viem/chains'

const arbitrumUsdc = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
const baseUsdc = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'

const prepared = await account.prepareTransaction({
  targetChain: base,
  sourceChains: [arbitrum],
  sourceAssets: [{
    chain: arbitrum,
    address: arbitrumUsdc,
    amount: 5_000_000n,
  }],
  tokenRequests: [{ address: baseUsdc, amount: 1_000_000n }],
})

const prepared = await account.prepareTransaction({
  source: {
    chain: arbitrum,
    token: arbitrumUsdc,
    maxAmount: 5_000_000n,
  },
  destination: {
    chain: base,
    token: baseUsdc,
    amount: 1_000_000n,
  },
})

• destination.token with amount requests exact output. With only token, receive the maximum output the source yields. Omit both for execution without token delivery.
• source.maxAmount caps the source balance available to the route; it does not promise to debit exactly that amount. Replace exact-input assumptions accordingly. For EVM sources, auxiliary funds are added after this cap.
• A delivery always needs source, even when sponsored. Execution without delivery can omit it only when gas-sponsored. HyperCore, Tron and Stellar destinations still need an explicit EVM source.chain.
• source.calls run before the claim. Their provides entries must name source.token; those amounts add to source.auxiliaryFunds. Calls formerly omitted by source selection now run or are refused.
• An explicit destination.recipient is delivery-only: do not combine it with destination calls. To execute through the invoking managed account, omit recipient.
• Put gasLimit alongside non-empty destination.calls, not on a delivery-only request. Cross-chain customDeadline and hyperCore options on non-HyperCore destinations are refused rather than ignored.

const prepared = await account.prepareTransaction({
  source: { token: baseUsdc },
  destination: { chain: base, calls },
})

​

Update deployment and setup

await account.deploy(base)
await account.setup(base)

await account.deploy('evm', base, { source: { token: baseUsdc } })
await account.setup(base, { source: { token: baseUsdc } })

​

Read quote requirements

const quote = prepared.quotes.best
const approval = quote.tokenRequirements?.[base.id]?.[baseUsdc]

const quote = prepared.quotes.best
const approval = quote.requirements.find(
  (requirement) => requirement.kind === 'erc20Approval'
    && requirement.chainId === 'eip155:8453'
    && requirement.tokenAddress.toLowerCase() === baseUsdc.toLowerCase(),
)

​

Migrate custom and detached signing

const signed = await account.signTransaction(prepared)
const result = await account.submitTransaction(signed)
const status = await account.waitForExecution(result)

const { origin, destination, targetExecution } =
  account.getTransactionMessages(prepared)
const signed = await account.signTransaction(prepared)
const signatures = signed.originSignatures

const requests = account.getTransactionMessages(prepared)
const signed = await account.signTransaction(prepared)
const proofs = signed.proofs
// proofs[i] answers requests[i].

• eip712: honor signatureFormat; an account-validator envelope is not a raw secp256k1 signature.
• personalSign: sign message.value as UTF-8 characters, not decoded hex.
• eip7702: return the authorization nonce and { r, s, yParity } signature.
• webauthn: return the assertion, not an ECDSA signature.

const contribution = await account.signTransaction(prepared, { owner })
const signed = await account.assembleTransaction(prepared, [contribution])

​

EIP-7702 authorizations

const signed = await account.signTransaction(prepared)
const authorizations = await account.signAuthorizations(prepared)
await account.submitTransaction(signed, { authorizations })

const signed = await account.signTransaction(prepared)
await account.submitTransaction(signed)

const proofs = await account.signAuthorizations(prepared)
const signed = await account.assembleTransaction(prepared, ownerSignatures, {
  proofs,
})

​

Upgrade sponsorship before clients

import { shouldSponsor } from '@rhinestone/sdk/jwt-server'

const allowed = await shouldSponsor(prepared.intentInput, {
  chain: ({ id }) => id === base.id,
  account: (address) => address === account.getAddress('evm'),
})

const prepared = await account.prepareTransaction({
  source: { chain: arbitrum, token: arbitrumUsdc },
  destination: { chain: base, token: baseUsdc, amount: 1_000_000n },
  sponsored: { gas: true, bridging: true, swaps: true },
})

​

Handle grouped status and native transaction references

for (const operation of status.operations) {
  console.log(
    operation.chain,
    operation.status,
    'txHash' in operation ? operation.txHash : undefined,
  )
}

for (const group of status.operations) {
  for (const operation of group.items) {
    if (operation.type === 'EXECUTION') {
      console.log(group.chainId, operation.result.outcome)
    } else {
      console.log(group.chainId, operation.status, operation.transaction)
    }
  }
}

​

Replace removed public types

​

Reconcile persisted transactions

​

Review smart session definitions

• Cross-chain permits are scoped by default. Open wildcard access is opt-in through fallback.
• Omitted settlement layers select every layer that can settle the permit, and explicit lists are strict. ECO is retired; use ECO_IE.
• A reusable permit’s maxAmount is a lifetime budget. Re-enabling an enabled session requires allowBudgetReset.
• Sessions add permit, swap, and one-time-use windows, and a one-time-use option.
• When signing is omitted, scoped sessions default to disabled signing; see Session signing.

​

What stays the same for EVM-only integrations

• You do not need a Solana account, signer or dependency. Configure only evm.
• Existing EVM account identities remain stable with the same configuration. Preserve any older Startale version explicitly, as described above.
• The prepare → sign → submit → wait lifecycle, quote selection and terminal status names stay the same.
• Managed EVM accounts retain reads, message signing, modules, recovery and UserOperation methods. UserOperation inputs remain flat { chain, calls, ... }; do not apply the intent input migration to them.
• Shared authentication/providers, appFees, protocolFees, settlement-layer/quoter filters, and HyperCore order builders retain their roles. Move only the transaction-specific fields described above.
• Preparation neither signs, spends nor deploys.

​

SDK v1 to v2

npm install @rhinestone/sdk@2.16.1 viem@^2.55.0

​

Initialize the SDK and account

import { RhinestoneSDK } from '@rhinestone/sdk'

const rhinestone = new RhinestoneSDK({
  auth: {
    mode: 'apiKey',
    apiKey: process.env.RHINESTONE_API_KEY!,
  },
})

const account = await rhinestone.createAccount({
  owners: {
    type: 'ecdsa',
    accounts: [owner],
  },
})

​

Replace transaction shortcuts

const prepared = await account.prepareTransaction(transaction)
const signed = await account.signTransaction(prepared)
const result = await account.submitTransaction(signed)
const status = await account.waitForExecution(result)

• Pass token addresses, not symbols such as USDC or WETH.
• Read the recommended route from prepared.quotes.best; all routes are in prepared.quotes.all.
• To select another route, call signTransaction(prepared, { intentId }) with an ID from quotes.all.
• Change settlementLayers arrays to { include: [...] } or { exclude: [...] }.
• Pass EIP-7702 authorizations as submitTransaction(signed, { authorizations }).
• Remove the second acceptsPreconfirmations argument from waitForExecution.
• Store intent IDs as strings before passing them to rhinestone.getIntentStatus(intentId).

import type { Transaction } from '@rhinestone/sdk'
import { base } from 'viem/chains'

const baseUsdc = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
const amount = 10_000_000n

const transaction = {
  targetChain: base,
  tokenRequests: [{ address: baseUsdc, amount }],
  settlementLayers: { include: ['ACROSS'] },
} satisfies Transaction

​

Migrate session keys

​

Update account and provider configuration

• Alchemy’s { type: 'alchemy', apiKey } provider configuration is removed. Supply complete per-chain URLs with { type: 'custom', urls }; see JSON-RPC providers.
• passport accounts are removed.
• Nexus supports 1.2.0 and 1.2.1; Kernel supports 3.3. Remove older pinned versions.
• submitTransaction options are now an object, including EIP-7702 authorizations.
• PortfolioToken.decimals and aggregate balances moved to per-chain entries as chains[].decimals and chains[].amount.

​

Update imports and removed helpers

import {
  experimental_getRhinestoneInitData,
  experimental_getV0InitData,
  walletClientToAccount,
  wrapParaAccount,
} from '@rhinestone/sdk/utils'
import { toSession } from '@rhinestone/sdk/smart-sessions'