@twin.org/dlt-iota 0.0.3-next.14 → 0.0.3-next.15

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

@@ -2,11 +2,13 @@
 // 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, 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.
  */
@@ -92,7 +94,7 @@ export class Iota {
         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);
+        await Iota.getPublicKeys(vaultConnector, config, identity, accountIndex, false, 0, async () => seed);
         return mnemonicToStore;
     }
     /**
@@ -138,10 +140,15 @@ export class Iota {
         const addresses = [];
         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 keyPairs = await Iota.buildKeyPairRange(vaultConnector, config, identity, accountIndex, internal, chunkStart);
-            const chunk = keyPairs.map(kp => Iota.publicKeyToAddress(Converter.base64ToBytes(kp.publicKey)));
+            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));
@@ -150,30 +157,26 @@ export class Iota {
         return addresses;
     }
     /**
-     * Get a key pair for the specified index.
+     * 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 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.
+     * @param accountIndex The account index.
+     * @param addressIndex The address index within the account.
+     * @returns A VaultTransactionSigner for the specified key.
      */
-    static async getKeyPair(vaultConnector, config, identity, accountIndex, addressIndex, isInternal) {
+    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 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 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 entry = keyPairs[offsetInChunk];
-        return {
-            privateKey: Converter.base64ToBytes(entry.privateKey),
-            publicKey: Converter.base64ToBytes(entry.publicKey)
-        };
+        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.
@@ -233,12 +236,12 @@ export class Iota {
         if (Is.stringValue(options?.dryRunLabel)) {
             await Iota.dryRunTransaction(client, logging, transaction, owner, options.dryRunLabel);
         }
-        const addressKeyPair = await Iota.findAddress(vaultConnector, config, identity, owner, 0);
-        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,
@@ -261,37 +264,6 @@ export class Iota {
             throw new GeneralError(Iota.CLASS_NAME, "transactionFailed", undefined, Iota.extractPayloadError(error));
         }
     }
-    /**
-     * 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.
-     * @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 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 });
-    }
     /**
      * Extract error from SDK payload.
      * Errors from the IOTA SDK are usually not JSON strings but objects.
@@ -484,10 +456,9 @@ export class Iota {
             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 addressKeyPair = await Iota.findAddress(vaultConnector, config, identity, owner, 0);
-            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) {
@@ -672,11 +643,50 @@ export class Iota {
         return BigInt(balance.totalBalance);
     }
     /**
-     * Get the seed from the vault.
+     * 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.
-     * @returns The seed.
+     * @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) {
@@ -700,7 +710,7 @@ export class Iota {
      * @internal
      */
     static buildMnemonicKey(identity, vaultMnemonicId) {
-        return `${identity}/${vaultMnemonicId ?? Iota.DEFAULT_MNEMONIC_SECRET_NAME}`;
+        return VaultConnectorHelper.buildKeyName(identity, vaultMnemonicId ?? Iota.DEFAULT_MNEMONIC_SECRET_NAME);
     }
     /**
      * Get the key for storing the seed.
@@ -710,54 +720,59 @@ export class Iota {
      * @internal
      */
     static buildSeedKey(identity, vaultSeedId) {
-        return `${identity}/${vaultSeedId ?? Iota.DEFAULT_SEED_SECRET_NAME}`;
+        return VaultConnectorHelper.buildKeyName(identity, vaultSeedId ?? Iota.DEFAULT_SEED_SECRET_NAME);
     }
     /**
-     * Build a chunk of key pairs from vault cache or derived from seed.
+     * 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 The starting address index.
-     * @returns The key pairs for the chunk.
+     * @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 buildKeyPairRange(vaultConnector, config, identity, accountIndex, internal, addressIndex) {
-        const keyPairChunkKey = Iota.buildAccountChunkKey(identity, accountIndex, internal, addressIndex);
-        let keyPairChunk;
-        try {
-            keyPairChunk =
-                await vaultConnector.getSecret(keyPairChunkKey);
+    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));
+            }
         }
-        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)
-                });
+        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));
             }
-            await vaultConnector.setSecret(keyPairChunkKey, keyPairChunk);
         }
-        return keyPairChunk;
+        return publicKeys;
     }
     /**
-     * Get the key for storing a keypair chunk.
+     * 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 to determine the chunk.
-     * @returns The keypair chunk key.
+     * @param addressIndex The address index.
+     * @returns The vault key name.
      * @internal
      */
-    static buildAccountChunkKey(identity, accountIndex, internal, addressIndex) {
-        return `${identity}/account/${accountIndex}/${internal ? "1" : "0"}/${addressIndex % Iota._PRE_CALC_CHUNK_SIZE}`;
+    static buildAddressKeyName(identity, accountIndex, internal, addressIndex) {
+        return VaultConnectorHelper.buildKeyName(identity, "account", accountIndex.toString(), internal ? "1" : "0", `${addressIndex}`);
     }
 }
 //# sourceMappingURL=iota.js.map