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

package/README.md

@@ -1,3 +1,175 @@
-# Midnight Wallet SDK Address Format
+# @midnight-ntwrk/wallet-sdk-address-format
 
-This package provides support for the Bech32m address format.
+Bech32m address encoding and decoding for the Midnight network.
+
+## Installation
+
+```bash
+npm install @midnight-ntwrk/wallet-sdk-address-format
+```
+
+## Overview
+
+This package provides Bech32m address formatting for the Midnight blockchain. It supports encoding and decoding of
+various address types including shielded addresses (for ZK transactions), unshielded addresses (for transparent
+transactions), and dust addresses (for fee tokens).
+
+Key features:
+
+- Bech32m encoding/decoding with Midnight-specific prefix (`mn_`)
+- Network-aware address formatting (mainnet vs testnet)
+- Support for shielded, unshielded, and dust address types
+- Type-safe codec system for custom address types
+
+## Usage
+
+### Unshielded Address
+
+For transparent transactions on the Midnight network.
+
+```typescript
+import { UnshieldedAddress, MidnightBech32m, mainnet } from '@midnight-ntwrk/wallet-sdk-address-format';
+import type { NetworkId } from '@midnight-ntwrk/wallet-sdk-address-format';
+import { addressFromKey, signatureVerifyingKey } from '@midnight-ntwrk/ledger-v7';
+import { randomBytes } from 'node:crypto';
+
+const networkId: NetworkId = 'preview';
+
+// Derive an unshielded address from a random unshielded secret key
+const secretKey = randomBytes(32);
+const publicKey = signatureVerifyingKey(secretKey.toString('hex'));
+const addressHex = addressFromKey(publicKey);
+const unshieldedAddress = new UnshieldedAddress(Buffer.from(addressHex, 'hex'));
+
+// Encode to Bech32m string: mn_addr_preview1...
+const encoded = MidnightBech32m.encode(networkId, unshieldedAddress).toString();
+
+// Parse and decode back to UnshieldedAddress
+const decoded = MidnightBech32m.parse(encoded).decode(UnshieldedAddress, networkId);
+
+// Compare addresses
+unshieldedAddress.equals(decoded); // true
+
+// Mainnet addresses omit the network suffix: mn_addr1...
+const mainnetEncoded = MidnightBech32m.encode(mainnet, unshieldedAddress).toString();
+```
+
+### Shielded Address
+
+For zero-knowledge transactions on the Midnight network.
+
+```typescript
+import {
+  ShieldedAddress,
+  ShieldedCoinPublicKey,
+  ShieldedEncryptionPublicKey,
+  MidnightBech32m,
+} from '@midnight-ntwrk/wallet-sdk-address-format';
+import type { NetworkId } from '@midnight-ntwrk/wallet-sdk-address-format';
+import * as ledger from '@midnight-ntwrk/ledger-v7';
+import { randomBytes } from 'node:crypto';
+
+const networkId: NetworkId = 'preview';
+
+// Create shielded keys from a seed
+const shieldedSeed = randomBytes(32); // Your 32-byte seed
+const shieldedKeys = ledger.ZswapSecretKeys.fromSeed(shieldedSeed);
+
+// Create a shielded address from the keys
+const shieldedAddress = new ShieldedAddress(
+  new ShieldedCoinPublicKey(Buffer.from(shieldedKeys.coinPublicKey, 'hex')),
+  new ShieldedEncryptionPublicKey(Buffer.from(shieldedKeys.encryptionPublicKey, 'hex')),
+);
+
+// Encode to Bech32m string: mn_shield-addr_preview1...
+const encoded = MidnightBech32m.encode(networkId, shieldedAddress).toString();
+
+// Parse and decode back to ShieldedAddress
+const decoded = MidnightBech32m.parse(encoded).decode(ShieldedAddress, networkId);
+
+// Access individual key components
+decoded.coinPublicKeyString();
+decoded.encryptionPublicKeyString();
+```
+
+### Dust Address
+
+For fee token operations on the Midnight network.
+
+```typescript
+import { DustAddress, MidnightBech32m } from '@midnight-ntwrk/wallet-sdk-address-format';
+import type { NetworkId } from '@midnight-ntwrk/wallet-sdk-address-format';
+import * as ledger from '@midnight-ntwrk/ledger-v7';
+import { randomBytes } from 'node:crypto';
+
+const networkId: NetworkId = 'preview';
+
+// Create a dust secret key from a seed
+const dustSeed = randomBytes(32); // Your 32-byte seed
+const dustSecretKey = ledger.DustSecretKey.fromSeed(dustSeed);
+
+// Create a dust address from the public key
+const dustAddress = new DustAddress(dustSecretKey.publicKey);
+
+// Encode to Bech32m string: mn_dust_preview1...
+const encoded = MidnightBech32m.encode(networkId, dustAddress).toString();
+
+// Parse and decode back to DustAddress
+const decoded = MidnightBech32m.parse(encoded).decode(DustAddress, networkId);
+```
+
+## Address Format
+
+All Midnight addresses use the Bech32m encoding with the following structure:
+
+```
+mn_<type>[_<network>]1<data>
+```
+
+- `mn` - Midnight prefix
+- `type` - Address type identifier (e.g., `shield-addr`, `addr`, `dust`)
+- `network` - Optional network identifier (omitted for mainnet)
+- `data` - Bech32m-encoded payload
+
+### Address Types
+
+| Type              | Bech32m Type  | Description                                                |
+| ----------------- | ------------- | ---------------------------------------------------------- |
+| Shielded          | `shield-addr` | Combined coin + encryption public keys for ZK transactions |
+| Coin Public Key   | `shield-cpk`  | Shielded coin public key only                              |
+| Encryption Key    | `shield-epk`  | Shielded encryption public key only                        |
+| Encryption Secret | `shield-esk`  | Shielded encryption secret key                             |
+| Unshielded        | `addr`        | Public address for transparent transactions                |
+| Dust              | `dust`        | Address for fee token operations                           |
+
+## Exports
+
+### Core Classes
+
+- `MidnightBech32m` - Main class for parsing and encoding Bech32m addresses
+- `Bech32mCodec` - Generic codec for creating custom address types
+
+### Address Types
+
+- `ShieldedAddress` - Full shielded address with coin and encryption keys
+- `ShieldedCoinPublicKey` - 32-byte coin public key
+- `ShieldedEncryptionPublicKey` - 32-byte encryption public key
+- `ShieldedEncryptionSecretKey` - Encryption secret key wrapper
+- `UnshieldedAddress` - 32-byte transparent address
+- `DustAddress` - Fee token address using BLS scalar
+
+### Types and Constants
+
+- `NetworkId` - Type for network identification (`mainnet` symbol or string)
+- `mainnet` - Symbol representing the mainnet network
+- `FormatContext` - Context type for encoding/decoding
+- `BLSScalar` - BLS curve scalar field definition
+- `ScaleBigInt` - SCALE codec utilities for bigint encoding
+- `Bech32mSymbol` - Symbol for codec attachment
+- `HasCodec` - Type helper for codec-enabled classes
+- `CodecTarget` - Type helper for extracting codec target type
+- `Field` - Type for field definitions
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DustPublicKey, EncryptionSecretKey, UserAddress } from '@midnight-ntwrk/ledger-v6';
+import { DustPublicKey, EncryptionSecretKey, UserAddress } from '@midnight-ntwrk/ledger-v7';
 export declare const mainnet: unique symbol;
 export type NetworkId = string | typeof mainnet;
 export type FormatContext = {

package/dist/index.js

@@ -10,7 +10,7 @@
 // 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 { EncryptionSecretKey } from '@midnight-ntwrk/ledger-v6';
+import { EncryptionSecretKey } from '@midnight-ntwrk/ledger-v7';
 import { bech32m } from '@scure/base';
 import * as subsquidScale from '@subsquid/scale-codec';
 export const mainnet = Symbol('Mainnet');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-address-format",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,24 +24,25 @@
     }
   },
   "dependencies": {
-    "@midnight-ntwrk/ledger-v6": "6.1.0-alpha.6",
+    "@midnight-ntwrk/ledger-v7": "7.0.0",
     "@scure/base": "^1.2.6",
     "@subsquid/scale-codec": "^4.0.1"
   },
   "devDependencies": {
     "@types/node": "22.17.0",
     "eslint": "^9.37.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",