cashubtc · robwoodgate · May 22, 2026 · May 12, 2026 · May 12, 2026 · May 12, 2026
diff --git a/Makefile b/Makefile
@@ -21,6 +21,14 @@ NUT_IMAGE_RC ?= cashubtc/nutshell:0.18.2
 NUT_IMAGE ?= cashubtc/nutshell:0.20.0
 NUT_NAME ?= cashu-dev-nutshell
 
+# BLS (v3) Nutshell: no published image yet — build from a local checkout that
+# carries v3 support. Default path assumes the worktree sibling layout used
+# during the BLS bring-up (../nutshell on feature/bls12-381-v3-keyset, ≥0.21.0
+# which emits v3 keysets by default; see cashu/core/base.py).
+NUT_BLS_PATH ?= ../nutshell
+NUT_BLS_IMAGE ?= cashu-dev-nutshell-bls:local
+NUT_BLS_NAME ?= cashu-dev-nutshell-bls
+
 # ------------------------
 # Docker envs per dependency
 # ------------------------
@@ -43,7 +51,8 @@ NUT_ENVS = \
 	-e FAKEWALLET_DELAY_PAYMENT=TRUE \
 	-e FAKEWALLET_DELAY_OUTGOING_PAYMENT=$(FAKE_DELAY) \
 	-e FAKEWALLET_DELAY_INCOMING_PAYMENT=$(FAKE_DELAY) \
-	-e MINT_TRANSACTION_RATE_LIMIT_PER_MINUTE=$(RATE_LIMIT_PM)
+	-e MINT_TRANSACTION_RATE_LIMIT_PER_MINUTE=$(RATE_LIMIT_PM) \
+	-e MINT_GLOBAL_RATE_LIMIT_PER_MINUTE=$(RATE_LIMIT_PM)
 
 # ------------------------
 # Platform flag
@@ -86,6 +95,7 @@ print-mint-images:
 	@echo "CDK_IMAGE_RC=$(CDK_IMAGE_RC)"
 	@echo "NUT_IMAGE=$(NUT_IMAGE)"
 	@echo "NUT_IMAGE_RC=$(NUT_IMAGE_RC)"
+	@echo "NUT_BLS_IMAGE=$(NUT_BLS_IMAGE) (built from $(NUT_BLS_PATH))"
 
 # ------------------------
 # Nutshell Targets
@@ -113,3 +123,23 @@ nutshell-stable-down:
 
 nutshell-rc-down:
 	$(MAKE) nutshell-down NUT_NAME=cashu-dev-nutshell-rc
+
+# ------------------------
+# Nutshell BLS (v3) Targets
+# ------------------------
+# Built natively (no PLATFORM_FLAG): the base image (python:3.10-slim) is
+# multi-arch, and BLS keygen through Rosetta is unusably slow on arm64 hosts.
+.PHONY: nutshell-bls-build nutshell-bls-up nutshell-bls-down
+
+nutshell-bls-build:
+	$(DOCKER) build -t $(NUT_BLS_IMAGE) $(NUT_BLS_PATH)
+
+nutshell-bls-up: nutshell-bls-build
+	-$(DOCKER) rm -f -v $(NUT_BLS_NAME) >/dev/null 2>&1 || true
+	$(DOCKER) run -d --name $(NUT_BLS_NAME) \
+		-p $(BIND_ADDR):$(PORT):3338 \
+		$(NUT_ENVS) \
+		$(NUT_BLS_IMAGE) poetry run mint
+
+nutshell-bls-down:
+	-$(DOCKER) rm -f -v $(NUT_BLS_NAME)
diff --git a/docs-src/wallet_events/proof_state_streams.md b/docs-src/wallet_events/proof_state_streams.md
@@ -8,19 +8,20 @@
 import { CheckStateEnum } from '@cashu/cashu-ts';
 const ac = new AbortController();
 (async () => {
-  for await (const u of wallet.on.proofStatesStream(proofs, { signal: ac.signal })) {
-    if (u.state === CheckStateEnum.SPENT) {
-      console.log('Spent proof', u.proof.id);
+  try {
+    for await (const u of wallet.on.proofStatesStream(proofs, { signal: ac.signal })) {
+      if (u.state === CheckStateEnum.SPENT) {
+        console.log('Spent proof', u.proof.id);
+      }
     }
+  } catch (e) {
+    if ((e as Error).name === 'AbortError') return; // ac.abort() ended the loop
+    console.error('Stream error', e); // websocket / mint RPC failure
   }
 })();
 
 // later
 ac.abort();
 ```
 
-> **Note:** the subscription is sent to the mint on the first iteration, not when
-> `proofStatesStream` is called. Per
-> [NUT-17](https://github.com/cashubtc/nuts/blob/main/17.md) the mint replays the
-> _current_ state on subscribe, so the latest state is never lost — only intermediate
-> transitions before the first iteration are collapsed into that snapshot.
+The iterator ends cleanly when the abort signal fires or the consumer breaks out of the loop. Wallet errors (WebSocket failure, RPC error from the mint) are thrown from the iterator — wrap in `try/catch` to recover.
diff --git a/etc/cashu-ts.api.md b/etc/cashu-ts.api.md
@@ -4,6 +4,7 @@
 
 ```ts
 
+import { Fp2 } from '@noble/curves/abstract/tower.js';
 import { WeierstrassPoint } from '@noble/curves/abstract/weierstrass.js';
 
 // @public
@@ -134,6 +135,12 @@ export class AmountWithUnitError extends CTSError {
     constructor(message: string);
 }
 
+// @public (undocumented)
+export function asBlsG1Point(pt: G1Point): CurvePoint;
+
+// @public (undocumented)
+export function asSecpPoint(pt: WeierstrassPoint<bigint>): CurvePoint;
+
 // @public
 export function assertSecretKind(allowed: SecretKind | SecretKind[], secret: Secret | string): Secret;
 
@@ -205,15 +212,34 @@ export type BatchMintRequest = {
     signatures?: Array<string | null>;
 };
 
+// @public
+export function batchVerifyUnblindedSignatureBls(items: Array<{
+    K2: G2Point;
+    C: G1Point;
+    secret: Uint8Array;
+}>): boolean;
+
 // @public
 export function blindMessage(secret: Uint8Array, r?: bigint): RawBlindedMessage;
 
+// @public
+export function blindMessageBls(secret: Uint8Array, r?: bigint): RawBlindedMessage;
+
 // @public (undocumented)
 export type BlindSignature = {
     C_: WeierstrassPoint<bigint>;
     id: string;
 };
 
+// @public
+export const BLS_FR_ORDER: bigint;
+
+// @public
+export const BLS_G2_GENERATOR: WeierstrassPoint<Fp2>;
+
+// @public
+export const BLS_HASH_TO_CURVE_DST = "CASHU_BLS12_381_G1_XMD:SHA-256_SSWU_RO_";
+
 // @public (undocumented)
 export type CancellerLike = SubscriptionCanceller | Promise<SubscriptionCanceller>;
 
@@ -272,6 +298,9 @@ export class ConsoleLogger implements Logger {
 // @public (undocumented)
 export function constructUnblindedSignature(blindSig: BlindSignature, r: bigint, secret: Uint8Array, key: WeierstrassPoint<bigint>): UnblindedSignature;
 
+// @public (undocumented)
+export function constructUnblindedSignatureBls(blindSig: BlindSignature, r: bigint, secret: Uint8Array): UnblindedSignature;
+
 // @public
 export interface CounterRange {
     // (undocumented)
@@ -303,6 +332,9 @@ export function createAuthWallet(mintUrl: string, options?: {
 // @public (undocumented)
 export function createBlindSignature(B_: WeierstrassPoint<bigint>, privateKey: Uint8Array, id: string): BlindSignature;
 
+// @public
+export function createBlindSignatureBls(B_: G1Point, privateKey: Uint8Array, id: string): BlindSignature;
+
 // @public
 export const createDLEQProof: (B_: WeierstrassPoint<bigint>, a: Uint8Array) => DLEQ;
 
@@ -347,6 +379,15 @@ export class CTSError extends Error {
     readonly cause?: unknown;
 }
 
+// @public
+export type CurvePoint = {
+    kind: 'secp';
+    pt: WeierstrassPoint<bigint>;
+} | {
+    kind: 'blsG1';
+    pt: G1Point;
+};
+
 // @public
 export function decodePaymentRequest(paymentRequest: string): PaymentRequest_2;
 
@@ -418,6 +459,12 @@ export type Enumerate<N extends number, Acc extends number[] = []> = Acc['length
 // @public
 export function findSigningKey(pubkey: string, privkeys: string | string[]): string;
 
+// @public (undocumented)
+export type G1Point = WeierstrassPoint<bigint>;
+
+// @public (undocumented)
+export type G2Point = WeierstrassPoint<Fp2>;
+
 // @public
 export function getDataField(secret: Secret | string): string;
 
@@ -435,6 +482,9 @@ export function getEncodedToken(token: Token, opts?: {
 // @public
 export function getEncodedTokenBinary(token: Token): Uint8Array;
 
+// @public
+export function getG2PubKeyFromPrivKey(privKey: Uint8Array): Uint8Array<ArrayBufferLike>;
+
 // @public
 export function getHTLCWitnessPreimage(witness: Proof['witness']): string | undefined;
 
@@ -574,6 +624,9 @@ export function hash_e(pubkeys: Array<WeierstrassPoint<bigint>>): Uint8Array;
 // @public (undocumented)
 export function hashToCurve(secret: Uint8Array): WeierstrassPoint<bigint>;
 
+// @public (undocumented)
+export function hashToCurveBls(secret: Uint8Array): G1Point;
+
 // @public
 export type HasKeysetId = {
     id: string;
@@ -617,6 +670,9 @@ export function injectWebSocketImpl(ws: typeof WebSocket): void;
 // @public (undocumented)
 export type IntRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
 
+// @public
+export function isBlsKeyset(keysetId: string): boolean;
+
 // @public
 export function isHTLCSpendAuthorised(proof: Proof, logger?: Logger, message?: string): boolean;
 
@@ -1566,6 +1622,18 @@ export function pointFromBytes(bytes: Uint8Array): WeierstrassPoint<bigint>;
 // @public (undocumented)
 export function pointFromHex(hex: string): WeierstrassPoint<bigint>;
 
+// @public
+export function pointFromHexAuto(hex: string): CurvePoint;
+
+// @public (undocumented)
+export function pointFromHexG1(hex: string): G1Point;
+
+// @public (undocumented)
+export function pointFromHexG2(hex: string): G2Point;
+
+// @public (undocumented)
+export function pointToHex(p: CurvePoint): string;
+
 // @public
 export type PostRestorePayload = {
     outputs: SerializedBlindedMessage[];
@@ -2012,8 +2080,8 @@ export type UnblindedSignature = {
 // @public (undocumented)
 export function unblindSignature(C_: WeierstrassPoint<bigint>, r: bigint, A: WeierstrassPoint<bigint>): WeierstrassPoint<bigint>;
 
-// @public @deprecated (undocumented)
-export function verifyDleqIfPresent(proof: Proof, keyset: HasKeysetKeys): boolean;
+// @public
+export function unblindSignatureBls(C_: G1Point, r: bigint): G1Point;
 
 // @public (undocumented)
 export const verifyDLEQProof: (dleq: DLEQ, B_: WeierstrassPoint<bigint>, C_: WeierstrassPoint<bigint>, A: WeierstrassPoint<bigint>) => boolean;
@@ -2035,9 +2103,17 @@ export function verifyMintQuoteSignature(pubkey: string, quote: string, blindedM
 // @public
 export function verifyP2PKSpendingConditions(proof: Proof, logger?: Logger, message?: string): P2PKVerificationResult;
 
-// @public (undocumented)
+// @public
+export function verifyProofsForReceive(proofs: ProofLike[], getKeyset: (id: string) => HasKeysetKeys, opts?: {
+    requireDleq?: boolean;
+}): void;
+
+// @public
 export function verifyUnblindedSignature(proof: UnblindedSignature, privKey: Uint8Array): boolean;
 
+// @public
+export function verifyUnblindedSignatureBls(K2: G2Point, C: G1Point, secret: Uint8Array): boolean;
+
 // @public
 export class Wallet {
     constructor(mint: Mint | string, options?: {
@@ -2071,7 +2147,7 @@ export class Wallet {
     checkMintQuoteBolt11(quote: string | MintQuoteBolt11Response): Promise<MintQuoteBolt11Response>;
     checkMintQuoteBolt12(quote: string): Promise<MintQuoteBolt12Response>;
     checkMintQuoteOnchain(quote: string): Promise<MintQuoteOnchainResponse>;
-    checkProofsStates(proofs: Array<Pick<Proof, 'secret'>>): Promise<ProofState[]>;
+    checkProofsStates(proofs: Array<Pick<ProofLike, 'secret' | 'id'>>): Promise<ProofState[]>;
     completeBatchMint(batchPreview: BatchMintPreview<Pick<MintQuoteBaseResponse, 'quote'>>): Promise<Proof[]>;
     completeMelt<TQuote extends Pick<MeltQuoteBaseResponse, 'quote'> = MeltQuoteBaseResponse>(meltPreview: MeltPreview<TQuote>, privkey?: string | string[], options?: CompleteMeltOptions): Promise<MeltProofsResponse<TQuote>>;
     // @deprecated (undocumented)

diff --git a/examples/README.md b/examples/README.md
@@ -25,13 +25,13 @@ Run `make print-mint-images` to see which versions are pinned. The auth demos ha
 
 ## Examples
 
-| File                      | Mint required                          | Description                                                                                                                                                                                                                                       |
-| ------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `simpleWallet_example.ts` | `DEV=1 make nutshell-up` (or `cdk-up`) | End-to-end BOLT11 mint, send, receive, and melt against a fake-wallet LN backend.                                                                                                                                                                 |
-| `bolt12Wallet_example.ts` | `DEV=1 make cdk-up`                    | Reusable BOLT12 offer flow: mint via BOLT11, pay the offer, mint again from accumulated payments. CDK's fakewallet handles both BOLT11 and BOLT12.                                                                                                |
-| `onchain_example.ts`      | none (uses public test mint)           | Onchain (NUT-30) mint and melt against `https://onchain.cashudevkit.org` on Mutinynet. **Interactive** — pauses while you fund the printed address from the Mutinynet faucet, then continues automatically once the mint detects 2 confirmations. |
-| `auth_mint/`              | Keycloak + CDK mint via docker         | OAuth2 / OIDC blind-auth (NUT-21 / NUT-22) demos. See `auth_mint/Makefile` (`make up`, `make demo-device`, `make down`).                                                                                                                          |
-| `paymentApi_example.js`   | —                                      | Code snippet for receiving locked ecash inside a Firebase Cloud Function. Not runnable standalone.                                                                                                                                                |
+| File                      | Mint required                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `simpleWallet_example.ts` | `DEV=1 make nutshell-up` (or `cdk-up`)                                            | End-to-end BOLT11 mint, send, receive, and melt against a fake-wallet LN backend.                                                                                                                                                                                                                                                                                                                                                          |
+| `bolt12Wallet_example.ts` | `DEV=1 make cdk-up`                                                               | Reusable BOLT12 offer flow: mint via BOLT11, pay the offer, mint again from accumulated payments. CDK's fakewallet handles both BOLT11 and BOLT12.                                                                                                                                                                                                                                                                                         |
+| `onchain_example.ts`      | none (uses public test mint)                                                      | Onchain (NUT-30) mint and melt against `https://onchain.cashudevkit.org` on Mutinynet. **Interactive** — pauses while you fund the printed address from the Mutinynet faucet, then continues automatically once the mint detects 2 confirmations.                                                                                                                                                                                          |
+| `auth_mint/`              | Keycloak + CDK mint via docker, **or** Keycloak + locally-built Nutshell BLS mint | OAuth2 / OIDC blind-auth (NUT-21 / NUT-22) demos. CDK variant: `make up`, `make demo` (or `demo-device` / `demo-pkce`), `make down`. Nutshell BLS variant (exercises v3 BLS BAT verification): `make nutshell-up`, `make nutshell-demo` (or `nutshell-demo-device` / `nutshell-demo-pkce`), `make nutshell-down` — requires a sibling `../nutshell` checkout on a branch with cashubtc/nutshell#1004 (override path via `NUT_BLS_PATH=…`). |
+| `paymentApi_example.js`   | —                                                                                 | Code snippet for receiving locked ecash inside a Firebase Cloud Function. Not runnable standalone.                                                                                                                                                                                                                                                                                                                                         |
 
 ## Notes
 

diff --git a/examples/auth_mint/Makefile b/examples/auth_mint/Makefile
@@ -1,6 +1,12 @@
 # One-liner setup / teardown for CDK Mint + Keycloak demo
+#
+# CDK targets (default compose):  up / down / demo / demo-ci / logs / clean
+# Nutshell BLS targets:           nutshell-up / nutshell-down / nutshell-demo
+#                                 nutshell-demo-ci / nutshell-logs / nutshell-clean
+# Nutshell builds from $(NUT_BLS_PATH) (default ../../../nutshell).
 
 COMPOSE = docker compose
+COMPOSE_NUT = $(COMPOSE) -f docker-compose-nutshell.yml
 DEMO_CMD = npx tsx auth_password_example.ts
 DEMO_DEVA = npx tsx auth_device_example.ts
 DEMO_PKCE = npx tsx auth_pkce_example.ts
@@ -43,3 +49,44 @@ demo-pkce:
 clean: down
 	@echo "🧽 Removing any leftover volumes..."
 	docker volume prune -f
+
+# ------------------------
+# Nutshell BLS (v3) variant — Keycloak + locally-built Nutshell auth mint
+# ------------------------
+.PHONY: nutshell-up nutshell-down nutshell-demo nutshell-demo-device nutshell-demo-pkce nutshell-demo-ci nutshell-logs nutshell-clean
+
+nutshell-demo-ci:
+	$(COMPOSE_NUT) up -d --build --force-recreate
+	@sleep 20
+	$(DEMO_CMD)
+	$(COMPOSE_NUT) down -v
+
+nutshell-up:
+	@echo "🚀 Starting Keycloak + Nutshell (BLS, built from $(or $(NUT_BLS_PATH),../../../nutshell))..."
+	$(COMPOSE_NUT) up -d --build --force-recreate
+	@echo "⌛ Waiting for Keycloak + mint to be ready (approx 20s)..."
+	@sleep 20
+	@echo "✅ Containers started. Run 'make nutshell-demo' to execute the auth flow."
+
+nutshell-down:
+	@echo "🧹 Stopping and removing Nutshell containers..."
+	$(COMPOSE_NUT) down -v
+
+nutshell-logs:
+	$(COMPOSE_NUT) logs -f
+
+nutshell-demo:
+	@echo "🧪 Running PASSWORD Auth demo against Nutshell mint..."
+	$(DEMO_CMD)
+
+nutshell-demo-device:
+	@echo "🧪 Running DEVICE Auth demo against Nutshell mint..."
+	$(DEMO_DEVA)
+
+nutshell-demo-pkce:
+	@echo "🧪 Running PKCE Auth demo against Nutshell mint..."
+	$(DEMO_PKCE)
+
+nutshell-clean: nutshell-down
+	@echo "🧽 Removing any leftover volumes..."
+	docker volume prune -f
diff --git a/examples/auth_mint/cashu-realm.json b/examples/auth_mint/cashu-realm.json
@@ -1,6 +1,7 @@
 {
   "realm": "cashu",
   "enabled": true,
+  "sslRequired": "none",
 
   "defaultRoles": ["offline_access", "uma_authorization"],