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

package/README.md

@@ -1,6 +1,6 @@
 # TWIN DLT IOTA
 
-DLT helpers for use with IOTA.
+This package provides utilities for integrating applications with IOTA distributed ledger capabilities, including client construction, transaction submission, sponsored transaction support, and smart contract migration helpers. It is intended for services that need a reliable and repeatable approach to ledger operations without rebuilding common primitives.
 
 ## Installation
 
@@ -8,14 +8,12 @@ DLT helpers for use with IOTA.
 npm install @twin.org/dlt-iota
 ```
 
-## Testing
+## Docker
 
-The tests developed are functional tests and need an instance of the IOTA Gas Station and Redis up and running.
-
-The simplest way to set up the testing environment using our unified container:
+To perform testing of this component it may be necessary to launch a local instance of the gas station to communicate with.
 
 ```shell
-docker run -d --name twin-gas-station-test -p 9527:9527 -p 6379:6379 -p 9184:9184 twinfoundation/twin-gas-station-test:latest
+docker run -d --name twin-gas-station-test -p 6379:6379 -p 9527:9527 -p 9184:9184 -e IOTA_NODE_URL="https://api.testnet.iota.cafe" -e GAS_STATION_AUTH="qEyCL6d9BKKFl/tfDGAKeGFkhUlf7FkqiGV7Xw4JUsI=" twinfoundation/twin-gas-station-test:latest
 ```
 
 ## Examples

package/dist/es/index.js

@@ -1,6 +1,7 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 export * from "./iota.js";
+export * from "./iotaIdentityUtils.js";
 export * from "./iotaSmartContractUtils.js";
 export * from "./models/IAdminCapFields.js";
 export * from "./models/IContractData.js";
@@ -9,6 +10,10 @@ export * from "./models/IGasStationConfig.js";
 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/IIotaDryRun.js";
 export * from "./models/IIotaResponseOptions.js";

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,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,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 \"./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/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,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"]}

package/dist/es/iota.js

@@ -1,10 +1,11 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 import { IotaClient } from "@iota/iota-sdk/client";
+import { requestIotaFromFaucetV0 } from "@iota/iota-sdk/faucet";
 import { Ed25519Keypair } from "@iota/iota-sdk/keypairs/ed25519";
 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 { FetchHelper, HttpMethod } from "@twin.org/web";
 /**
  * Class for performing operations on IOTA.
@@ -22,18 +23,25 @@ export class Iota {
      * Default coin type.
      */
     static DEFAULT_COIN_TYPE = 4218;
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "Iota";
     /**
      * Default scan range.
+     * @internal
      */
-    static DEFAULT_SCAN_RANGE = 1000;
+    static _DEFAULT_SCAN_RANGE = 1000;
     /**
-     * Default inclusion timeout.
+     * Default pre-calculation chunk size.
+     * @internal
      */
-    static DEFAULT_INCLUSION_TIMEOUT = 60;
+    static _PRE_CALC_CHUNK_SIZE = 25;
     /**
-     * Runtime name for the class.
+     * Default inclusion timeout.
+     * @internal
      */
-    static CLASS_NAME = "Iota";
+    static _DEFAULT_INCLUSION_TIMEOUT = 60;
     /**
      * Create a new IOTA client.
      * @param config The configuration.
@@ -54,47 +62,115 @@ export class Iota {
         config.vaultMnemonicId ??= Iota.DEFAULT_MNEMONIC_SECRET_NAME;
         config.vaultSeedId ??= Iota.DEFAULT_SEED_SECRET_NAME;
         config.coinType ??= Iota.DEFAULT_COIN_TYPE;
-        config.inclusionTimeoutSeconds ??= Iota.DEFAULT_INCLUSION_TIMEOUT;
+        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.buildKeyPairRange(vaultConnector, config, identity, accountIndex, false, 0);
+        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;
+        while (addresses.length < count) {
+            const chunkStart = Math.floor(currentIndex / Iota._PRE_CALC_CHUNK_SIZE) * Iota._PRE_CALC_CHUNK_SIZE;
+            const keyPairs = await Iota.buildKeyPairRange(vaultConnector, config, identity, accountIndex, internal, chunkStart);
+            const chunk = keyPairs.map(kp => Iota.publicKeyToAddress(Converter.base64ToBytes(kp.publicKey)));
+            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 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 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.
      */
-    static getKeyPair(seed, coinType, accountIndex, addressIndex, isInternal) {
-        Guards.integer(Iota.CLASS_NAME, "coinType", coinType);
+    static async getKeyPair(vaultConnector, config, identity, accountIndex, addressIndex, 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, "addressIndex", addressIndex);
-        const keyPair = Bip44.keyPair(seed, KeyType.Ed25519, coinType ?? Iota.DEFAULT_COIN_TYPE, accountIndex, isInternal ?? false, addressIndex);
-        return keyPair;
+        const internal = isInternal ?? false;
+        const chunkStart = Math.floor(addressIndex / Iota._PRE_CALC_CHUNK_SIZE) * Iota._PRE_CALC_CHUNK_SIZE;
+        const keyPairs = await Iota.buildKeyPairRange(vaultConnector, config, identity, accountIndex, internal, chunkStart);
+        const offsetInChunk = addressIndex - chunkStart;
+        const entry = keyPairs[offsetInChunk];
+        return {
+            privateKey: Converter.base64ToBytes(entry.privateKey),
+            publicKey: Converter.base64ToBytes(entry.publicKey)
+        };
+    }
+    /**
+     * Create a new transaction instance.
+     * @returns A new transaction instance.
+     */
+    static createTransaction() {
+        return new Transaction();
     }
     /**
      * Prepare and post a transaction.
@@ -147,8 +223,7 @@ 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 addressKeyPair = await Iota.findAddress(vaultConnector, config, identity, owner, 0);
         const keypair = Ed25519Keypair.fromSecretKey(addressKeyPair.privateKey);
         try {
             const response = await client.signAndExecuteTransaction({
@@ -177,35 +252,32 @@ export class Iota {
         }
     }
     /**
-     * Get the seed from the vault.
-     * @param config The configuration to use.
+     * Find the address in the seed.
      * @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.
-     */
-    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.
+     * @param accountIndex The account index to search.
+     * @param isInternal Whether to search internal addresses.
+     * @param startScanIndex The address index to start scanning from.
+     * @param maxScanRange The maximum range to scan.
      * @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;
+    static async findAddress(vaultConnector, config, identity, address, accountIndex, isInternal, startScanIndex, maxScanRange) {
+        const internal = isInternal ?? false;
+        const startIndex = startScanIndex ?? 0;
+        const scanRange = maxScanRange ?? config.maxAddressScanRange ?? Iota._DEFAULT_SCAN_RANGE;
+        for (let chunkStart = startIndex; chunkStart < startIndex + scanRange; chunkStart += Iota._PRE_CALC_CHUNK_SIZE) {
+            const keyPairs = await Iota.buildKeyPairRange(vaultConnector, config, identity, accountIndex, internal, chunkStart);
+            const offsetInChunk = keyPairs.findIndex(kp => Iota.publicKeyToAddress(Converter.base64ToBytes(kp.publicKey)) === address);
+            if (offsetInChunk !== -1) {
+                const entry = keyPairs[offsetInChunk];
+                return {
+                    address,
+                    privateKey: Converter.base64ToBytes(entry.privateKey),
+                    publicKey: Converter.base64ToBytes(entry.publicKey)
+                };
             }
         }
         throw new GeneralError(Iota.CLASS_NAME, "addressNotFound", { address });
@@ -241,24 +313,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.
@@ -358,7 +412,7 @@ export class Iota {
      * @returns The confirmed transaction response.
      */
     static async waitForTransactionConfirmation(client, digest, config, options) {
-        const timeoutMs = (config.inclusionTimeoutSeconds ?? Iota.DEFAULT_INCLUSION_TIMEOUT) * 1000;
+        const timeoutMs = (config.inclusionTimeoutSeconds ?? Iota._DEFAULT_INCLUSION_TIMEOUT) * 1000;
         return client.waitForTransaction({
             digest,
             timeout: timeoutMs,
@@ -370,21 +424,33 @@ export class Iota {
         });
     }
     /**
-     * Check if the error is an abort error.
+     * Check if the error is an abort error with a specific code.
      * @param error The error to check.
      * @param code The error code to check for.
      * @returns True if the error is an abort error, false otherwise.
      */
     static isAbortError(error, code) {
         const err = BaseError.fromError(error);
-        if (Is.stringValue(err.properties?.error) && err.properties.error.startsWith("MoveAbort")) {
-            if (Is.number(code)) {
-                return err.properties.error.includes(code.toString());
-            }
-            return true;
+        if (Is.stringValue(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.
@@ -410,8 +476,7 @@ export class Iota {
             // 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 addressKeyPair = await Iota.findAddress(vaultConnector, config, identity, owner, 0);
             const keypair = Ed25519Keypair.fromSecretKey(addressKeyPair.privateKey);
             const signature = await keypair.signTransaction(unsignedTxBytes);
             return await Iota.executeAndConfirmGasStationTransaction(config, client, gasReservation.reservationId, unsignedTxBytes, signature.signature, options);
@@ -504,5 +569,187 @@ 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);
+    }
+    /**
+     * Get the seed from the vault.
+     * @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.
+     * @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 `${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 `${identity}/${vaultSeedId ?? Iota.DEFAULT_SEED_SECRET_NAME}`;
+    }
+    /**
+     * Build a chunk of key pairs from vault cache or derived from seed.
+     * @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 The starting address index.
+     * @returns The key pairs for the chunk.
+     * @internal
+     */
+    static async buildKeyPairRange(vaultConnector, config, identity, accountIndex, internal, addressIndex) {
+        const keyPairChunkKey = Iota.buildKeyPairChunkKey(identity, accountIndex, internal, addressIndex);
+        let keyPairChunk;
+        try {
+            keyPairChunk =
+                await vaultConnector.getSecret(keyPairChunkKey);
+        }
+        catch { }
+        if (Is.empty(keyPairChunk)) {
+            const startChunkIndex = addressIndex % Iota._PRE_CALC_CHUNK_SIZE;
+            const endChunkIndex = startChunkIndex + Iota._PRE_CALC_CHUNK_SIZE;
+            const seed = await Iota.getSeed(vaultConnector, config, identity);
+            keyPairChunk = [];
+            for (let i = startChunkIndex; i < endChunkIndex; i++) {
+                const keyPair = Bip44.keyPair(seed, KeyType.Ed25519, config.coinType ?? Iota.DEFAULT_COIN_TYPE, accountIndex, internal, i);
+                keyPairChunk.push({
+                    privateKey: Converter.bytesToBase64(keyPair.privateKey),
+                    publicKey: Converter.bytesToBase64(keyPair.publicKey)
+                });
+            }
+            await vaultConnector.setSecret(keyPairChunkKey, keyPairChunk);
+        }
+        return keyPairChunk;
+    }
+    /**
+     * Get the key for storing a keypair chunk.
+     * @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 to determine the chunk.
+     * @returns The keypair chunk key.
+     * @internal
+     */
+    static buildKeyPairChunkKey(identity, accountIndex, internal, addressIndex) {
+        return `${identity}/keypair/${accountIndex}/${internal ? "internal" : "external"}/${addressIndex % Iota._PRE_CALC_CHUNK_SIZE}`;
+    }
 }
 //# sourceMappingURL=iota.js.map