@midnight-ntwrk/wallet-sdk-capabilities 3.0.0-beta.9 → 3.0.0

package/README.md

@@ -1,3 +1,126 @@
-# Midnight Wallet SDK Capabilities
+# @midnight-ntwrk/wallet-sdk-capabilities
 
-This package provides a range of capabilities used only internally by the wallet when implementing `@midnight-ntwrk/wallet-api`. The version of the package is focused only in transaction balancing.
+Internal wallet capabilities for transaction balancing on the Midnight network.
+
+## Installation
+
+```bash
+npm install @midnight-ntwrk/wallet-sdk-capabilities
+```
+
+## Overview
+
+This package provides core transaction balancing capabilities used internally by wallet implementations. It handles the
+complex logic of selecting inputs and creating outputs to balance transactions while accounting for fee overhead costs.
+
+Key features:
+
+- Transaction balancing algorithms
+- Coin selection strategies
+- Imbalance tracking and resolution
+- Fee-aware counter-offer generation
+
+## Usage
+
+### Basic Transaction Balancing
+
+```typescript
+import { getBalanceRecipe, Imbalances, chooseCoin } from '@midnight-ntwrk/wallet-sdk-capabilities';
+
+const recipe = getBalanceRecipe({
+  coins: availableCoins,
+  initialImbalances: Imbalances.fromEntry('NIGHT', -1000n), // Need 1000 NIGHT
+  transactionCostModel: {
+    inputFeeOverhead: 1000n,
+    outputFeeOverhead: 500n,
+  },
+  feeTokenType: 'DUST',
+  createOutput: (coin) => ({ type: coin.type, value: coin.value }),
+  isCoinEqual: (a, b) => a.id === b.id,
+  coinSelection: chooseCoin, // Optional: defaults to smallest-first selection
+});
+
+console.log('Inputs to add:', recipe.inputs);
+console.log('Outputs to create:', recipe.outputs);
+```
+
+### Working with Imbalances
+
+```typescript
+import { Imbalances } from '@midnight-ntwrk/wallet-sdk-capabilities';
+
+// Create imbalances from entries
+const imbalances = Imbalances.fromEntries([
+  ['NIGHT', -500n], // Need 500 NIGHT (negative = deficit)
+  ['TOKEN_A', 200n], // Have 200 TOKEN_A excess (positive = surplus)
+]);
+
+// Merge imbalances
+const merged = Imbalances.merge(imbalances1, imbalances2);
+
+// Get value for a token type
+const nightImbalance = Imbalances.getValue(imbalances, 'NIGHT');
+```
+
+### Custom Coin Selection
+
+```typescript
+import { getBalanceRecipe, CoinSelection } from '@midnight-ntwrk/wallet-sdk-capabilities';
+
+// Custom strategy: prefer larger coins
+const largestFirst: CoinSelection<MyCoin> = (coins, tokenType, amountNeeded, costModel) => {
+  return coins
+    .filter((coin) => coin.type === tokenType)
+    .sort((a, b) => Number(b.value - a.value))
+    .at(0);
+};
+
+const recipe = getBalanceRecipe({
+  // ... other options
+  coinSelection: largestFirst,
+});
+```
+
+### Error Handling
+
+```typescript
+import { getBalanceRecipe, InsufficientFundsError } from '@midnight-ntwrk/wallet-sdk-capabilities';
+
+try {
+  const recipe = getBalanceRecipe({
+    /* ... */
+  });
+} catch (error) {
+  if (error instanceof InsufficientFundsError) {
+    console.log(`Cannot balance: insufficient ${error.tokenType}`);
+  }
+}
+```
+
+## Exports
+
+### Balancer
+
+- `getBalanceRecipe` - Main function to calculate inputs/outputs needed to balance a transaction
+- `createCounterOffer` - Creates counter offers with cost model awareness
+- `chooseCoin` - Default coin selection strategy (smallest coin first)
+- `InsufficientFundsError` - Error thrown when balancing fails due to insufficient funds
+- `BalanceRecipe` - Type for balance result with inputs and outputs
+- `CoinSelection` - Type for coin selection function
+
+### Imbalances
+
+- `Imbalances` - Utilities for creating and manipulating token imbalance maps
+- `Imbalance` - Type representing a single token imbalance `[TokenType, TokenValue]`
+- `TokenType` - String type alias for token identifiers
+- `TokenValue` - Bigint type alias for token amounts
+- `CoinRecipe` - Interface for basic coin structure with `type` and `value`
+
+### CounterOffer
+
+- `CounterOffer` - Class for building balanced transactions with fee awareness
+- `TransactionCostModel` - Interface defining `inputFeeOverhead` and `outputFeeOverhead`
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-capabilities",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,25 +24,26 @@
     }
   },
   "dependencies": {
-    "@midnight-ntwrk/wallet-sdk-address-format": "3.0.0-beta.9",
-    "@midnight-ntwrk/wallet-sdk-hd": "3.0.0-beta.7",
-    "effect": "^3.17.3"
+    "@midnight-ntwrk/wallet-sdk-address-format": "3.0.0",
+    "@midnight-ntwrk/wallet-sdk-hd": "3.0.0",
+    "effect": "^3.19.14"
   },
   "devDependencies": {
-    "@midnight-ntwrk/ledger-v6": "6.1.0-alpha.6",
+    "@midnight-ntwrk/ledger-v7": "7.0.0",
     "eslint": "^9.37.0",
     "fast-check": "^4.2.0",
+    "prettier": "^3.7.0",
     "publint": "~0.3.14",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.16"
   },
   "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}\"",
+    "format": "prettier --write \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml,md}\"",
     "dist": "tsc -b ./tsconfig.build.json",
     "dist:publish": "tsc -b ./tsconfig.publish.json",
     "clean": "rimraf --glob dist 'tsconfig.*.tsbuildinfo' && date +%s > .clean-timestamp",