@twin.org/wallet-connector-entity-storage 0.0.1-next.3

package/dist/esm/index.mjs

@@ -0,0 +1,308 @@
+import { property, entity, LogicalOperator, ComparisonOperator, EntitySchemaFactory, EntitySchemaHelper } from '@twin.org/entity';
+import { Guards, Is, Coerce, GeneralError } from '@twin.org/core';
+import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
+import { Bip39, Bip44, KeyType } from '@twin.org/crypto';
+import { VaultConnectorFactory } from '@twin.org/vault-models';
+import { FaucetConnectorFactory } from '@twin.org/wallet-models';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class describing a wallet address.
+ */
+let WalletAddress = class WalletAddress {
+    /**
+     * The address in the wallet.
+     */
+    address;
+    /**
+     * The identity of the owner.
+     */
+    identity;
+    /**
+     * The balance of the wallet as bigint.
+     */
+    balance;
+};
+__decorate([
+    property({ type: "string", isPrimary: true }),
+    __metadata("design:type", String)
+], WalletAddress.prototype, "address", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], WalletAddress.prototype, "identity", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], WalletAddress.prototype, "balance", void 0);
+WalletAddress = __decorate([
+    entity()
+], WalletAddress);
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class for performing faucet operations using entity storage.
+ */
+class EntityStorageFaucetConnector {
+    /**
+     * The namespace supported by the wallet connector.
+     */
+    static NAMESPACE = "entity-storage";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "EntityStorageFaucetConnector";
+    /**
+     * The entity storage for wallets.
+     * @internal
+     */
+    _walletAddressEntityStorage;
+    /**
+     * Create a new instance of EntityStorageFaucetConnector.
+     * @param options The options for the wallet connector.
+     * @param options.walletAddressEntityStorageType The entity storage type for wallet addresses, defaults to "wallet-address".
+     */
+    constructor(options) {
+        this._walletAddressEntityStorage = EntityStorageConnectorFactory.get(options?.walletAddressEntityStorageType ?? "wallet-address");
+    }
+    /**
+     * Fund the wallet from the faucet.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The bech32 encoded address of the address to fund.
+     * @param timeoutInSeconds The timeout in seconds to wait for the funding to complete.
+     * @returns The amount added to the address by the faucet.
+     */
+    async fundAddress(identity, address, timeoutInSeconds = 60) {
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        Guards.stringValue(this.CLASS_NAME, "address", address);
+        let walletAddress = await this._walletAddressEntityStorage.get(address);
+        if (Is.empty(walletAddress)) {
+            walletAddress = {
+                balance: "0",
+                identity,
+                address
+            };
+        }
+        const maxFundAmount = 1000000000n;
+        const balance = Coerce.bigint(walletAddress.balance) ?? 0n;
+        walletAddress.balance = (balance + maxFundAmount).toString();
+        await this._walletAddressEntityStorage.set(walletAddress);
+        return maxFundAmount;
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class for performing wallet operations using in-memory storage.
+ */
+class EntityStorageWalletConnector {
+    /**
+     * The namespace supported by the wallet connector.
+     */
+    static NAMESPACE = "entity-storage";
+    /**
+     * Default name for the mnemonic secret.
+     * @internal
+     */
+    static _DEFAULT_MNEMONIC_SECRET_NAME = "mnemonic";
+    /**
+     * Default coin type.
+     * @internal
+     */
+    static _DEFAULT_COIN_TYPE = 9999;
+    /**
+     * Default bech32 hrp.
+     * @internal
+     */
+    static _DEFAULT_BECH32_HRP = "ent";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "EntityStorageWalletConnector";
+    /**
+     * The vault for the mnemonic.
+     * @internal
+     */
+    _vaultConnector;
+    /**
+     * The faucet.
+     * @internal
+     */
+    _faucetConnector;
+    /**
+     * The entity storage for wallets.
+     * @internal
+     */
+    _walletAddressEntityStorage;
+    /**
+     * The configuration to use for tangle operations.
+     * @internal
+     */
+    _config;
+    /**
+     * Create a new instance of EntityStorageWalletConnector.
+     * @param options The options for the wallet connector.
+     * @param options.vaultConnectorType Vault connector to use for wallet secrets, defaults to "vault".
+     * @param options.faucetConnectorType Optional faucet for requesting funds, defaults to "faucet".
+     * @param options.walletAddressEntityStorageType The entity storage for wallets, defaults to "wallet-address".
+     * @param options.config The configuration to use.
+     */
+    constructor(options) {
+        this._vaultConnector = VaultConnectorFactory.get(options?.vaultConnectorType ?? "vault");
+        this._faucetConnector = FaucetConnectorFactory.getIfExists(options?.faucetConnectorType ?? "faucet");
+        this._walletAddressEntityStorage = EntityStorageConnectorFactory.get(options?.walletAddressEntityStorageType ?? "wallet-address");
+        this._config = options?.config ?? {};
+        this._config.coinType ??= EntityStorageWalletConnector._DEFAULT_COIN_TYPE;
+        this._config.bech32Hrp ??= EntityStorageWalletConnector._DEFAULT_BECH32_HRP;
+    }
+    /**
+     * Create a new wallet.
+     * @param identity The identity of the user to access the vault keys.
+     * @returns Nothing.
+     */
+    async create(identity) {
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        const mnemonic = Bip39.randomMnemonic();
+        await this._vaultConnector.setSecret(this.buildMnemonicKey(identity), mnemonic);
+    }
+    /**
+     * Get the addresses for the requested range.
+     * @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.
+     * @returns The list of addresses.
+     */
+    async getAddresses(identity, accountIndex, startAddressIndex, count) {
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        Guards.integer(this.CLASS_NAME, "startAddressIndex", startAddressIndex);
+        Guards.integer(this.CLASS_NAME, "count", count);
+        const mnemonic = await this._vaultConnector.getSecret(this.buildMnemonicKey(identity));
+        const seed = Bip39.mnemonicToSeed(mnemonic);
+        const keyPairs = [];
+        for (let i = startAddressIndex; i < startAddressIndex + count; i++) {
+            const addressKeyPair = Bip44.addressBech32(seed, KeyType.Ed25519, this._config.bech32Hrp ?? EntityStorageWalletConnector._DEFAULT_BECH32_HRP, this._config.coinType ?? EntityStorageWalletConnector._DEFAULT_COIN_TYPE, accountIndex, false, i);
+            keyPairs.push(addressKeyPair.address);
+        }
+        return keyPairs;
+    }
+    /**
+     * Get the balance for an address in a wallet.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The bech32 encoded address.
+     * @returns The balance of the wallet address.
+     */
+    async getBalance(identity, address) {
+        Guards.stringValue(this.CLASS_NAME, "address", address);
+        const walletAddress = await this._walletAddressEntityStorage.get(address);
+        return Coerce.bigint(walletAddress?.balance) ?? 0n;
+    }
+    /**
+     * Ensure the balance for an address in a wallet.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The bech32 encoded address.
+     * @param ensureBalance The balance to ensure on the address.
+     * @param timeoutInSeconds The timeout in seconds to wait for the funding to complete.
+     * @returns True if the balance has been ensured.
+     */
+    async ensureBalance(identity, address, ensureBalance, timeoutInSeconds) {
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        Guards.stringValue(this.CLASS_NAME, "address", address);
+        Guards.bigint(this.CLASS_NAME, "ensureBalance", ensureBalance);
+        if (this._faucetConnector) {
+            let retryCount = 10;
+            let currentBalance = await this.getBalance(identity, address);
+            while (currentBalance < ensureBalance && retryCount > 0) {
+                const addedBalance = await this._faucetConnector.fundAddress(identity, address, timeoutInSeconds);
+                if (addedBalance === 0n) {
+                    // The balance has not increased, so return.
+                    return false;
+                }
+                currentBalance += addedBalance;
+                if (currentBalance < ensureBalance) {
+                    // The balance has increased but is still not enough, wait and try again.
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                    retryCount--;
+                }
+            }
+            return currentBalance >= ensureBalance;
+        }
+        return false;
+    }
+    /**
+     * Transfer funds to an address.
+     * @param identity The identity of the user to access the vault keys.
+     * @param addressSource The bech32 encoded address to send the funds from.
+     * @param addressDest The bech32 encoded address to send the funds to.
+     * @param amount The amount to transfer.
+     * @returns An identifier for the transfer if there was one.
+     */
+    async transfer(identity, addressSource, addressDest, amount) {
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        Guards.stringValue(this.CLASS_NAME, "addressSource", addressSource);
+        Guards.stringValue(this.CLASS_NAME, "addressDest", addressDest);
+        Guards.bigint(this.CLASS_NAME, "amount", amount);
+        const walletAddresses = await this._walletAddressEntityStorage.query({
+            logicalOperator: LogicalOperator.And,
+            conditions: [
+                {
+                    property: "identity",
+                    comparison: ComparisonOperator.Equals,
+                    value: identity
+                },
+                {
+                    property: "address",
+                    comparison: ComparisonOperator.Equals,
+                    value: addressSource
+                }
+            ]
+        });
+        let walletAddress;
+        let balance = 0n;
+        if (walletAddresses.entities.length > 0) {
+            walletAddress = walletAddresses.entities[0];
+            balance = BigInt(walletAddress.balance);
+            walletAddress.balance = (BigInt(walletAddress.balance) - amount).toString();
+        }
+        if (balance < amount) {
+            throw new GeneralError(this.CLASS_NAME, "insufficientFunds");
+        }
+        if (!Is.empty(walletAddress)) {
+            await this._walletAddressEntityStorage.set(walletAddress);
+            let destWalletAddress = await this._walletAddressEntityStorage.get(addressDest);
+            if (Is.empty(destWalletAddress)) {
+                destWalletAddress = {
+                    balance: "0",
+                    identity: "",
+                    address: addressDest
+                };
+            }
+            destWalletAddress.balance = (BigInt(destWalletAddress.balance) + amount).toString();
+            await this._walletAddressEntityStorage.set(destWalletAddress);
+        }
+        return undefined;
+    }
+    /**
+     * Build the key name to access the mnemonic in the vault.
+     * @param identity The identity of the user to access the vault keys.
+     * @returns The vault key.
+     * @internal
+     */
+    buildMnemonicKey(identity) {
+        return `${identity}/${this._config.vaultMnemonicId ?? EntityStorageWalletConnector._DEFAULT_MNEMONIC_SECRET_NAME}`;
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Initialize the schema for the wallet entity storage connector.
+ */
+function initSchema() {
+    EntitySchemaFactory.register("WalletAddress", () => EntitySchemaHelper.getSchema(WalletAddress));
+}
+
+export { EntityStorageFaucetConnector, EntityStorageWalletConnector, WalletAddress, initSchema };

package/dist/types/entities/walletAddress.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Class describing a wallet address.
+ */
+export declare class WalletAddress {
+    /**
+     * The address in the wallet.
+     */
+    address: string;
+    /**
+     * The identity of the owner.
+     */
+    identity: string;
+    /**
+     * The balance of the wallet as bigint.
+     */
+    balance: string;
+}

package/dist/types/entityStorageFaucetConnector.d.ts

@@ -0,0 +1,30 @@
+import type { IFaucetConnector } from "@twin.org/wallet-models";
+/**
+ * Class for performing faucet operations using entity storage.
+ */
+export declare class EntityStorageFaucetConnector implements IFaucetConnector {
+    /**
+     * The namespace supported by the wallet connector.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageFaucetConnector.
+     * @param options The options for the wallet connector.
+     * @param options.walletAddressEntityStorageType The entity storage type for wallet addresses, defaults to "wallet-address".
+     */
+    constructor(options?: {
+        walletAddressEntityStorageType?: string;
+    });
+    /**
+     * Fund the wallet from the faucet.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The bech32 encoded address of the address to fund.
+     * @param timeoutInSeconds The timeout in seconds to wait for the funding to complete.
+     * @returns The amount added to the address by the faucet.
+     */
+    fundAddress(identity: string, address: string, timeoutInSeconds?: number): Promise<bigint>;
+}

package/dist/types/entityStorageWalletConnector.d.ts

@@ -0,0 +1,69 @@
+import { type IWalletConnector } from "@twin.org/wallet-models";
+import type { IEntityStorageWalletConnectorConfig } from "./models/IEntityStorageWalletConnectorConfig";
+/**
+ * Class for performing wallet operations using in-memory storage.
+ */
+export declare class EntityStorageWalletConnector implements IWalletConnector {
+    /**
+     * The namespace supported by the wallet connector.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageWalletConnector.
+     * @param options The options for the wallet connector.
+     * @param options.vaultConnectorType Vault connector to use for wallet secrets, defaults to "vault".
+     * @param options.faucetConnectorType Optional faucet for requesting funds, defaults to "faucet".
+     * @param options.walletAddressEntityStorageType The entity storage for wallets, defaults to "wallet-address".
+     * @param options.config The configuration to use.
+     */
+    constructor(options?: {
+        vaultConnectorType?: string;
+        faucetConnectorType?: string;
+        walletAddressEntityStorageType?: string;
+        config?: IEntityStorageWalletConnectorConfig;
+    });
+    /**
+     * Create a new wallet.
+     * @param identity The identity of the user to access the vault keys.
+     * @returns Nothing.
+     */
+    create(identity: string): Promise<void>;
+    /**
+     * Get the addresses for the requested range.
+     * @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.
+     * @returns The list of addresses.
+     */
+    getAddresses(identity: string, accountIndex: number, startAddressIndex: number, count: number): Promise<string[]>;
+    /**
+     * Get the balance for an address in a wallet.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The bech32 encoded address.
+     * @returns The balance of the wallet address.
+     */
+    getBalance(identity: string, address: string): Promise<bigint>;
+    /**
+     * Ensure the balance for an address in a wallet.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The bech32 encoded address.
+     * @param ensureBalance The balance to ensure on the address.
+     * @param timeoutInSeconds The timeout in seconds to wait for the funding to complete.
+     * @returns True if the balance has been ensured.
+     */
+    ensureBalance(identity: string, address: string, ensureBalance: bigint, timeoutInSeconds?: number): Promise<boolean>;
+    /**
+     * Transfer funds to an address.
+     * @param identity The identity of the user to access the vault keys.
+     * @param addressSource The bech32 encoded address to send the funds from.
+     * @param addressDest The bech32 encoded address to send the funds to.
+     * @param amount The amount to transfer.
+     * @returns An identifier for the transfer if there was one.
+     */
+    transfer(identity: string, addressSource: string, addressDest: string, amount: bigint): Promise<string | undefined>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./entities/walletAddress";
+export * from "./entityStorageFaucetConnector";
+export * from "./entityStorageWalletConnector";
+export * from "./models/IEntityStorageWalletConnectorConfig";
+export * from "./schema";

package/dist/types/models/IEntityStorageWalletConnectorConfig.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Configuration for the Entity Storage Wallet Connector.
+ */
+export interface IEntityStorageWalletConnectorConfig {
+    /**
+     * The id of the entry in the vault containing the mnemonic.
+     * @default mnemonic
+     */
+    vaultMnemonicId?: string;
+    /**
+     * The coin type.
+     * @default 9999
+     */
+    coinType?: number;
+    /**
+     * The bech32 human readable part for the addresses.
+     * @default ent
+     */
+    bech32Hrp?: string;
+}

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initialize the schema for the wallet entity storage connector.
+ */
+export declare function initSchema(): void;

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/wallet-connector-entity-storage - Changelog
+
+## v0.0.1-next.3
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/wallet-connector-entity-storage - Examples

package/docs/reference/classes/EntityStorageFaucetConnector.md

@@ -0,0 +1,81 @@
+# Class: EntityStorageFaucetConnector
+
+Class for performing faucet operations using entity storage.
+
+## Implements
+
+- `IFaucetConnector`
+
+## Constructors
+
+### new EntityStorageFaucetConnector()
+
+> **new EntityStorageFaucetConnector**(`options`?): [`EntityStorageFaucetConnector`](EntityStorageFaucetConnector.md)
+
+Create a new instance of EntityStorageFaucetConnector.
+
+#### Parameters
+
+• **options?**
+
+The options for the wallet connector.
+
+• **options.walletAddressEntityStorageType?**: `string`
+
+The entity storage type for wallet addresses, defaults to "wallet-address".
+
+#### Returns
+
+[`EntityStorageFaucetConnector`](EntityStorageFaucetConnector.md)
+
+## Properties
+
+### NAMESPACE
+
+> `readonly` `static` **NAMESPACE**: `string` = `"entity-storage"`
+
+The namespace supported by the wallet connector.
+
+***
+
+### CLASS\_NAME
+
+> `readonly` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+#### Implementation of
+
+`IFaucetConnector.CLASS_NAME`
+
+## Methods
+
+### fundAddress()
+
+> **fundAddress**(`identity`, `address`, `timeoutInSeconds`): `Promise`\<`bigint`\>
+
+Fund the wallet from the faucet.
+
+#### Parameters
+
+• **identity**: `string`
+
+The identity of the user to access the vault keys.
+
+• **address**: `string`
+
+The bech32 encoded address of the address to fund.
+
+• **timeoutInSeconds**: `number` = `60`
+
+The timeout in seconds to wait for the funding to complete.
+
+#### Returns
+
+`Promise`\<`bigint`\>
+
+The amount added to the address by the faucet.
+
+#### Implementation of
+
+`IFaucetConnector.fundAddress`