@iota/isc-sdk 0.0.0-dev-20251015065834

package/src/transaction.ts

@@ -0,0 +1,380 @@
+import type { TransactionObjectArgument } from '@iota/iota-sdk/transactions';
+import { Transaction } from '@iota/iota-sdk/transactions';
+import * as isc from './isc.js';
+import type { ChainData } from './types/index.js';
+import { IOTA_TYPE_ARG } from '@iota/iota-sdk/utils';
+import { L2_FROM_L1_GAS_BUDGET } from './constants.js';
+import type { ObjectArgument } from './isc.js';
+
+export type Agent = {
+    type: 'evm';
+    address: string;
+};
+
+export class IscTransaction {
+    #finalized: boolean;
+    #transaction: Transaction;
+    #chainData: ChainData;
+
+    constructor(chainData: ChainData, transaction = new Transaction()) {
+        this.#finalized = false;
+        this.#transaction = transaction;
+        this.#chainData = chainData;
+    }
+
+    private validateFinalizedStatus() {
+        if (this.#finalized) {
+            throw Error('Transaction is built.');
+        }
+    }
+
+    /**
+     * Getter for the IOTA MOVE Transaction.
+     */
+    transaction(): Transaction {
+        return this.#transaction;
+    }
+
+    /**
+     * Create a bag.
+     */
+    newBag(): TransactionObjectArgument {
+        this.validateFinalizedStatus();
+        return isc.newBag(this.#transaction, this.#chainData);
+    }
+
+    /**
+     * Get some amount in a coin.
+     */
+    coinFromAmount({ amount }: { amount: number | bigint }) {
+        this.validateFinalizedStatus();
+        return isc.coinFromAmount(this.#transaction, BigInt(amount));
+    }
+
+    /**
+     * Place a coin in a bag.
+     *
+     * **Uses the IOTA Coin Type by default.**
+     */
+    placeCoinInBag({
+        bag,
+        coinType = IOTA_TYPE_ARG,
+        coin,
+    }: {
+        coin: ObjectArgument;
+        coinType?: string;
+        bag: TransactionObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        isc.placeCoinInBag(this.#transaction, this.#chainData, bag, coinType, coin);
+    }
+
+    /**
+     * Finally create and send a request calling the given `contractFunction` with `contractArgs` in `contract`
+     */
+    createAndSend({
+        bag,
+        contract,
+        contractFunction,
+        contractArgs,
+        transfers,
+        gasBudget = L2_FROM_L1_GAS_BUDGET,
+    }: {
+        contractArgs: Uint8Array[];
+        contract: number;
+        contractFunction: number;
+        transfers: Array<[string, number | bigint]>;
+        gasBudget?: number | bigint;
+        bag: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        isc.createAndSendRequest(
+            this.#transaction,
+            this.#chainData,
+            contract,
+            contractFunction,
+            contractArgs,
+            bag,
+            transfers,
+            gasBudget,
+        );
+    }
+
+    /**
+     * Finally create and send a request calling the given `accountsFunction` in `accountsContract`
+     */
+    createAndSendToEvm({
+        address,
+        accountsContract,
+        accountsFunction,
+        transfers,
+        gasBudget = L2_FROM_L1_GAS_BUDGET,
+        bag,
+    }: {
+        address: string;
+        accountsContract: number;
+        accountsFunction: number;
+        transfers: Array<[string, number | bigint]>;
+        gasBudget?: number | bigint;
+        bag: ObjectArgument;
+    }) {
+        const agentID = isc.agentIdForEVM(address);
+        this.createAndSend({
+            bag,
+            gasBudget,
+            contract: accountsContract,
+            contractFunction: accountsFunction,
+            contractArgs: [agentID],
+            transfers,
+        });
+    }
+
+    /**
+     * Take out the specified amount of coin from the bag.
+     *
+     * **Uses the IOTA Coin Type by default.**
+     */
+    takeCoinBalanceFromBag({
+        bag,
+        coinType = IOTA_TYPE_ARG,
+        amount,
+    }: {
+        amount: number | bigint;
+        coinType?: string;
+        bag: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.takeCoinBalanceFromBag(
+            this.#transaction,
+            this.#chainData,
+            bag,
+            coinType,
+            amount,
+        );
+    }
+
+    /**
+     * Take out all the coin from the bag.
+     *
+     * **Uses the IOTA Coin Type by default.**
+     */
+    takeAllCoinBalanceFromBag({
+        bag,
+        coinType = IOTA_TYPE_ARG,
+    }: {
+        bag: ObjectArgument;
+        coinType?: string;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.takeAllCoinBalanceFromBag(this.#transaction, this.#chainData, bag, coinType);
+    }
+
+    /**
+     * Place a coin balance in the bag.
+     *
+     * **Uses the IOTA Coin Type by default.**
+     */
+    placeCoinBalanceInBag({
+        bag,
+        coinType = IOTA_TYPE_ARG,
+        balance,
+    }: {
+        balance: ObjectArgument;
+        coinType?: string;
+        bag: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        isc.placeCoinBalanceInBag(this.#transaction, this.#chainData, bag, coinType, balance);
+    }
+
+    /**
+     * Place an asset in the bag.
+     */
+    placeAssetInBag({
+        bag,
+        asset,
+        assetType,
+    }: {
+        asset: ObjectArgument;
+        bag: ObjectArgument;
+        assetType: string;
+    }) {
+        this.validateFinalizedStatus();
+        isc.placeAssetInBag(this.#transaction, this.#chainData, bag, assetType, asset);
+    }
+
+    /**
+     * Take an asset from a bag.
+     */
+    takeAssetFromBag({
+        bag,
+        assetType,
+        asset,
+    }: {
+        bag: ObjectArgument;
+        assetType: string;
+        asset: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        isc.takeAssetFromBag(this.#transaction, this.#chainData, bag, assetType, asset);
+    }
+
+    /**
+     * Get the size of the bag.
+     */
+    getSizeOfBag({ bag }: { bag: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.getSizeOfBag(this.#transaction, this.#chainData, bag);
+    }
+
+    /**
+     * Destroy the bag.
+     */
+    destroyBag({ bag }: { bag: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.destroyBag(this.#transaction, this.#chainData, bag);
+    }
+
+    startNewChain({ metadata, coin }: { metadata: Uint8Array; coin?: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.startNewChain(this.#transaction, this.#chainData, metadata, coin);
+    }
+
+    createAnchorWithAssetBag({ bag }: { bag: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.createAnchorWithAssetBag(this.#transaction, this.#chainData, bag);
+    }
+
+    updateAnchorStateForMigraton({
+        anchor,
+        metadata,
+        stateIndex,
+    }: {
+        anchor: ObjectArgument;
+        metadata: Uint8Array;
+        stateIndex: number;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.updateAnchorStateForMigraton(
+            this.#transaction,
+            this.#chainData,
+            anchor,
+            metadata,
+            stateIndex,
+        );
+    }
+
+    destroyAnchor({ anchor }: { anchor: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.destroyAnchor(this.#transaction, this.#chainData, anchor);
+    }
+
+    borrowAssets({ anchor }: { anchor: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.borrowAssets(this.#transaction, this.#chainData, anchor);
+    }
+
+    returnAssetsFromBorrow({
+        anchor,
+        bag,
+        borrow,
+    }: {
+        anchor: ObjectArgument;
+        bag: ObjectArgument;
+        borrow: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.returnAssetsFromBorrow(this.#transaction, this.#chainData, anchor, bag, borrow);
+    }
+
+    receiveRequest({ anchor, request }: { anchor: ObjectArgument; request: ObjectArgument }) {
+        this.validateFinalizedStatus();
+        return isc.receiveRequest(this.#transaction, this.#chainData, anchor, request);
+    }
+
+    transition({
+        anchor,
+        newStateMetadata,
+        receipts,
+    }: {
+        anchor: ObjectArgument;
+        newStateMetadata: Uint8Array;
+        receipts: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.transition(
+            this.#transaction,
+            this.#chainData,
+            anchor,
+            newStateMetadata,
+            receipts,
+        );
+    }
+
+    placeCoinForMigration({
+        anchor,
+        coinType = IOTA_TYPE_ARG,
+        coin,
+    }: {
+        anchor: ObjectArgument;
+        coinType?: string;
+        coin: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.placeCoinForMigration(
+            this.#transaction,
+            this.#chainData,
+            anchor,
+            coinType,
+            coin,
+        );
+    }
+
+    placeCoinBalanceForMigration({
+        anchor,
+        coinType = IOTA_TYPE_ARG,
+        balance,
+    }: {
+        anchor: ObjectArgument;
+        coinType?: string;
+        balance: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.placeCoinBalanceForMigration(
+            this.#transaction,
+            this.#chainData,
+            anchor,
+            coinType,
+            balance,
+        );
+    }
+
+    placeAssetForMigration({
+        anchor,
+        assetType,
+        asset,
+    }: {
+        anchor: ObjectArgument;
+        assetType: string;
+        asset: ObjectArgument;
+    }) {
+        this.validateFinalizedStatus();
+        return isc.placeAssetForMigration(
+            this.#transaction,
+            this.#chainData,
+            anchor,
+            assetType,
+            asset,
+        );
+    }
+
+    /**
+     * Stop building this ISC Transaction and return the IOTA MOVE Transaction.
+     * @returns IOTA MOVE Transaction.
+     */
+    build(): Transaction {
+        this.validateFinalizedStatus();
+        this.#finalized = true;
+        return this.#transaction;
+    }
+}

package/src/types/assetsResponse.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+export const CoinJSONSchema = z.object({
+    balance: z.string(),
+    coinType: z.string(),
+});
+
+export const AssetsResponseSchema = z.object({
+    baseTokens: z.string(),
+    nativeTokens: z.array(CoinJSONSchema),
+});
+
+export type AssetsResponse = z.infer<typeof AssetsResponseSchema>;

package/src/types/chainData.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const ChainDataSchema = z.object({
+    packageId: z.string(),
+    chainId: z.string(),
+});
+
+export type ChainData = z.infer<typeof ChainDataSchema>;

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './assetsResponse.js';
+export * from './chainData.js';

package/src/utils/getHname.ts

@@ -0,0 +1,11 @@
+import { blake2b } from '@noble/hashes/blake2';
+
+export function getHname(input: string): number {
+    // Encode input as UTF-8 and hash it using BLAKE2b (32-byte digest)
+    const hash = blake2b(new TextEncoder().encode(input), { dkLen: 32 });
+
+    // Extract the first 4 bytes and interpret as little-endian uint32
+    const value = hash[0] | (hash[1] << 8) | (hash[2] << 16) | (hash[3] << 24);
+
+    return Number('0x' + (value >>> 0).toString(16).padStart(8, '0')); // Convert to hex with leading zeros
+}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './getHname.js';

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/tests/L1ToL2Tokens.spec.ts

@@ -0,0 +1,141 @@
+import {
+    AccountsContractMethod,
+    CoreContract,
+    getHname,
+    IscTransaction,
+    L2_FROM_L1_GAS_BUDGET,
+} from '../src/index';
+import { IOTA_TYPE_ARG } from '@iota/iota-sdk/utils';
+import { Ed25519Keypair } from '@iota/iota-sdk/keypairs/ed25519';
+import { requestIotaFromFaucetV0 } from '@iota/iota-sdk/faucet';
+import { IotaClient } from '@iota/iota-sdk/client';
+import { beforeAll, expect, test } from 'vitest';
+import { CONFIG } from './config';
+import { Wallet } from 'ethers';
+import { bcs } from '@iota/iota-sdk/bcs';
+import { checkL2BalanceWithRetries, requestFunds } from './utils';
+
+const { L1 } = CONFIG;
+
+let client: IotaClient;
+
+beforeAll(async () => {
+    client = new IotaClient({
+        url: L1.rpcUrl,
+    });
+});
+
+test('Send IOTA', async () => {
+    const keypair = new Ed25519Keypair();
+    const address = keypair.toIotaAddress();
+
+    await requestIotaFromFaucetV0({
+        host: L1.faucetUrl!,
+        recipient: address,
+    });
+
+    const wallet = Wallet.createRandom();
+
+    // EVM Address
+    const recipientAddress = wallet.address;
+    // Amount to send (1 IOTAs)
+    const amountToSend = BigInt(1 * 1000000000);
+    // We also need to place a little more in the bag to cover the L2 gas
+    const amountToPlace = amountToSend + L2_FROM_L1_GAS_BUDGET;
+
+    const iscTx = new IscTransaction(L1);
+
+    const bag = iscTx.newBag();
+    const coin = iscTx.coinFromAmount({ amount: amountToPlace });
+    iscTx.placeCoinInBag({ coin, bag });
+    iscTx.createAndSendToEvm({
+        bag,
+        transfers: [[IOTA_TYPE_ARG, amountToSend]],
+        address: recipientAddress,
+        accountsContract: getHname(CoreContract.Accounts),
+        accountsFunction: getHname(AccountsContractMethod.TransferAllowanceTo),
+    });
+
+    const transaction = iscTx.build();
+    transaction.setSender(address);
+    await transaction.build({ client });
+
+    await client.signAndExecuteTransaction({
+        signer: keypair,
+        transaction,
+    });
+
+    const evmBalance = await checkL2BalanceWithRetries(recipientAddress);
+    expect(evmBalance?.baseTokens).toEqual(amountToSend.toString());
+});
+
+test('Send Non-IOTA Tokens', async () => {
+    const MNEMONIC =
+        'mom program scrap easily doctor seed slender secret mad flat foam hospital cherry seek river you obscure column blood reflect arch pencil cat burst';
+    const TOKEN_COIN_TYPE =
+        '0xe1e88f4962b3ea96cfad19aee42f666b04bbce4dc4327c3cd63f1b8ff16e13b2::tool_coin::TOOL_COIN';
+
+    const keypair = Ed25519Keypair.deriveKeypair(MNEMONIC);
+    const address = keypair.toIotaAddress();
+    const wallet = Wallet.createRandom();
+
+    await requestFunds(client, L1.faucetUrl!, address);
+
+    // EVM Address
+    const recipientAddress = wallet.address;
+    // Amount to send (0.01 IOTAs)
+    const amountToSend = BigInt(1 * 1_000_000);
+    // Amount to send (1 Boxfish)
+    const tokenAmountToSend = BigInt(1);
+    // We also need to place a little more in the bag to cover the L2 gas
+    const amountToPlace = amountToSend + L2_FROM_L1_GAS_BUDGET;
+
+    const iscTx = new IscTransaction(L1);
+    const tx = iscTx.transaction();
+
+    const bag = iscTx.newBag();
+
+    // Place IOTA
+    const iotaCoin = iscTx.coinFromAmount({ amount: amountToPlace });
+    iscTx.placeCoinInBag({ coin: iotaCoin, bag, coinType: IOTA_TYPE_ARG });
+
+    // Place Token
+    const tokenCoin = tx.splitCoins(
+        tx.object('0xf7662ffd9cb079d8e75ab4805ba78fdb0e0fb78cf49aa0fa01ecb7ebdf15d04e'),
+        [tx.pure(bcs.U64.serialize(tokenAmountToSend))],
+    );
+    iscTx.placeCoinInBag({
+        bag,
+        coin: tokenCoin,
+        coinType: TOKEN_COIN_TYPE,
+    });
+
+    iscTx.createAndSendToEvm({
+        bag,
+        transfers: [
+            [IOTA_TYPE_ARG, amountToSend],
+            [TOKEN_COIN_TYPE, tokenAmountToSend],
+        ],
+        address: recipientAddress,
+        accountsContract: getHname(CoreContract.Accounts),
+        accountsFunction: getHname(AccountsContractMethod.TransferAllowanceTo),
+    });
+
+    const transaction = iscTx.build();
+    transaction.setSender(address);
+    await transaction.build({ client });
+
+    await client.signAndExecuteTransaction({
+        signer: keypair,
+        transaction,
+    });
+
+    const evmBalance = await checkL2BalanceWithRetries(recipientAddress, TOKEN_COIN_TYPE);
+    expect(evmBalance?.baseTokens).toEqual(amountToSend.toString());
+    expect(evmBalance?.nativeTokens).toEqual([
+        {
+            coinType: TOKEN_COIN_TYPE,
+            balance: tokenAmountToSend.toString(),
+        },
+    ]);
+});

package/tests/config.ts

@@ -0,0 +1,81 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { z } from 'zod';
+import { config } from 'dotenv';
+
+const HEX_REGEX = /^0x[0-9a-fA-F]+$/;
+
+const envSchema = z.record(
+    z.object({
+        L1: z.object({
+            networkName: z.string(),
+            rpcUrl: z.string().url(),
+            faucetUrl: z.string().url().optional(),
+            chainId: z.string(),
+            packageId: z.string(),
+        }),
+        L2: z.object({
+            chainName: z.string(),
+            chainCurrency: z.string(),
+            rpcUrl: z.string().url(),
+            chainId: z.preprocess(
+                (val) => (val !== undefined ? Number(val) : undefined),
+                z.number().int().positive(),
+            ),
+            chainDecimals: z.preprocess(
+                (val) => (val !== undefined ? Number(val) : undefined),
+                z.number().int().positive(),
+            ),
+            chainExplorerName: z.string(),
+            chainExplorerUrl: z.string(),
+            wagmiAppName: z.string(),
+            walletConnectProjectId: z.string(),
+            iscContractAddress: z
+                .string()
+                .regex(
+                    HEX_REGEX,
+                    'Must be a valid hex string starting with 0x',
+                ) as z.ZodType<`0x${string}`>,
+            evmRpcUrl: z.string().url(),
+        }),
+    }),
+);
+
+type Config = z.infer<typeof envSchema>;
+
+function loadConfig(): Config {
+    config();
+    const rawEvmBridgeConfig = process.env.VITE_EVM_BRIDGE_CONFIG as string;
+
+    let evmBridgeConfig: Record<string, unknown> = {};
+
+    try {
+        evmBridgeConfig = JSON.parse(rawEvmBridgeConfig);
+    } catch (error) {
+        throw new Error(
+            `Failed to parse IOTA EVM Bridge config JSON env var! ${(error as Error)?.message}`,
+        );
+    }
+
+    try {
+        return envSchema.parse(evmBridgeConfig);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            const missingVars = error.issues
+                .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                .join('\n');
+            throw new Error(`Missing required configuration:\n${missingVars}`);
+        }
+
+        throw error;
+    }
+}
+
+export const CONFIG = getDefaultNetwork();
+
+function getDefaultNetwork() {
+    const config = loadConfig();
+    const evmBridgeDefaultNetwork = process.env.VITE_EVM_BRIDGE_DEFAULT_NETWORK as string;
+    return config[evmBridgeDefaultNetwork];
+}