@midnight-ntwrk/wallet-sdk-facade 1.0.0-beta.10

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { Observable } from 'rxjs';
+import { ShieldedWalletState, type ShieldedWallet } from '@midnight-ntwrk/wallet-sdk-shielded';
+import { type UnshieldedWallet, UnshieldedWalletState } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { type Utxo } from '@midnight-ntwrk/wallet-sdk-unshielded-state';
+import { AnyTransaction, DustWallet, DustWalletState } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
+import { ProvingRecipe } from '@midnight-ntwrk/wallet-sdk-shielded/v1';
+import * as ledger from '@midnight-ntwrk/ledger-v6';
+export interface TokenTransfer {
+    type: ledger.RawTokenType;
+    receiverAddress: string;
+    amount: bigint;
+}
+export type CombinedTokenTransfer = {
+    type: 'shielded' | 'unshielded';
+    outputs: TokenTransfer[];
+};
+export type CombinedSwapInputs = {
+    shielded?: Record<ledger.RawTokenType, bigint>;
+    unshielded?: Record<ledger.RawTokenType, bigint>;
+};
+export type CombinedSwapOutputs = CombinedTokenTransfer;
+export type TransactionIdentifier = string;
+export declare class FacadeState {
+    readonly shielded: ShieldedWalletState;
+    readonly unshielded: UnshieldedWalletState;
+    readonly dust: DustWalletState;
+    get isSynced(): boolean;
+    constructor(shielded: ShieldedWalletState, unshielded: UnshieldedWalletState, dust: DustWalletState);
+}
+export declare class WalletFacade {
+    shielded: ShieldedWallet;
+    unshielded: UnshieldedWallet;
+    dust: DustWallet;
+    constructor(shieldedWallet: ShieldedWallet, unshieldedWallet: UnshieldedWallet, dustWallet: DustWallet);
+    state(): Observable<FacadeState>;
+    submitTransaction(tx: ledger.FinalizedTransaction): Promise<TransactionIdentifier>;
+    balanceTransaction(zswapSecretKeys: ledger.ZswapSecretKeys, dustSecretKeys: ledger.DustSecretKey, tx: ledger.Transaction<ledger.SignatureEnabled, ledger.Proofish, ledger.Bindingish>, ttl: Date): Promise<ProvingRecipe.ProvingRecipe<ledger.FinalizedTransaction>>;
+    finalizeTransaction(recipe: ProvingRecipe.ProvingRecipe<ledger.FinalizedTransaction>): Promise<ledger.FinalizedTransaction>;
+    signTransaction(tx: ledger.UnprovenTransaction, signSegment: (data: Uint8Array) => ledger.Signature): Promise<ledger.UnprovenTransaction>;
+    calculateTransactionFee(tx: AnyTransaction): Promise<bigint>;
+    transferTransaction(zswapSecretKeys: ledger.ZswapSecretKeys, dustSecretKey: ledger.DustSecretKey, outputs: CombinedTokenTransfer[], ttl: Date): Promise<ProvingRecipe.TransactionToProve>;
+    registerNightUtxosForDustGeneration(nightUtxos: readonly Utxo[], nightVerifyingKey: ledger.SignatureVerifyingKey, signDustRegistration: (payload: Uint8Array) => Promise<ledger.Signature> | ledger.Signature, dustReceiverAddress?: string): Promise<ProvingRecipe.TransactionToProve>;
+    initSwap(zswapSecretKeys: ledger.ZswapSecretKeys, desiredInputs: CombinedSwapInputs, desiredOutputs: CombinedSwapOutputs[], ttl: Date): Promise<ledger.UnprovenTransaction>;
+    deregisterFromDustGeneration(nightUtxos: Utxo[], nightVerifyingKey: ledger.SignatureVerifyingKey, signDustRegistration: (payload: Uint8Array) => Promise<ledger.Signature> | ledger.Signature): Promise<ProvingRecipe.TransactionToProve>;
+    start(zswapSecretKeys: ledger.ZswapSecretKeys, dustSecretKey: ledger.DustSecretKey): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,204 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { combineLatest, map } from 'rxjs';
+import { ProvingRecipe } from '@midnight-ntwrk/wallet-sdk-shielded/v1';
+export class FacadeState {
+    shielded;
+    unshielded;
+    dust;
+    get isSynced() {
+        return (this.shielded.state.progress.isStrictlyComplete() &&
+            this.dust.state.progress.isStrictlyComplete() &&
+            this.unshielded.syncProgress?.synced === true);
+    }
+    constructor(shielded, unshielded, dust) {
+        this.shielded = shielded;
+        this.unshielded = unshielded;
+        this.dust = dust;
+    }
+}
+export class WalletFacade {
+    shielded;
+    unshielded;
+    dust;
+    constructor(shieldedWallet, unshieldedWallet, dustWallet) {
+        this.shielded = shieldedWallet;
+        this.unshielded = unshieldedWallet;
+        this.dust = dustWallet;
+    }
+    state() {
+        return combineLatest([this.shielded.state, this.unshielded.state(), this.dust.state]).pipe(map(([shieldedState, unshieldedState, dustState]) => new FacadeState(shieldedState, unshieldedState, dustState)));
+    }
+    async submitTransaction(tx) {
+        await this.shielded.submitTransaction(tx, 'Finalized');
+        return tx.identifiers().at(-1);
+    }
+    async balanceTransaction(zswapSecretKeys, dustSecretKeys, tx, ttl) {
+        const unshieldedBalancedTx = await this.unshielded.balanceTransaction(tx);
+        const recipe = await this.shielded.balanceTransaction(zswapSecretKeys, unshieldedBalancedTx, []);
+        switch (recipe.type) {
+            case ProvingRecipe.TRANSACTION_TO_PROVE:
+                return await this.dust.addFeePayment(dustSecretKeys, recipe.transaction, new Date(), ttl);
+            case ProvingRecipe.BALANCE_TRANSACTION_TO_PROVE: {
+                // if the shielded wallet returned a proven transaction, we need to pay fees with the dust wallet
+                const balancedTx = await this.dust.addFeePayment(dustSecretKeys, recipe.transactionToProve, new Date(), ttl);
+                if (balancedTx.type !== ProvingRecipe.TRANSACTION_TO_PROVE) {
+                    throw Error('Unexpected transaction type after adding fee payment.');
+                }
+                return {
+                    ...recipe,
+                    transactionToProve: balancedTx.transaction,
+                };
+            }
+            case ProvingRecipe.NOTHING_TO_PROVE: {
+                // @TODO fix casting
+                const txToBalance = recipe.transaction;
+                return await this.dust.addFeePayment(dustSecretKeys, txToBalance, new Date(), ttl);
+            }
+        }
+    }
+    async finalizeTransaction(recipe) {
+        return await this.shielded.finalizeTransaction(recipe);
+    }
+    async signTransaction(tx, signSegment) {
+        return await this.unshielded.signTransaction(tx, signSegment);
+    }
+    async calculateTransactionFee(tx) {
+        return await this.dust.calculateFee(tx);
+    }
+    async transferTransaction(zswapSecretKeys, dustSecretKey, outputs, ttl) {
+        const unshieldedOutputs = outputs
+            .filter((output) => output.type === 'unshielded')
+            .flatMap((output) => output.outputs);
+        const shieldedOutputs = outputs.filter((output) => output.type === 'shielded').flatMap((output) => output.outputs);
+        if (unshieldedOutputs.length === 0 && shieldedOutputs.length === 0) {
+            throw Error('At least one shielded or unshielded output is required.');
+        }
+        let shieldedTxRecipe = undefined;
+        let unshieldedTx = undefined;
+        if (unshieldedOutputs.length > 0) {
+            unshieldedTx = await this.unshielded.transferTransaction(unshieldedOutputs, ttl);
+        }
+        if (shieldedOutputs.length > 0) {
+            shieldedTxRecipe = await this.shielded.transferTransaction(zswapSecretKeys, shieldedOutputs);
+        }
+        // if there's a shielded tx only, return it as it's already balanced
+        if (shieldedTxRecipe !== undefined && unshieldedTx === undefined) {
+            if (shieldedTxRecipe.type !== 'TransactionToProve') {
+                throw Error('Unexpected transaction type.');
+            }
+            const recipe = await this.dust.addFeePayment(dustSecretKey, shieldedTxRecipe.transaction, new Date(), ttl);
+            if (recipe.type !== 'TransactionToProve') {
+                throw Error('Unexpected transaction type after adding fee payment.');
+            }
+            return recipe;
+        }
+        // if there's an unshielded tx only, pay fees (balance) with shielded wallet
+        if (shieldedTxRecipe === undefined && unshieldedTx !== undefined) {
+            const recipe = await this.dust.addFeePayment(dustSecretKey, unshieldedTx, new Date(), ttl);
+            if (recipe.type !== 'TransactionToProve') {
+                throw Error('Unexpected transaction type after adding fee payment.');
+            }
+            return recipe;
+        }
+        // if there's a shielded and unshielded tx, pay fees for unshielded and merge them
+        if (shieldedTxRecipe !== undefined && unshieldedTx !== undefined) {
+            if (shieldedTxRecipe.type !== 'TransactionToProve') {
+                throw Error('Unexpected transaction type.');
+            }
+            const txToBalance = shieldedTxRecipe.transaction.merge(unshieldedTx);
+            const recipe = await this.dust.addFeePayment(dustSecretKey, txToBalance, new Date(), ttl);
+            if (recipe.type !== 'TransactionToProve') {
+                throw Error('Unexpected transaction type after adding fee payment.');
+            }
+            return recipe;
+        }
+        throw Error('Unexpected transaction state.');
+    }
+    async registerNightUtxosForDustGeneration(nightUtxos, nightVerifyingKey, signDustRegistration, dustReceiverAddress) {
+        if (nightUtxos.length === 0) {
+            throw Error('At least one Night UTXO is required.');
+        }
+        const dustState = await this.dust.waitForSyncedState();
+        const receiverAddress = dustReceiverAddress ?? dustState.dustAddress;
+        const nextBlock = new Date();
+        const ttl = new Date(nextBlock.getTime() + 60 * 60 * 1000);
+        const transaction = await this.dust.createDustGenerationTransaction(nextBlock, ttl, nightUtxos.map((utxo) => ({ ...utxo, ctime: new Date(utxo.ctime) })), nightVerifyingKey, receiverAddress);
+        const intent = transaction.intents?.get(1);
+        if (!intent) {
+            throw Error('Dust generation transaction is missing intent segment 1.');
+        }
+        const signatureData = intent.signatureData(1);
+        const signature = await Promise.resolve(signDustRegistration(signatureData));
+        const recipe = await this.dust.addDustGenerationSignature(transaction, signature);
+        if (recipe.type !== ProvingRecipe.TRANSACTION_TO_PROVE) {
+            throw Error('Unexpected recipe type returned when registering Night UTXOs.');
+        }
+        return recipe;
+    }
+    async initSwap(zswapSecretKeys, desiredInputs, desiredOutputs, ttl) {
+        const { shielded: shieldedInputs, unshielded: unshieldedInputs } = desiredInputs;
+        const shieldedOutputs = desiredOutputs
+            .filter((output) => output.type === 'shielded')
+            .flatMap((output) => output.outputs);
+        const unshieldedOutputs = desiredOutputs
+            .filter((output) => output.type === 'unshielded')
+            .flatMap((output) => output.outputs);
+        const hasShieldedPart = (shieldedInputs && Object.keys(shieldedInputs).length > 0) || shieldedOutputs.length > 0;
+        const hasUnshieldedPart = (unshieldedInputs && Object.keys(unshieldedInputs).length > 0) || unshieldedOutputs.length > 0;
+        if (!hasShieldedPart && !hasUnshieldedPart) {
+            throw Error('At least one shielded or unshielded swap is required.');
+        }
+        const shieldedTxRecipe = hasShieldedPart && shieldedInputs !== undefined
+            ? await this.shielded.initSwap(zswapSecretKeys, shieldedInputs, shieldedOutputs)
+            : undefined;
+        const unshieldedTx = hasUnshieldedPart && unshieldedInputs !== undefined
+            ? await this.unshielded.initSwap(unshieldedInputs, unshieldedOutputs, ttl)
+            : undefined;
+        if (shieldedTxRecipe !== undefined && shieldedTxRecipe.type !== ProvingRecipe.TRANSACTION_TO_PROVE) {
+            throw Error('Unexpected transaction type.');
+        }
+        if (shieldedTxRecipe && unshieldedTx) {
+            return shieldedTxRecipe.transaction.merge(unshieldedTx);
+        }
+        if (shieldedTxRecipe) {
+            return shieldedTxRecipe.transaction;
+        }
+        if (unshieldedTx) {
+            return unshieldedTx;
+        }
+        throw Error('Unexpected transaction state.');
+    }
+    async deregisterFromDustGeneration(nightUtxos, nightVerifyingKey, signDustRegistration) {
+        const nextBlock = new Date();
+        const ttl = new Date(nextBlock.getTime() + 60 * 60 * 1000);
+        const transaction = await this.dust.createDustGenerationTransaction(nextBlock, ttl, nightUtxos.map((utxo) => ({ ...utxo, ctime: new Date(utxo.ctime) })), nightVerifyingKey, undefined);
+        const intent = transaction.intents?.get(1);
+        if (!intent) {
+            throw Error('Dust generation transaction is missing intent segment 1.');
+        }
+        const signatureData = intent.signatureData(1);
+        const signature = await Promise.resolve(signDustRegistration(signatureData));
+        const recipe = await this.dust.addDustGenerationSignature(transaction, signature);
+        if (recipe.type !== ProvingRecipe.TRANSACTION_TO_PROVE) {
+            throw Error('Unexpected recipe type returned when registering Night UTXOs.');
+        }
+        return recipe;
+    }
+    async start(zswapSecretKeys, dustSecretKey) {
+        await Promise.all([this.shielded.start(zswapSecretKeys), this.unshielded.start(), this.dust.start(dustSecretKey)]);
+    }
+    async stop() {
+        await Promise.all([this.shielded.stop(), this.unshielded.stop(), this.dust.stop()]);
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@midnight-ntwrk/wallet-sdk-facade",
+  "version": "1.0.0-beta.10",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Midnight Foundation",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/midnight-ntwrk/artifacts.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@midnight-ntwrk/ledger-v6": "6.1.0-alpha.5",
+    "@midnight-ntwrk/wallet-sdk-abstractions": "1.0.0-beta.9",
+    "@midnight-ntwrk/wallet-sdk-address-format": "3.0.0-beta.8",
+    "@midnight-ntwrk/wallet-sdk-dust-wallet": "1.0.0-beta.9",
+    "@midnight-ntwrk/wallet-sdk-hd": "3.0.0-beta.7",
+    "@midnight-ntwrk/wallet-sdk-shielded": "1.0.0-beta.10",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "1.0.0-beta.12",
+    "rxjs": "^7.5"
+  },
+  "devDependencies": {
+    "eslint": "^9.37.0",
+    "publint": "~0.3.14",
+    "rimraf": "^6.0.1",
+    "testcontainers": "^11.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "typecheck": "tsc -b ./tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint --max-warnings 0",
+    "format": "prettier --write \"**/*.{ts,js,json,yaml,yml}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml}\"",
+    "dist": "tsc -b ./tsconfig.build.json",
+    "dist:publish": "tsc -b ./tsconfig.publish.json",
+    "clean": "rimraf --glob dist 'tsconfig.*.tsbuildinfo' && date +%s > .clean-timestamp",
+    "publint": "publint --strict"
+  }
+}