feat(sealevel-sdk): svm sdk cross collateral token (#8384)

Author: xeno097

.changeset/cross-collateral-token.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/sealevel-sdk': minor
+---
+
+Added cross-collateral token support to the SVM SDK, including create, read, and update operations for cross-collateral warp routes.

.github/workflows/test-sdk-e2e.yml

@@ -171,6 +171,7 @@ jobs:
           - native-token
           - synthetic-token
           - collateral-token
+          - cross-collateral-token
           - provider
           - read-token
         include:

pnpm-lock.yaml

@@ -58,6 +58,7 @@
     "chai": "^4.4.1",
     "chai-as-promised": "catalog:",
     "mocha": "^10.4.0",
+    "mocha-steps": "catalog:",
     "oxfmt": "catalog:",
     "sinon": "catalog:",
     "testcontainers": "catalog:",

typescript/svm-sdk/package.json

@@ -0,0 +1,27 @@
+import { decodeAccountData } from '../codecs/account-data.js';
+import type { ByteCursor } from '../codecs/binary.js';
+import { decodeMapU32VecH256 } from '../codecs/shared.js';
+
+export interface CrossCollateralStateData {
+  bump: number;
+  dispatchAuthorityBump: number;
+  localDomain: number;
+  enrolledRouters: Map<number, Uint8Array[]>;
+}
+
+export function decodeCrossCollateralStateAccount(
+  raw: Uint8Array,
+): CrossCollateralStateData | null {
+  const wrapped = decodeAccountData(raw, decodeCrossCollateralStateInner);
+  return wrapped.data;
+}
+
+function decodeCrossCollateralStateInner(
+  cursor: ByteCursor,
+): CrossCollateralStateData {
+  const bump = cursor.readU8();
+  const dispatchAuthorityBump = cursor.readU8();
+  const localDomain = cursor.readU32LE();
+  const enrolledRouters = decodeMapU32VecH256(cursor);
+  return { bump, dispatchAuthorityBump, localDomain, enrolledRouters };
+}

typescript/svm-sdk/src/accounts/cross-collateral-token.ts

@@ -369,6 +369,23 @@ export function decodeMapU32H256(cursor: ByteCursor): Map<number, H256> {
   return entries;
 }
 
+export function decodeMapU32VecH256(
+  cursor: ByteCursor,
+): Map<number, Uint8Array[]> {
+  const mapLen = cursor.readU32LE();
+  const entries = new Map<number, Uint8Array[]>();
+  for (let i = 0; i < mapLen; i += 1) {
+    const key = cursor.readU32LE();
+    const setLen = cursor.readU32LE();
+    const set: Uint8Array[] = [];
+    for (let j = 0; j < setLen; j += 1) {
+      set.push(cursor.readBytes(32));
+    }
+    entries.set(key, set);
+  }
+  return entries;
+}
+
 export function decodeMapU32GasOracle(
   cursor: ByteCursor,
 ): Map<number, GasOracle> {

typescript/svm-sdk/src/codecs/shared.ts

@@ -97,6 +97,8 @@ export {
   deriveValidatorAnnouncePda,
   deriveValidatorStorageLocationsPda,
   deriveReplayProtectionPda,
+  deriveCrossCollateralStatePda,
+  deriveCrossCollateralDispatchAuthorityPda,
 } from './pda.js';
 
 // Account decoders
@@ -119,3 +121,16 @@ export {
   decodeValidatorAnnounceAccount,
   decodeValidatorStorageLocationsAccount,
 } from './core/validator-announce-query.js';
+export { decodeCrossCollateralStateAccount } from './accounts/cross-collateral-token.js';
+
+// Cross-collateral instruction builders
+export {
+  getCrossCollateralInitInstruction,
+  getSetCrossCollateralRoutersInstruction,
+} from './instructions/cross-collateral-token.js';
+
+// Cross-collateral warp token reader/writer
+export {
+  SvmCrossCollateralTokenReader,
+  SvmCrossCollateralTokenWriter,
+} from './warp/cross-collateral-token.js';

typescript/svm-sdk/src/index.ts

@@ -0,0 +1,105 @@
+import type {
+  Address,
+  Instruction,
+  ReadonlyUint8Array,
+  TransactionSigner,
+} from '@solana/kit';
+
+import { concatBytes, u8, u32le, vec } from '../codecs/binary.js';
+import {
+  encodeH256,
+  encodeRemoteRouterConfig,
+  type H256,
+  type RemoteRouterConfig,
+} from '../codecs/shared.js';
+import { SYSTEM_PROGRAM_ADDRESS } from '../constants.js';
+import {
+  deriveCrossCollateralDispatchAuthorityPda,
+  deriveCrossCollateralStatePda,
+  deriveHyperlaneTokenPda,
+} from '../pda.js';
+import {
+  getTokenInitInstruction,
+  type TokenInitInstructionData,
+} from './token.js';
+import {
+  buildInstruction,
+  type InstructionAccountMeta,
+  readonlyAccount,
+  writableAccount,
+  writableSignerAddress,
+} from './utils.js';
+
+// Cross-collateral plugin discriminator [2; 8], distinct from the base
+// token program discriminator [1; 8] (PROGRAM_INSTRUCTION_DISCRIMINATOR).
+const CC_INSTRUCTION_DISCRIMINATOR = new Uint8Array([2, 2, 2, 2, 2, 2, 2, 2]);
+
+export enum CrossCollateralInstructionKind {
+  SetCrossCollateralRouters = 0,
+  TransferRemoteTo = 1,
+  HandleLocal = 2,
+  HandleLocalAccountMetas = 3,
+}
+
+export type CrossCollateralRouterUpdate =
+  | { kind: 'add'; config: { domain: number; router: H256 } }
+  | { kind: 'remove'; config: RemoteRouterConfig };
+
+function encodeCrossCollateralRouterUpdate(
+  update: CrossCollateralRouterUpdate,
+): ReadonlyUint8Array {
+  if (update.kind === 'add') {
+    return concatBytes(
+      u8(0),
+      u32le(update.config.domain),
+      encodeH256(update.config.router),
+    );
+  }
+
+  return concatBytes(u8(1), encodeRemoteRouterConfig(update.config));
+}
+
+export async function getCrossCollateralInitInstruction(
+  programAddress: Address,
+  payer: TransactionSigner,
+  init: TokenInitInstructionData,
+  pluginAccounts: InstructionAccountMeta[],
+  mailboxOutboxPda: Address,
+): Promise<Instruction> {
+  const { address: ccStatePda } =
+    await deriveCrossCollateralStatePda(programAddress);
+  const { address: ccDispatchAuthority } =
+    await deriveCrossCollateralDispatchAuthorityPda(programAddress);
+
+  return getTokenInitInstruction(programAddress, payer, init, [
+    ...pluginAccounts,
+    writableAccount(ccStatePda),
+    writableAccount(ccDispatchAuthority),
+    readonlyAccount(mailboxOutboxPda),
+  ]);
+}
+
+export async function getSetCrossCollateralRoutersInstruction(
+  programAddress: Address,
+  owner: Address,
+  updates: CrossCollateralRouterUpdate[],
+): Promise<Instruction> {
+  const { address: ccStatePda } =
+    await deriveCrossCollateralStatePda(programAddress);
+  const { address: tokenPda } = await deriveHyperlaneTokenPda(programAddress);
+
+  return buildInstruction(
+    programAddress,
+    [
+      readonlyAccount(SYSTEM_PROGRAM_ADDRESS),
+      writableAccount(ccStatePda),
+      readonlyAccount(tokenPda),
+      writableSignerAddress(owner),
+    ],
+    concatBytes(
+      CC_INSTRUCTION_DISCRIMINATOR,
+      u8(CrossCollateralInstructionKind.SetCrossCollateralRouters),
+      vec(updates, encodeCrossCollateralRouterUpdate),
+    ),
+  );
+}

typescript/svm-sdk/src/instructions/cross-collateral-token.ts

@@ -359,7 +359,7 @@ export async function getTokenSetDestinationGasConfigsInstruction(
   );
 }
 
-function encodeTokenInit(value: TokenInitInstructionData): Uint8Array {
+export function encodeTokenInit(value: TokenInitInstructionData): Uint8Array {
   const normalized: TokenInitCodecValue = {
     mailbox: value.mailbox,
     interchainSecurityModule: value.interchainSecurityModule,

typescript/svm-sdk/src/instructions/token.ts

@@ -221,3 +221,23 @@ export async function deriveEscrowPda(
     utf8.encode('escrow'),
   ]);
 }
+
+export async function deriveCrossCollateralStatePda(
+  programAddress: Address,
+): Promise<PdaWithBump> {
+  return derive(programAddress, [
+    utf8.encode('hyperlane_token'),
+    utf8.encode('-'),
+    utf8.encode('cross_collateral'),
+  ]);
+}
+
+export async function deriveCrossCollateralDispatchAuthorityPda(
+  programAddress: Address,
+): Promise<PdaWithBump> {
+  return derive(programAddress, [
+    utf8.encode('hyperlane_cc'),
+    utf8.encode('-'),
+    utf8.encode('dispatch_authority'),
+  ]);
+}