@twin.org/dlt-iota 0.0.3-next.9 → 0.9.0-next.1

package/dist/es/index.js

@@ -11,14 +11,18 @@ export * from "./models/IGasStationExecuteResponse.js";
 export * from "./models/IGasStationReserveGasResponse.js";
 export * from "./models/IGasStationReserveGasResult.js";
 export * from "./models/IIotaClient.js";
-export * from "./models/IIotaControllerCapInfo.js";
-export * from "./models/IIotaTransaction.js";
-export * from "./models/IIotaTransactionBlockResponse.js";
 export * from "./models/IIotaConfig.js";
+export * from "./models/IIotaControllerCapInfo.js";
 export * from "./models/IIotaDryRun.js";
 export * from "./models/IIotaResponseOptions.js";
+export * from "./models/IIotaTransaction.js";
+export * from "./models/IIotaTransactionBlockResponse.js";
+export * from "./models/ITransactionSigner.js";
 export * from "./models/IMigrationStateFields.js";
 export * from "./models/ISmartContractDeployments.js";
 export * from "./models/ISmartContractObject.js";
 export * from "./models/networkTypes.js";
+export * from "./vaultJwtSigner.js";
+export * from "./vaultSigner.js";
+export * from "./vaultTransactionSigner.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC;AACxC,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./iota.js\";\nexport * from \"./iotaIdentityUtils.js\";\nexport * from \"./iotaSmartContractUtils.js\";\nexport * from \"./models/IAdminCapFields.js\";\nexport * from \"./models/IContractData.js\";\nexport * from \"./models/IGasReservationResult.js\";\nexport * from \"./models/IGasStationConfig.js\";\nexport * from \"./models/IGasStationExecuteResponse.js\";\nexport * from \"./models/IGasStationReserveGasResponse.js\";\nexport * from \"./models/IGasStationReserveGasResult.js\";\nexport * from \"./models/IIotaClient.js\";\nexport * from \"./models/IIotaControllerCapInfo.js\";\nexport * from \"./models/IIotaTransaction.js\";\nexport * from \"./models/IIotaTransactionBlockResponse.js\";\nexport * from \"./models/IIotaConfig.js\";\nexport * from \"./models/IIotaDryRun.js\";\nexport * from \"./models/IIotaResponseOptions.js\";\nexport * from \"./models/IMigrationStateFields.js\";\nexport * from \"./models/ISmartContractDeployments.js\";\nexport * from \"./models/ISmartContractObject.js\";\nexport * from \"./models/networkTypes.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oCAAoC,CAAC;AACnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./iota.js\";\nexport * from \"./iotaIdentityUtils.js\";\nexport * from \"./iotaSmartContractUtils.js\";\nexport * from \"./models/IAdminCapFields.js\";\nexport * from \"./models/IContractData.js\";\nexport * from \"./models/IGasReservationResult.js\";\nexport * from \"./models/IGasStationConfig.js\";\nexport * from \"./models/IGasStationExecuteResponse.js\";\nexport * from \"./models/IGasStationReserveGasResponse.js\";\nexport * from \"./models/IGasStationReserveGasResult.js\";\nexport * from \"./models/IIotaClient.js\";\nexport * from \"./models/IIotaConfig.js\";\nexport * from \"./models/IIotaControllerCapInfo.js\";\nexport * from \"./models/IIotaDryRun.js\";\nexport * from \"./models/IIotaResponseOptions.js\";\nexport * from \"./models/IIotaTransaction.js\";\nexport * from \"./models/IIotaTransactionBlockResponse.js\";\nexport * from \"./models/ITransactionSigner.js\";\nexport * from \"./models/IMigrationStateFields.js\";\nexport * from \"./models/ISmartContractDeployments.js\";\nexport * from \"./models/ISmartContractObject.js\";\nexport * from \"./models/networkTypes.js\";\nexport * from \"./vaultJwtSigner.js\";\nexport * from \"./vaultSigner.js\";\nexport * from \"./vaultTransactionSigner.js\";\n"]}

package/dist/es/iota.js

@@ -1,11 +1,14 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 import { IotaClient } from "@iota/iota-sdk/client";
-import { Ed25519Keypair } from "@iota/iota-sdk/keypairs/ed25519";
+import { requestIotaFromFaucetV0 } from "@iota/iota-sdk/faucet";
 import { Transaction } from "@iota/iota-sdk/transactions";
-import { BaseError, Converter, GeneralError, Guards, Is, StringHelper } from "@twin.org/core";
-import { Bip39, Bip44, KeyType } from "@twin.org/crypto";
+import { BaseError, Coerce, Converter, GeneralError, Guards, Is, StringHelper } from "@twin.org/core";
+import { Bip39, Bip44, Blake2b, KeyType } from "@twin.org/crypto";
+import { VaultConnectorHelper, VaultKeyType } from "@twin.org/vault-models";
 import { FetchHelper, HttpMethod } from "@twin.org/web";
+import { VaultSigner } from "./vaultSigner.js";
+import { VaultTransactionSigner } from "./vaultTransactionSigner.js";
 /**
  * Class for performing operations on IOTA.
  */
@@ -31,11 +34,26 @@ export class Iota {
      * @internal
      */
     static _DEFAULT_SCAN_RANGE = 1000;
+    /**
+     * Default pre-calculation chunk size.
+     * @internal
+     */
+    static _PRE_CALC_CHUNK_SIZE = 25;
     /**
      * Default inclusion timeout.
      * @internal
      */
     static _DEFAULT_INCLUSION_TIMEOUT = 60;
+    /**
+     * Default gas budget for all transactions (including sponsored and direct).
+     * @internal
+     */
+    static _DEFAULT_GAS_BUDGET = 50000000;
+    /**
+     * Default gas reservation duration.
+     * @internal
+     */
+    static _DEFAULT_GAS_RESERVATION_DURATION = 60;
     /**
      * Create a new IOTA client.
      * @param config The configuration.
@@ -58,45 +76,107 @@ export class Iota {
         config.coinType ??= Iota.DEFAULT_COIN_TYPE;
         config.inclusionTimeoutSeconds ??= Iota._DEFAULT_INCLUSION_TIMEOUT;
     }
+    /**
+     * Store a mnemonic in the vault, derive and store the seed, and pre-cache the first keypair chunk.
+     * @param vaultConnector The vault connector.
+     * @param config The configuration.
+     * @param identity The identity of the user to access the vault keys.
+     * @param mnemonic The mnemonic to store, if undefined a new one will be generated and returned.
+     * @param accountIndex The account index to pre-cache.
+     * @returns The mnemonic that was stored.
+     */
+    static async storeMnemonic(vaultConnector, config, identity, mnemonic, accountIndex) {
+        Guards.object(Iota.CLASS_NAME, "vaultConnector", vaultConnector);
+        Guards.object(Iota.CLASS_NAME, "config", config);
+        Guards.stringValue(Iota.CLASS_NAME, "identity", identity);
+        Guards.integer(Iota.CLASS_NAME, "accountIndex", accountIndex);
+        const mnemonicToStore = mnemonic ?? Bip39.randomMnemonic();
+        await vaultConnector.setSecret(Iota.buildMnemonicKey(identity, config.vaultMnemonicId), mnemonicToStore);
+        const seed = Bip39.mnemonicToSeed(mnemonicToStore);
+        await vaultConnector.setSecret(Iota.buildSeedKey(identity, config.vaultSeedId), Converter.bytesToBase64(seed));
+        await Iota.getPublicKeys(vaultConnector, config, identity, accountIndex, false, 0, async () => seed);
+        return mnemonicToStore;
+    }
+    /**
+     * Derive an address from a public key.
+     * @param publicKey The public key to derive the address from.
+     * @returns The derived address.
+     */
+    static publicKeyToAddress(publicKey) {
+        return Converter.bytesToHex(Blake2b.sum256(publicKey), true);
+    }
+    /**
+     * Get address for the identity.
+     * @param vaultConnector The vault connector.
+     * @param config The configuration.
+     * @param identity The identity of the user to access the vault keys.
+     * @param accountIndex The account index to get the addresses for.
+     * @param startAddressIndex The start index for the addresses.
+     * @param isInternal Whether the addresses are internal.
+     * @returns The address.
+     */
+    static async getAddress(vaultConnector, config, identity, accountIndex, startAddressIndex, isInternal) {
+        const addresses = await Iota.getAddresses(vaultConnector, config, identity, accountIndex, startAddressIndex, 1, isInternal);
+        return addresses[0];
+    }
     /**
      * Get addresses for the identity.
-     * @param seed The seed to use for generating addresses.
-     * @param coinType The coin type to use.
+     * @param vaultConnector The vault connector.
+     * @param config The configuration.
+     * @param identity The identity of the user to access the vault keys.
      * @param accountIndex The account index to get the addresses for.
      * @param startAddressIndex The start index for the addresses.
      * @param count The number of addresses to generate.
      * @param isInternal Whether the addresses are internal.
      * @returns The list of addresses.
      */
-    static getAddresses(seed, coinType, accountIndex, startAddressIndex, count, isInternal) {
-        Guards.integer(Iota.CLASS_NAME, "coinType", coinType);
+    static async getAddresses(vaultConnector, config, identity, accountIndex, startAddressIndex, count, isInternal) {
+        Guards.object(Iota.CLASS_NAME, "vaultConnector", vaultConnector);
+        Guards.object(Iota.CLASS_NAME, "config", config);
+        Guards.stringValue(Iota.CLASS_NAME, "identity", identity);
         Guards.integer(Iota.CLASS_NAME, "accountIndex", accountIndex);
         Guards.integer(Iota.CLASS_NAME, "startAddressIndex", startAddressIndex);
         Guards.integer(Iota.CLASS_NAME, "count", count);
         const addresses = [];
-        for (let i = startAddressIndex; i < startAddressIndex + count; i++) {
-            // Derive the keypair using the seed
-            const keyPair = Bip44.keyPair(seed, KeyType.Ed25519, coinType ?? Iota.DEFAULT_COIN_TYPE, accountIndex, isInternal ?? false, i);
-            const keypair = Ed25519Keypair.fromSecretKey(keyPair.privateKey);
-            addresses.push(keypair.getPublicKey().toIotaAddress());
+        const internal = isInternal ?? false;
+        let currentIndex = startAddressIndex;
+        let cachedSeed;
+        const seedProvider = async () => {
+            cachedSeed ??= await Iota.getSeed(vaultConnector, config, identity);
+            return cachedSeed;
+        };
+        while (addresses.length < count) {
+            const chunkStart = Math.floor(currentIndex / Iota._PRE_CALC_CHUNK_SIZE) * Iota._PRE_CALC_CHUNK_SIZE;
+            const publicKeys = await Iota.getPublicKeys(vaultConnector, config, identity, accountIndex, internal, chunkStart, seedProvider);
+            const chunk = publicKeys.map((pk) => Iota.publicKeyToAddress(Converter.base64ToBytes(pk)));
+            const offsetInChunk = currentIndex - chunkStart;
+            const remaining = count - addresses.length;
+            addresses.push(...chunk.slice(offsetInChunk, offsetInChunk + remaining));
+            currentIndex = chunkStart + Iota._PRE_CALC_CHUNK_SIZE;
         }
         return addresses;
     }
     /**
-     * Get a key pair for the specified index.
-     * @param seed The seed to use for generating the key pair.
-     * @param coinType The coin type to use.
-     * @param accountIndex The account index to get the key pair for.
-     * @param addressIndex The address index to get the key pair for.
-     * @param isInternal Whether the address is internal.
-     * @returns The key pair containing private key and public key.
+     * Get a vault-backed transaction signer for the given identity and key indices.
+     * @param vaultConnector The vault connector.
+     * @param config The configuration.
+     * @param identity The identity of the user to access the vault keys.
+     * @param accountIndex The account index.
+     * @param addressIndex The address index within the account.
+     * @returns A VaultTransactionSigner for the specified key.
      */
-    static getKeyPair(seed, coinType, accountIndex, addressIndex, isInternal) {
-        Guards.integer(Iota.CLASS_NAME, "coinType", coinType);
+    static async getTransactionSigner(vaultConnector, config, identity, accountIndex, addressIndex) {
+        Guards.object(Iota.CLASS_NAME, "vaultConnector", vaultConnector);
+        Guards.object(Iota.CLASS_NAME, "config", config);
+        Guards.stringValue(Iota.CLASS_NAME, "identity", identity);
         Guards.integer(Iota.CLASS_NAME, "accountIndex", accountIndex);
         Guards.integer(Iota.CLASS_NAME, "addressIndex", addressIndex);
-        const keyPair = Bip44.keyPair(seed, KeyType.Ed25519, coinType ?? Iota.DEFAULT_COIN_TYPE, accountIndex, isInternal ?? false, addressIndex);
-        return keyPair;
+        const publicKeys = await Iota.getPublicKeys(vaultConnector, config, identity, accountIndex, false, addressIndex, async () => Iota.getSeed(vaultConnector, config, identity));
+        const chunkStart = addressIndex - (addressIndex % Iota._PRE_CALC_CHUNK_SIZE);
+        const offsetInChunk = addressIndex - chunkStart;
+        const publicKey = Converter.base64ToBytes(publicKeys[offsetInChunk]);
+        const keyName = Iota.buildAddressKeyName(identity, accountIndex, false, addressIndex);
+        return new VaultTransactionSigner(vaultConnector, keyName, publicKey);
     }
     /**
      * Create a new transaction instance.
@@ -156,13 +236,12 @@ export class Iota {
         if (Is.stringValue(options?.dryRunLabel)) {
             await Iota.dryRunTransaction(client, logging, transaction, owner, options.dryRunLabel);
         }
-        const seed = await Iota.getSeed(config, vaultConnector, identity);
-        const addressKeyPair = Iota.findAddress(config.maxAddressScanRange ?? Iota._DEFAULT_SCAN_RANGE, config.coinType ?? Iota.DEFAULT_COIN_TYPE, seed, owner);
-        const keypair = Ed25519Keypair.fromSecretKey(addressKeyPair.privateKey);
+        const { keyName, publicKey } = await Iota.ensureOwnerKey(vaultConnector, config, identity, owner);
+        const signer = new VaultSigner(vaultConnector, keyName, publicKey);
         try {
             const response = await client.signAndExecuteTransaction({
                 transaction,
-                signer: keypair,
+                signer,
                 requestType: "WaitForLocalExecution",
                 options: {
                     showEffects: options?.showEffects ?? true,
@@ -185,40 +264,6 @@ export class Iota {
             throw new GeneralError(Iota.CLASS_NAME, "transactionFailed", undefined, Iota.extractPayloadError(error));
         }
     }
-    /**
-     * Get the seed from the vault.
-     * @param config The configuration to use.
-     * @param vaultConnector The vault connector to use.
-     * @param identity The identity of the user to access the vault keys.
-     * @returns The seed.
-     */
-    static async getSeed(config, vaultConnector, identity) {
-        try {
-            const seedBase64 = await vaultConnector.getSecret(Iota.buildSeedKey(identity, config.vaultSeedId));
-            return Converter.base64ToBytes(seedBase64);
-        }
-        catch { }
-        const mnemonic = await vaultConnector.getSecret(Iota.buildMnemonicKey(identity, config.vaultMnemonicId));
-        return Bip39.mnemonicToSeed(mnemonic);
-    }
-    /**
-     * Find the address in the seed.
-     * @param maxScanRange The maximum range to scan.
-     * @param coinType The coin type to use.
-     * @param seed The seed to use.
-     * @param address The address to find.
-     * @returns The address key pair.
-     * @throws Error if the address is not found.
-     */
-    static findAddress(maxScanRange, coinType, seed, address) {
-        for (let i = 0; i < maxScanRange; i++) {
-            const addressKeyPair = Bip44.address(seed, KeyType.Ed25519, coinType, 0, false, i);
-            if (addressKeyPair.address === address) {
-                return addressKeyPair;
-            }
-        }
-        throw new GeneralError(Iota.CLASS_NAME, "addressNotFound", { address });
-    }
     /**
      * Extract error from SDK payload.
      * Errors from the IOTA SDK are usually not JSON strings but objects.
@@ -250,24 +295,6 @@ export class Iota {
         }
         return baseError;
     }
-    /**
-     * Get the key for storing the mnemonic.
-     * @param identity The identity to use.
-     * @param vaultMnemonicId The mnemonic ID to use.
-     * @returns The mnemonic key.
-     */
-    static buildMnemonicKey(identity, vaultMnemonicId) {
-        return `${identity}/${vaultMnemonicId ?? Iota.DEFAULT_MNEMONIC_SECRET_NAME}`;
-    }
-    /**
-     * Get the key for storing the seed.
-     * @param identity The identity to use.
-     * @param vaultSeedId The seed ID to use.
-     * @returns The seed key.
-     */
-    static buildSeedKey(identity, vaultSeedId) {
-        return `${identity}/${vaultSeedId ?? Iota.DEFAULT_SEED_SECRET_NAME}`;
-    }
     /**
      * Check if the package exists on the network.
      * @param client The client to use.
@@ -306,7 +333,7 @@ export class Iota {
      * @param txb The transaction to dry run.
      * @param sender The sender address.
      * @param operation The operation to log.
-     * @returns void.
+     * @returns The dry run result including status, costs, events, and object changes.
      */
     static async dryRunTransaction(client, logging, txb, sender, operation) {
         try {
@@ -387,11 +414,25 @@ export class Iota {
     static isAbortError(error, code) {
         const err = BaseError.fromError(error);
         if (Is.stringValue(err.properties?.error)) {
-            const abortCodeMatch = /abort\s+code\s*:\s*(\d+)/i.exec(err.properties.error);
+            const abortCodeMatch = /abort code\s*:\s*(\d+)/i.exec(err.properties.error);
             return abortCodeMatch?.[1] === code.toString();
         }
         return false;
     }
+    /**
+     * Extracts the abort code from a transaction result if the transaction was aborted.
+     * @param response The transaction result to extract the abort code from.
+     * @returns The abort code if the transaction was aborted, or undefined if it was not an abort error or the code could not be extracted.
+     */
+    static extractAbortCode(response) {
+        if (response.effects?.status?.status === "failure" &&
+            Is.stringValue(response.effects.status.error)) {
+            const match = /abort code: (\d+)/.exec(response.effects.status.error);
+            if (match) {
+                return Coerce.integer(match[1]);
+            }
+        }
+    }
     /**
      * Prepare and post a transaction using gas station sponsoring.
      * @param config The configuration.
@@ -407,20 +448,17 @@ export class Iota {
         Guards.object(Iota.CLASS_NAME, "config.gasStation", config.gasStation);
         try {
             // Reserve gas from the gas station
-            const gasBudget = config.gasBudget ?? 50000000;
-            const gasReservation = await Iota.reserveGas(config, gasBudget);
+            const gasReservation = await Iota.reserveGas(config);
             // Set transaction parameters for sponsoring
             transaction.setSender(owner);
             transaction.setGasOwner(gasReservation.sponsorAddress);
             transaction.setGasPayment(gasReservation.gasCoins);
-            transaction.setGasBudget(gasBudget);
+            transaction.setGasBudget(config.gasBudget ?? Iota._DEFAULT_GAS_BUDGET);
             // Build and sign transaction
             const unsignedTxBytes = await transaction.build({ client });
-            // Sign the transaction with the user's private key
-            const seed = await Iota.getSeed(config, vaultConnector, identity);
-            const addressKeyPair = Iota.findAddress(config.maxAddressScanRange ?? Iota._DEFAULT_SCAN_RANGE, config.coinType ?? Iota.DEFAULT_COIN_TYPE, seed, owner);
-            const keypair = Ed25519Keypair.fromSecretKey(addressKeyPair.privateKey);
-            const signature = await keypair.signTransaction(unsignedTxBytes);
+            const { keyName, publicKey } = await Iota.ensureOwnerKey(vaultConnector, config, identity, owner);
+            const signer = new VaultSigner(vaultConnector, keyName, publicKey);
+            const signature = await signer.signTransaction(unsignedTxBytes);
             return await Iota.executeAndConfirmGasStationTransaction(config, client, gasReservation.reservationId, unsignedTxBytes, signature.signature, options);
         }
         catch (error) {
@@ -430,16 +468,15 @@ export class Iota {
     /**
      * Reserve gas from the gas station.
      * @param config The configuration containing gas station settings.
-     * @param gasBudget The gas budget to reserve.
      * @returns The gas reservation result.
      */
-    static async reserveGas(config, gasBudget) {
+    static async reserveGas(config) {
         Guards.object(Iota.CLASS_NAME, "config.gasStation", config.gasStation);
         const requestData = {
             // eslint-disable-next-line camelcase
-            gas_budget: gasBudget,
+            gas_budget: config.gasBudget ?? Iota._DEFAULT_GAS_BUDGET,
             // eslint-disable-next-line camelcase
-            reserve_duration_secs: 30
+            reserve_duration_secs: config.gasReservationDuration ?? Iota._DEFAULT_GAS_RESERVATION_DURATION
         };
         const baseUrl = StringHelper.trimTrailingSlashes(config.gasStation.gasStationUrl);
         const result = await FetchHelper.fetchJson(Iota.CLASS_NAME, `${baseUrl}/v1/reserve_gas`, HttpMethod.POST, requestData, {
@@ -511,5 +548,231 @@ export class Iota {
         }
         return response;
     }
+    /**
+     * Fund an address with IOTA from the faucet.
+     * @param config The configuration containing endpoint information.
+     * @param faucetUrl The URL of the faucet to request funds from.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The address to fund.
+     * @param timeoutInSeconds The timeout in seconds to wait for the funding to complete.
+     * @returns The amount funded.
+     */
+    static async fundAddress(config, faucetUrl, identity, address, timeoutInSeconds = 60) {
+        Guards.objectValue(Iota.CLASS_NAME, "config", config);
+        Guards.stringValue(Iota.CLASS_NAME, "config.clientOptions.url", config.clientOptions.url);
+        Guards.stringValue(Iota.CLASS_NAME, "faucetUrl", faucetUrl);
+        Guards.stringValue(Iota.CLASS_NAME, "identity", identity);
+        Guards.stringValue(Iota.CLASS_NAME, "address", address);
+        try {
+            const initialBalance = await Iota.getBalance(config, address);
+            const response = await requestIotaFromFaucetV0({
+                host: faucetUrl,
+                recipient: address
+            });
+            if (response?.error) {
+                throw new GeneralError(Iota.CLASS_NAME, "fundingFailed", undefined, response.error);
+            }
+            // Poll for balance change
+            const numTries = Math.ceil(timeoutInSeconds / 5);
+            for (let i = 0; i < numTries; i++) {
+                const newBalance = await Iota.getBalance(config, address);
+                if (newBalance > initialBalance) {
+                    return newBalance - initialBalance;
+                }
+                if (i < numTries - 1) {
+                    await new Promise(resolve => setTimeout(resolve, 5000));
+                }
+            }
+        }
+        catch (error) {
+            const payloadError = Iota.extractPayloadError(error);
+            if (payloadError.message.includes("Too many requests from this client have been sent to the faucet")) {
+                throw new GeneralError(Iota.CLASS_NAME, "faucetRateLimit", undefined, Iota.extractPayloadError(error));
+            }
+            throw new GeneralError(Iota.CLASS_NAME, "fundingFailed", undefined, Iota.extractPayloadError(error));
+        }
+        return 0n;
+    }
+    /**
+     * Ensure the balance for the given address is at least the given amount.
+     * @param config The configuration containing endpoint information.
+     * @param faucetUrl The URL of the faucet to request funds from.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The address to ensure the balance for.
+     * @param ensureBalance The minimum balance to ensure.
+     * @param timeoutInSeconds Optional timeout in seconds, defaults to 10 seconds.
+     * @returns True if the balance is at least the given amount, false otherwise.
+     */
+    static async ensureBalance(config, faucetUrl, identity, address, ensureBalance, timeoutInSeconds) {
+        Guards.objectValue(Iota.CLASS_NAME, "config", config);
+        Guards.stringValue(Iota.CLASS_NAME, "config.clientOptions.url", config.clientOptions.url);
+        Guards.stringValue(Iota.CLASS_NAME, "identity", identity);
+        Guards.stringValue(Iota.CLASS_NAME, "address", address);
+        Guards.bigint(Iota.CLASS_NAME, "ensureBalance", ensureBalance);
+        let currentBalance = await Iota.getBalance(config, address);
+        if (Is.stringValue(faucetUrl)) {
+            let retryCount = 10;
+            while (currentBalance < ensureBalance && retryCount > 0) {
+                const addedBalance = await Iota.fundAddress(config, faucetUrl, identity, address, timeoutInSeconds);
+                if (addedBalance === 0n) {
+                    return false;
+                }
+                currentBalance += addedBalance;
+                if (currentBalance < ensureBalance) {
+                    await new Promise(resolve => setTimeout(resolve, 1000));
+                    retryCount--;
+                }
+            }
+        }
+        return currentBalance >= ensureBalance;
+    }
+    /**
+     * Get the balance for the given address.
+     * @param config The configuration containing endpoint information.
+     * @param address The address to get the balance for.
+     * @returns The balance of the given address.
+     */
+    static async getBalance(config, address) {
+        Guards.objectValue(Iota.CLASS_NAME, "config", config);
+        Guards.stringValue(Iota.CLASS_NAME, "config.clientOptions.url", config.clientOptions.url);
+        Guards.stringValue(Iota.CLASS_NAME, "address", address);
+        const client = Iota.createClient(config);
+        const balance = await client.getBalance({
+            owner: address
+        });
+        return BigInt(balance.totalBalance);
+    }
+    /**
+     * Create a transaction instance from the given bytes.
+     * @param bytes The transaction bytes to create the transaction from.
+     * @returns The transaction instance created from the given bytes.
+     */
+    static transactionFromBytes(bytes) {
+        return Transaction.from(bytes);
+    }
+    /**
+     * Find the vault key name and public key for the given owner address.
+     * Keys are individually registered in the vault by buildKeyPairRange, so no addKey is needed here.
+     * @param vaultConnector The vault connector to use.
+     * @param config The configuration to use.
+     * @param identity The identity of the user to access the vault keys.
+     * @param owner The owner address whose key should be located.
+     * @param accountIndex The account index to search.
+     * @returns The vault key name and the public key bytes.
+     * @internal
+     */
+    static async ensureOwnerKey(vaultConnector, config, identity, owner, accountIndex = 0) {
+        const scanRange = config.maxAddressScanRange ?? Iota._DEFAULT_SCAN_RANGE;
+        let cachedSeed;
+        const seedProvider = async () => {
+            cachedSeed ??= await Iota.getSeed(vaultConnector, config, identity);
+            return cachedSeed;
+        };
+        for (let chunkStart = 0; chunkStart < scanRange; chunkStart += Iota._PRE_CALC_CHUNK_SIZE) {
+            const publicKeys = await Iota.getPublicKeys(vaultConnector, config, identity, accountIndex, false, chunkStart, seedProvider);
+            const matchIndex = publicKeys.findIndex((pk) => Iota.publicKeyToAddress(Converter.base64ToBytes(pk)) === owner);
+            if (matchIndex >= 0) {
+                const addressIndex = chunkStart + matchIndex;
+                return {
+                    keyName: Iota.buildAddressKeyName(identity, accountIndex, false, addressIndex),
+                    publicKey: Converter.base64ToBytes(publicKeys[matchIndex])
+                };
+            }
+        }
+        throw new GeneralError(Iota.CLASS_NAME, "addressNotFound", { address: owner });
+    }
+    /**
+     * Get the seed from the vault, deriving it from the mnemonic if necessary.
+     * @param vaultConnector The vault connector to use.
+     * @param config The configuration to use.
+     * @param identity The identity of the user to access the vault keys.
+     * @returns The seed bytes.
+     * @internal
+     */
+    static async getSeed(vaultConnector, config, identity) {
+        const seedKey = Iota.buildSeedKey(identity, config.vaultSeedId);
+        try {
+            const seedBase64 = await vaultConnector.getSecret(seedKey);
+            return Converter.base64ToBytes(seedBase64);
+        }
+        catch { }
+        const mnemonic = await vaultConnector.getSecret(Iota.buildMnemonicKey(identity, config.vaultMnemonicId));
+        // If the seed is not found but the mnemonic exists, derive the seed and store it for future use
+        const seed = Bip39.mnemonicToSeed(mnemonic);
+        await vaultConnector.setSecret(seedKey, Converter.bytesToBase64(seed));
+        return seed;
+    }
+    /**
+     * Get the key for storing the mnemonic.
+     * @param identity The identity to use.
+     * @param vaultMnemonicId The mnemonic ID to use.
+     * @returns The mnemonic key.
+     * @internal
+     */
+    static buildMnemonicKey(identity, vaultMnemonicId) {
+        return VaultConnectorHelper.buildKeyName(identity, vaultMnemonicId ?? Iota.DEFAULT_MNEMONIC_SECRET_NAME);
+    }
+    /**
+     * Get the key for storing the seed.
+     * @param identity The identity to use.
+     * @param vaultSeedId The seed ID to use.
+     * @returns The seed key.
+     * @internal
+     */
+    static buildSeedKey(identity, vaultSeedId) {
+        return VaultConnectorHelper.buildKeyName(identity, vaultSeedId ?? Iota.DEFAULT_SEED_SECRET_NAME);
+    }
+    /**
+     * Ensure a range of BIP44-derived keys are registered as individual vault keys and return their public keys.
+     * If the first key of the range already exists the range is considered registered and only public keys are derived.
+     * If not registered, all keys are derived and added to the vault before returning the public keys.
+     * @param vaultConnector The vault connector to use.
+     * @param config The configuration to use.
+     * @param identity The identity of the user to access the vault keys.
+     * @param accountIndex The account index.
+     * @param internal Whether the addresses are internal or external.
+     * @param addressIndex Any address index within the desired chunk; aligned internally.
+     * @param seedProvider Callback invoked at most once per call to supply the seed when a chunk is not yet registered.
+     * @returns The base64-encoded public keys for each address in the range.
+     * @internal
+     */
+    static async getPublicKeys(vaultConnector, config, identity, accountIndex, internal, addressIndex, seedProvider) {
+        const chunkStart = addressIndex - (addressIndex % Iota._PRE_CALC_CHUNK_SIZE);
+        const firstKeyName = Iota.buildAddressKeyName(identity, accountIndex, internal, chunkStart);
+        const publicKeys = [];
+        if (await vaultConnector.keyExists(firstKeyName)) {
+            for (let i = chunkStart; i < chunkStart + Iota._PRE_CALC_CHUNK_SIZE; i++) {
+                const keyName = Iota.buildAddressKeyName(identity, accountIndex, internal, i);
+                const keyData = await vaultConnector.getKey(keyName, "public");
+                if (!keyData.publicKey) {
+                    throw new GeneralError(Iota.CLASS_NAME, "missingPublicKey", { keyName });
+                }
+                publicKeys.push(Converter.bytesToBase64(keyData.publicKey));
+            }
+        }
+        else {
+            const seed = await seedProvider();
+            const coinType = config.coinType ?? Iota.DEFAULT_COIN_TYPE;
+            for (let i = chunkStart; i < chunkStart + Iota._PRE_CALC_CHUNK_SIZE; i++) {
+                const keyName = Iota.buildAddressKeyName(identity, accountIndex, internal, i);
+                const keyPair = Bip44.keyPair(seed, KeyType.Ed25519, coinType, accountIndex, internal, i);
+                await vaultConnector.addKey(keyName, VaultKeyType.Ed25519, keyPair.privateKey, keyPair.publicKey);
+                publicKeys.push(Converter.bytesToBase64(keyPair.publicKey));
+            }
+        }
+        return publicKeys;
+    }
+    /**
+     * Build the vault key name for a specific derived address.
+     * @param identity The identity to use.
+     * @param accountIndex The account index.
+     * @param internal Whether the address is internal or external.
+     * @param addressIndex The address index.
+     * @returns The vault key name.
+     * @internal
+     */
+    static buildAddressKeyName(identity, accountIndex, internal, addressIndex) {
+        return VaultConnectorHelper.buildKeyName(identity, "account", accountIndex.toString(), internal ? "1" : "0", `${addressIndex}`);
+    }
 }
 //# sourceMappingURL=iota.js.map