NUT-17: WebSocket updates

.github/workflows/nutshell-integration.yml

@@ -8,7 +8,7 @@ jobs:
     steps:
       - name: Pull and start mint
         run: |
-          docker run -d -p 3338:3338 --name nutshell -e MINT_LIGHTNING_BACKEND=FakeWallet -e MINT_INPUT_FEE_PPK=100 -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY cashubtc/nutshell:0.16.0 poetry run mint
+          docker run -d -p 3338:3338 --name nutshell -e MINT_LIGHTNING_BACKEND=FakeWallet -e MINT_INPUT_FEE_PPK=100 -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY cashubtc/nutshell:0.16.2 poetry run mint
 
       - name: Check running containers
         run: docker ps

package.json

@@ -29,6 +29,7 @@
 	"devDependencies": {
 		"@types/jest": "^29.5.1",
 		"@types/node-fetch": "^2.6.4",
+		"@types/ws": "^8.5.10",
 		"@typescript-eslint/eslint-plugin": "^5.59.2",
 		"@typescript-eslint/parser": "^5.59.2",
 		"eslint": "^8.39.0",
@@ -37,14 +38,16 @@
 		"eslint-plugin-n": "^15.7.0",
 		"eslint-plugin-promise": "^6.1.1",
 		"jest": "^29.5.0",
+		"mock-socket": "^9.3.1",
 		"nock": "^13.3.3",
 		"node-fetch": "^2.7.0",
 		"prettier": "^2.8.8",
 		"ts-jest": "^29.1.0",
 		"ts-jest-resolver": "^2.0.1",
 		"ts-node": "^10.9.1",
 		"typedoc": "^0.24.7",
-		"typescript": "^5.0.4"
+		"typescript": "^5.0.4",
+		"ws": "^8.16.0"
 	},
 	"dependencies": {
 		"@cashu/crypto": "^0.2.7",

src/CashuMint.ts

@@ -1,3 +1,4 @@
+import { ConnectionManager, WSConnection } from './WSConnection.js';
 import type {
 	CheckStatePayload,
 	CheckStateResponse,
@@ -33,6 +34,7 @@ import { handleMintInfoContactFieldDeprecated } from './legacy/nut-06.js';
  * Class represents Cashu Mint API. This class contains Lower level functions that are implemented by CashuWallet.
  */
 class CashuMint {
+	private ws?: WSConnection;
 	/**
 	 * @param _mintUrl requires mint URL to create this object
 	 * @param _customRequest if passed, use custom request implementation for network communication with the mint
@@ -438,6 +440,47 @@ class CashuMint {
 	}): Promise<PostRestoreResponse> {
 		return CashuMint.restore(this._mintUrl, restorePayload, this._customRequest);
 	}
+
+	/**
+	 * Tries to establish a websocket connection with the websocket mint url according to NUT-17
+	 */
+	async connectWebSocket() {
+		if (this.ws) {
+			await this.ws.ensureConnection();
+		} else {
+			const mintUrl = new URL(this._mintUrl);
+			const wsSegment = 'v1/ws';
+			if (mintUrl.pathname) {
+				if (mintUrl.pathname.endsWith('/')) {
+					mintUrl.pathname += wsSegment;
+				} else {
+					mintUrl.pathname += '/' + wsSegment;
+				}
+			}
+			this.ws = ConnectionManager.getInstance().getConnection(
+				`${mintUrl.protocol === 'https:' ? 'wss' : 'ws'}://${mintUrl.host}${mintUrl.pathname}`
+			);
+			try {
+				await this.ws.connect();
+			} catch (e) {
+				console.log(e);
+				throw new Error('Failed to connect to WebSocket...');
+			}
+		}
+	}
+
+	/**
+	 * Closes a websocket connection
+	 */
+	disconnectWebSocket() {
+		if (this.ws) {
+			this.ws.close();
+		}
+	}
+
+	get webSocketConnection() {
+		return this.ws;
+	}
 }
 
 export { CashuMint };

src/CashuWallet.ts

@@ -19,7 +19,10 @@ import {
 	GetInfoResponse,
 	OutputAmounts,
 	ProofState,
-	BlindingData
+	BlindingData,
+	MintQuoteResponse,
+	MintQuoteState,
+	MeltQuoteState
 } from './model/types/index.js';
 import { bytesToNumber, getDecodedToken, splitAmount, sumProofs, getKeepAmounts } from './utils.js';
 import { hashToCurve, pointFromHex } from '@cashu/crypto/modules/common';
@@ -31,6 +34,7 @@ import {
 import { deriveBlindingFactor, deriveSecret } from '@cashu/crypto/modules/client/NUT09';
 import { createP2PKsecret, getSignedProofs } from '@cashu/crypto/modules/client/NUT11';
 import { type Proof as NUT11Proof } from '@cashu/crypto/modules/common/index';
+import { SubscriptionCanceller } from './model/types/wallet/websocket.js';
 
 /**
  * The default number of proofs per denomination to keep in a wallet.
@@ -863,6 +867,139 @@ class CashuWallet {
 		return states;
 	}
 
+	/**
+	 * Register a callback to be called whenever a mint quote's state changes
+	 * @param quoteIds List of mint quote IDs that should be subscribed to
+	 * @param callback Callback function that will be called whenever a mint quote state changes
+	 * @param errorCallback
+	 * @returns
+	 */
+	async onMintQuoteUpdates(
+		quoteIds: Array<string>,
+		callback: (payload: MintQuoteResponse) => void,
+		errorCallback: (e: Error) => void
+	): Promise<SubscriptionCanceller> {
+		await this.mint.connectWebSocket();
+		if (!this.mint.webSocketConnection) {
+			throw new Error('failed to establish WebSocket connection.');
+		}
+		const subId = this.mint.webSocketConnection.createSubscription(
+			{ kind: 'bolt11_mint_quote', filters: quoteIds },
+			callback,
+			errorCallback
+		);
+		return () => {
+			this.mint.webSocketConnection?.cancelSubscription(subId, callback);
+		};
+	}
+
+	/**
+	 * Register a callback to be called whenever a melt quote's state changes
+	 * @param quoteIds List of melt quote IDs that should be subscribed to
+	 * @param callback Callback function that will be called whenever a melt quote state changes
+	 * @param errorCallback
+	 * @returns
+	 */
+	async onMeltQuotePaid(
+		quoteId: string,
+		callback: (payload: MeltQuoteResponse) => void,
+		errorCallback: (e: Error) => void
+	): Promise<SubscriptionCanceller> {
+		return this.onMeltQuoteUpdates(
+			[quoteId],
+			(p) => {
+				if (p.state === MeltQuoteState.PAID) {
+					callback(p);
+				}
+			},
+			errorCallback
+		);
+	}
+
+	/**
+	 * Register a callback to be called when a single mint quote gets paid
+	 * @param quoteId Mint quote id that should be subscribed to
+	 * @param callback Callback function that will be called when this mint quote gets paid
+	 * @param errorCallback
+	 * @returns
+	 */
+	async onMintQuotePaid(
+		quoteId: string,
+		callback: (payload: MintQuoteResponse) => void,
+		errorCallback: (e: Error) => void
+	): Promise<SubscriptionCanceller> {
+		return this.onMintQuoteUpdates(
+			[quoteId],
+			(p) => {
+				if (p.state === MintQuoteState.PAID) {
+					callback(p);
+				}
+			},
+			errorCallback
+		);
+	}
+
+	/**
+	 * Register a callback to be called when a single melt quote gets paid
+	 * @param quoteId Melt quote id that should be subscribed to
+	 * @param callback Callback function that will be called when this melt quote gets paid
+	 * @param errorCallback
+	 * @returns
+	 */
+	async onMeltQuoteUpdates(
+		quoteIds: Array<string>,
+		callback: (payload: MeltQuoteResponse) => void,
+		errorCallback: (e: Error) => void
+	): Promise<SubscriptionCanceller> {
+		await this.mint.connectWebSocket();
+		if (!this.mint.webSocketConnection) {
+			throw new Error('failed to establish WebSocket connection.');
+		}
+		const subId = this.mint.webSocketConnection.createSubscription(
+			{ kind: 'bolt11_melt_quote', filters: quoteIds },
+			callback,
+			errorCallback
+		);
+		return () => {
+			this.mint.webSocketConnection?.cancelSubscription(subId, callback);
+		};
+	}
+
+	/**
+	 * Register a callback to be called whenever a subscribed proof state changes
+	 * @param proofs List of proofs that should be subscribed to
+	 * @param callback Callback function that will be called whenever a proof's state changes
+	 * @param errorCallback
+	 * @returns
+	 */
+	async onProofStateUpdates(
+		proofs: Array<Proof>,
+		callback: (payload: ProofState & { proof: Proof }) => void,
+		errorCallback: (e: Error) => void
+	): Promise<SubscriptionCanceller> {
+		await this.mint.connectWebSocket();
+		if (!this.mint.webSocketConnection) {
+			throw new Error('failed to establish WebSocket connection.');
+		}
+		const enc = new TextEncoder();
+		const proofMap: { [y: string]: Proof } = {};
+		for (let i = 0; i < proofs.length; i++) {
+			const y = hashToCurve(enc.encode(proofs[i].secret)).toHex(true);
+			proofMap[y] = proofs[i];
+		}
+		const ys = Object.keys(proofMap);
+		const subId = this.mint.webSocketConnection.createSubscription(
+			{ kind: 'proof_state', filters: ys },
+			(p: ProofState) => {
+				callback({ ...p, proof: proofMap[p.Y] });
+			},
+			errorCallback
+		);
+		return () => {
+			this.mint.webSocketConnection?.cancelSubscription(subId, callback);
+		};
+	}
+
 	/**
 	 * Creates blinded messages for a given amount
 	 * @param amount amount to create blinded messages for