Version 3.0.0 Migration guide

⚠️ Upgrading to version 3.0.0 will come with breaking changes! Please follow the migration guide for a smooth transition to the new version.

Breaking changes

Renamed Classes and Streamlined instantiation

Version 3 uses new class names:

CashuWallet is now Wallet CashuMint is now Mint

A wallet can be instantiated by passing a Mint instance, as before, or simply by passing in a mintUrl.

You MUST now call the loadMint() method to complete wallet init.

example:

const mintUrl = 'http://localhost:3338';
const wallet1 = new Wallet(mintUrl); // unit is 'sat'
await wallet1.loadMint(); // wallet is now ready to use
Copy

Crypto Library

The sub-module exports for the Crypto Library have been removed. All functions are now exported from the main library index.

example:

import { signP2PKProofs } from '@cashu/cashu-ts/crypto/client/NUT11';
import { isP2PKSpendAuthorised } from '@cashu/cashu-ts/crypto/mint/NUT11';
Copy

is now:

import { signP2PKProofs, isP2PKSpendAuthorised } from '@cashu/cashu-ts';
Copy

Some crypto types have been deduplicated to the main library types:

• Proof is now RawProof
• MintKeys is now RawMintKeys
• Keyset and KeysetWithKeys have been removed as unused

Function signature changes:

• signP2PKProofs: The optional beStrict param has been replaced with a logger.

// third (optional) param:
signP2PKProofs = (
	proofs: Proof[], privateKey: string | string[], beStrict = false
): Proof[]

// is now a logger:
signP2PKProofs = (
	proofs: Proof[], privateKey: string | string[], logger: Logger = NULL_LOGGER
): Proof[]
Copy

New OutputType and OutputConfig

The output model for send, receive, mintProofs, and meltProofs has been simplified.

Instead of juggling keepFactory, outputData, and multiple option types, you now use:

• OutputType — a tagged union describing one output strategy (random, deterministic, p2pk, etc).
• OutputConfig — combines keep and send OutputTypes when sending.

These are passed as the FOURTH parameter where needed, or expressed more naturally via the new WalletOps fluent builder API.

Example:

// before
const { keep, send } = await wallet.send(amount, proofs, {
  includeFees: true,
  pubkey: bytesToHex(pubKeyBob),
});

// after (using fluent builder)
const { keep, send } = await wallet.ops
  .send(amount, proofs)
  .asP2PK({ pubkey: bytesToHex(pubKeyBob) })
  .includeFees(true)
  .run();

// or using the forth param directly
const customConfig: OutputConfig = {
  send: { type: 'p2pk', options: { pubkey: bytesToHex(pubKeyBob) } },
  keep: { type: 'deterministic', counter: 0 }, // optional keep shaping
};
const { keep, send } = await wallet.send(
  amount,
  proofs,
  { includeFees: true },
  customConfig, // forth param
);
Copy

The builder makes intent explicit and eliminates the need for extra boilerplate.

See the README and integration tests for more usage examples.

OutputDataLike / OutputDataFactory

OutputData helpers only require id and keys, so OutputDataLike and OutputDataFactory now default to HasKeysetKeys, which just includes id and keys.

This may show up as a TypeScript error when assigning a factory that takes MintKeys to OutputDataFactory without a type argument.

If you want richer typing at the call site, use the new generics: OutputDataLike<YourType> and OutputDataFactory<YourType>.

For example, if your custom factory is typed to MintKeys, declare it as OutputDataFactory<MintKeys>.

// Factory typed to MintKeys
const customFactory: OutputDataFactory<MintKeys> = (amount, keyset) => {
  return OutputData.createRandomData(amount, keyset)[0];
};

// Factory typed to default (HasKeysetKeys: { id, keys })
const customFactory: OutputDataFactory = (amount, keysetKeys) => {
  return OutputData.createRandomData(amount, keysetKeys)[0];
};
Copy

Logger

LogLevel is no longer exported as a const object with uppercase values. It is now a simple string union of lowercase level names.

Fatal level has also been removed:

// New LogLevel shape (lowercase, no 'fatal' level)
export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';

// before
const logger = new ConsoleLogger(LogLevel.DEBUG);

// after
const logger = new ConsoleLogger('debug');
Copy

This change simplifies the API by removing the enum-like wrapper, avoids the need for extra imports, and makes configuration easier when log levels are provided from JSON or environment variables (which are typically lowercase).

Update any code that referenced LogLevel.XYZ to pass the lowercase string literal instead.

Keyset methods delegated to KeyChain class

Wallet no longer manages keysets and keys itself. Instead, these are delegated to the KeyChain class, accessed via wallet.keyChain.

The following wallet methods are affected:

• wallet.getKeys(id?) -> wallet.keyChain.getKeyset(id?)
• wallet.getActiveKeyset() -> wallet.keyChain.getCheapestKeyset()
• wallet.getKeySets() -> wallet.keyChain.getKeysets()
• wallet.getAllKeys() -> wallet.keyChain.getAllKeys()

getDecodedToken signature update

getDecodedToken now prefers a string[] of full keyset IDs as its second argument. The older signature that accepted keyset-like objects is deprecated.

This matters for keysets v2 support: when decoding outside a wallet instance, pass the full list of keyset IDs the token might reference, for example from wallet.keyChain.getAllKeysetIds().

// before
const token = getDecodedToken(tokenString);

// after
const token = getDecodedToken(tokenString, wallet.keyChain.getAllKeysetIds());
Copy

If you already have a wallet for the token's mint and unit, prefer wallet.decodeToken(tokenString).

For pre-wallet init, you can use the new getTokenMetadata function to inspect a token string and find out which mint and unit the token belongs to.

Treat the extracted mint as untrusted input. Validate it against your own trusted-mint policy before creating a Wallet or calling loadMint(), especially in server-side code.

NOTE: Although still optional, the second parameter of getDecodedToken is REQUIRED if you wish to support keysets v2.

on[Mint|Melt|Proof]* events

Wallet no longer manages subscription events itself. Instead, these are delegated to the WalletEvents class, accessed via wallet.on.

The following wallet methods are affected:

• wallet.onMintQuoteUpdates() -> wallet.on.mintQuoteUpdates()
• wallet.onMeltQuotePaid() -> wallet.on.meltQuotePaid()
• wallet.onMintQuotePaid() -> wallet.on.mintQuotePaid()
• wallet.onMeltQuoteUpdates() -> wallet.on.meltQuoteUpdates()
• wallet.onProofStateUpdates() -> wallet.on.proofStateUpdates()

See the README for full details of the WalletEvents API.

Removed constants

The following constants are no longer available:

• DEFAULT_DENOMINATION_TARGET
• DEFAULT_UNIT
• TOKEN_VERSION
• TOKEN_PREFIX

Method changes in Mint

Static methods The Mint class no longer has static methods. If you wish to call a mint method, simply instantiate a mint first, then call the instance method.

The following method names have changed:

• async createMintQuote -> createMintQuoteBolt11
• async checkMintQuote -> checkMintQuoteBolt11
• async createMeltQuote -> createMeltQuoteBolt11
• async checkMeltQuote -> checkMeltQuoteBolt11
• async melt -> meltBolt11

The second parameter (was customRequest) is now an options object in the following methods:

- async meltBolt11(
		meltPayload: MeltPayload,
		options?: {
			customRequest?: RequestFn;
			preferAsync?: boolean;
		}
	)
- async meltBolt12(
		meltPayload: MeltPayload,
		options?: {
			customRequest?: RequestFn;
			preferAsync?: boolean;
		}
	)
Copy

Auth Changes

Clear and Blind authentication have been simplified and enhanced. Here are the highlights:

• Legacy CashuAuthMint / CashuAuthWallet have been removed.
• A new AuthManager provides "Batteries Included" CAT/BAT management.
• createAuthWallet() helper wires up a fully authenticated wallet session.
• OIDCAuth class handles the mechanics of OIDC authentication
• Mint replaces the authTokenGetter param with options, including an authProvider.

Before: new Mint(mintUrl, customRequest?, legacyAuthTokenGetter?)
After:  new Mint(mintUrl, options?: {customRequest?, authProvider?, logger?})
Copy

See the examples/auth_mint/ folder for examples of using these in all supported flows.

---