@bsv/wallet-toolbox-client 1.2.4 → 1.2.6

package/out/src/Setup.d.ts

@@ -0,0 +1,329 @@
+import { BEEF, CreateActionOptions, CreateActionOutput, CreateActionResult, KeyDeriver, LockingScript, PrivateKey, PublicKey, WalletInterface } from '@bsv/sdk';
+import { Monitor, sdk, Services, Wallet, WalletStorageManager } from './index.client';
+import { Knex } from 'knex';
+import { StorageKnex } from './index.all';
+/**
+ * The 'Setup` class provides static setup functions to construct BRC-100 compatible
+ * wallets in a variety of configurations.
+ *
+ * It serves as a starting point for experimentation and customization.
+ */
+export declare abstract class Setup {
+    /**
+     * @param chain
+     * @returns true if .env is not valid for chain
+     */
+    static noEnv(chain: sdk.Chain): boolean;
+    /**
+     * Creates content for .env file with some private keys, identity keys, sample API keys, and sample MySQL connection string.
+     *
+     * Two new, random private keys are generated each time, with their associated public identity keys.
+     *
+     * Loading secrets from a .env file is intended only for experimentation and getting started.
+     * Private keys should never be included directly in your source code.
+     *
+     * @publicbody
+     */
+    static makeEnv(): string;
+    /**
+     * Reads a .env file of the format created by `makeEnv`.
+     *
+     * Returns values for designated `chain`.
+     *
+     * Access private keys through the `devKeys` object: `devKeys[identityKey]`
+     *
+     * @param chain Which chain to use: 'test' or 'main'
+     * @returns {SetupEnv} with configuration environment secrets used by `Setup` functions.
+     *
+     * @publicbody
+     */
+    static getEnv(chain: sdk.Chain): SetupEnv;
+    /**
+     * Create a `Wallet`. Storage can optionally be provided or configured later.
+     *
+     * The following components are configured: KeyDeriver, WalletStorageManager, WalletService, WalletStorage.
+     * Optionally, PrivilegedKeyManager is also configured.
+     *
+     * @publicbody
+     */
+    static createWallet(args: SetupWalletArgs): Promise<SetupWallet>;
+    /**
+     * Setup a new `Wallet` without requiring a .env file.
+     *
+     * @param args.chain - 'main' or 'test'
+     * @param args.rootKeyHex  - Root private key for wallet's key deriver.
+     * @param args.storageUrl - Optional. `StorageClient` and `chain` compatible endpoint URL.
+     * @param args.privilegedKeyGetter - Optional. Method that will return the privileged `PrivateKey`, on demand.
+     */
+    static createWalletClientNoEnv(args: {
+        chain: sdk.Chain;
+        rootKeyHex: string;
+        storageUrl?: string;
+        privilegedKeyGetter?: () => Promise<PrivateKey>;
+    }): Promise<Wallet>;
+    /**
+     * @publicbody
+     */
+    static createWalletClient(args: SetupWalletClientArgs): Promise<SetupWalletClient>;
+    /**
+     * @publicbody
+     */
+    static getKeyPair(priv?: string | PrivateKey): KeyPairAddress;
+    /**
+     * @publicbody
+     */
+    static getLockP2PKH(address: string): LockingScript;
+    /**
+     * @publicbody
+     */
+    static getUnlockP2PKH(priv: PrivateKey, satoshis: number): sdk.ScriptTemplateUnlock;
+    /**
+     * @publicbody
+     */
+    static createP2PKHOutputs(outputs: {
+        address: string;
+        satoshis: number;
+        outputDescription?: string;
+        basket?: string;
+        tags?: string[];
+    }[]): CreateActionOutput[];
+    /**
+     * @publicbody
+     */
+    static createP2PKHOutputsAction(wallet: WalletInterface, outputs: {
+        address: string;
+        satoshis: number;
+        outputDescription?: string;
+        basket?: string;
+        tags?: string[];
+    }[], options?: CreateActionOptions): Promise<{
+        cr: CreateActionResult;
+        outpoints: string[] | undefined;
+    }>;
+    /**
+     * @publicbody
+     */
+    static fundWalletFromP2PKHOutpoints(wallet: WalletInterface, outpoints: string[], p2pkhKey: KeyPairAddress, inputBEEF?: BEEF): Promise<void>;
+    /**
+     * Adds `Knex` based storage to a `Wallet` configured by `Setup.createWalletOnly`
+     *
+     * @param args.knex `Knex` object configured for either MySQL or SQLite database access.
+     * Schema will be created and migrated as needed.
+     * For MySQL, a schema corresponding to databaseName must exist with full access permissions.
+     * @param args.databaseName Name for this storage. For MySQL, the schema name within the MySQL instance.
+     * @param args.chain Which chain this wallet is on: 'main' or 'test'. Defaults to 'test'.
+     * @param args.rootKeyHex
+     *
+     * @publicbody
+     */
+    static createWalletKnex(args: SetupWalletKnexArgs): Promise<SetupWalletKnex>;
+    /**
+     * @returns {StorageKnex} - `Knex` based storage provider for a wallet. May be used for either active storage or backup storage.
+     */
+    static createStorageKnex(args: SetupWalletKnexArgs): Promise<StorageKnex>;
+    /**
+     * @publicbody
+     */
+    static createSQLiteKnex(filename: string): Knex;
+    /**
+     * @publicbody
+     */
+    static createMySQLKnex(connection: string, database?: string): Knex;
+    /**
+     * @publicbody
+     */
+    static createWalletMySQL(args: SetupWalletMySQLArgs): Promise<SetupWalletKnex>;
+    /**
+     * @publicbody
+     */
+    static createWalletSQLite(args: SetupWalletSQLiteArgs): Promise<SetupWalletKnex>;
+}
+/**
+ * Arguments used by `createWallet` to construct a `SetupWallet`.
+ *
+ * Extension `SetupWalletClientArgs` used by `createWalletClient` to construct a `SetupWalletClient`.
+ *
+ * Extension `SetupWalletKnexArgs` used by `createWalletKnex` to construct a `SetupWalletKnex`.
+ *
+ * Extension `SetupWalletMySQLArgs` used by `createWalletMySQL` to construct a `SetupWalletKnex`.
+ *
+ * Extension `SetupWalletSQLiteArgs` used by `createWalletSQLite` to construct a `SetupWalletKnex`.
+ */
+export interface SetupWalletArgs {
+    /**
+     * Configuration "secrets" typically obtained by `Setup.makeEnv` and `Setup.getEnv` functions.
+     */
+    env: SetupEnv;
+    /**
+     * Optional. The non-privileged private key used to initialize the `KeyDeriver` and determine the `identityKey`.
+     * Defaults to `env.devKeys[env.identityKey]
+     */
+    rootKeyHex?: string;
+    /**
+     * Optional. The privileged private key getter used to initialize the `PrivilegedKeyManager`.
+     * Defaults to undefined.
+     */
+    privilegedKeyGetter?: () => Promise<PrivateKey>;
+    /**
+     * Optional. Active wallet storage. Can be added later.
+     */
+    active?: sdk.WalletStorageProvider;
+    /**
+     * Optional. One or more storage providers managed as backup destinations. Can be added later.
+     */
+    backups?: sdk.WalletStorageProvider[];
+}
+/**
+ *
+ */
+export interface SetupWalletKnexArgs extends SetupWalletArgs {
+    knex: Knex<any, any[]>;
+    databaseName: string;
+}
+/**
+ *
+ */
+export interface SetupWalletMySQLArgs extends SetupWalletArgs {
+    databaseName: string;
+}
+/**
+ *
+ */
+export interface SetupWalletSQLiteArgs extends SetupWalletArgs {
+    filePath: string;
+    databaseName: string;
+}
+/**
+ *
+ */
+export interface SetupWalletKnex extends SetupWallet {
+    activeStorage: StorageKnex;
+    userId: number;
+    rootKey: PrivateKey;
+    identityKey: string;
+    keyDeriver: KeyDeriver;
+    chain: sdk.Chain;
+    storage: WalletStorageManager;
+    services: Services;
+    monitor: Monitor;
+    wallet: Wallet;
+}
+/**
+ * A private key and associated public key and address.
+ */
+export interface KeyPairAddress {
+    privateKey: PrivateKey;
+    publicKey: PublicKey;
+    address: string;
+}
+/**
+ * `SetupEnv` provides a starting point for managing secrets that
+ * must not appear in source code.
+ *
+ * The `makeEnv` and `getEnv` functions of the `Setup` and `SetupClient` classes
+ * provide an easy way to create and import these secrets and related properties.
+ */
+export interface SetupEnv {
+    /**
+     * The chan being accessed: 'main' for mainnet, 'test' for 'testnet'.
+     */
+    chain: sdk.Chain;
+    /**
+     * The user's primary identity key (public key).
+     */
+    identityKey: string;
+    /**
+     * A secondary identity key (public key), used to test exchanges with other users.
+     */
+    identityKey2: string;
+    /**
+     * Filepath to sqlite file to be used for identityKey wallet.
+     */
+    filePath: string | undefined;
+    /**
+     * A vaild TAAL API key for use by `Services`
+     */
+    taalApiKey: string;
+    /**
+     * A map of public keys (identity keys, hex strings) to private keys (hex strings).
+     */
+    devKeys: Record<string, string>;
+    /**
+     * A MySQL connection string including user and password properties.
+     * Must be valid to make use of MySQL `Setup` class support.
+     */
+    mySQLConnection: string;
+}
+/**
+ * When creating a BRC-100 compatible `Wallet`, many components come into play.
+ *
+ * All of the `createWallet` functions in the `Setup` and `SetupClient` classes return
+ * an object with direct access to each component to facilitate experimentation, testing
+ * and customization.
+ */
+export interface SetupWallet {
+    /**
+     * The rootKey of the `KeyDeriver`. The private key from which other keys are derived.
+     */
+    rootKey: PrivateKey;
+    /**
+     * The pubilc key associated with the `rootKey` which also serves as the wallet's identity.
+     */
+    identityKey: string;
+    /**
+     * The `KeyDeriver` component used by the wallet for key derivation and cryptographic functions.
+     */
+    keyDeriver: KeyDeriver;
+    /**
+     * The chain ('main' or 'test') which the wallet accesses.
+     */
+    chain: sdk.Chain;
+    /**
+     * The `WalletStorageManager` that manages all the configured storage providers (active and backups)
+     * accessed by the wallet.
+     */
+    storage: WalletStorageManager;
+    /**
+     * The network `Services` component which provides the wallet with access to external services hosted
+     * on the public network.
+     */
+    services: Services;
+    /**
+     * The background task `Monitor` component available to the wallet to offload tasks
+     * that speed up wallet operations and maintain data integrity.
+     */
+    monitor: Monitor;
+    /**
+     * The actual BRC-100 `Wallet` to which all the other properties and components contribute.
+     *
+     * Note that internally, the wallet is itself linked to all these properties and components.
+     * They are included in this interface to facilitate access after wallet construction for
+     * experimentation, testing and customization. Any changes made to the configuration of these
+     * components after construction may disrupt the normal operation of the wallet.
+     */
+    wallet: Wallet;
+}
+/**
+ * Extension `SetupWalletClientArgs` of `SetupWalletArgs` is used by `createWalletClient`
+ * to construct a `SetupWalletClient`.
+ */
+export interface SetupWalletClientArgs extends SetupWalletArgs {
+    /**
+     * The endpoint URL of a service hosting the `StorageServer` JSON-RPC service to
+     * which a `StorageClient` instance should connect to function as
+     * the active storage provider of the newly created wallet.
+     */
+    endpointUrl?: string;
+}
+/**
+ * Extension `SetupWalletClient` of `SetupWallet` is returned by `createWalletClient`
+ */
+export interface SetupWalletClient extends SetupWallet {
+    /**
+     * The endpoint URL of the service hosting the `StorageServer` JSON-RPC service to
+     * which a `StorageClient` instance is connected to function as
+     * the active storage provider of the wallet.
+     */
+    endpointUrl: string;
+}
+//# sourceMappingURL=Setup.d.ts.map

package/out/src/Setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Setup.d.ts","sourceRoot":"","sources":["../../../src/Setup.ts"],"names":[],"mappings":"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"}