@midnightntwrk/wallet-sdk-address-format 3.1.2

package/README.md

@@ -0,0 +1,175 @@
+# @midnightntwrk/wallet-sdk-address-format
+
+Bech32m address encoding and decoding for the Midnight network.
+
+## Installation
+
+```bash
+npm install @midnightntwrk/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 '@midnightntwrk/wallet-sdk-address-format';
+import type { NetworkId } from '@midnightntwrk/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 '@midnightntwrk/wallet-sdk-address-format';
+import type { NetworkId } from '@midnightntwrk/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 '@midnightntwrk/wallet-sdk-address-format';
+import type { NetworkId } from '@midnightntwrk/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

@@ -0,0 +1,104 @@
+import { type DustPublicKey, EncryptionSecretKey, type UserAddress } from '@midnight-ntwrk/ledger-v8';
+export declare const mainnet: unique symbol;
+type NetworkId = string | typeof mainnet;
+declare const NetworkId: {
+    toString: (networkId: NetworkId) => string;
+};
+export type FormatContext = {
+    networkId: NetworkId;
+};
+export type Field = {
+    bytes: number;
+    modulus: bigint;
+};
+export declare const BLSScalar: Field;
+export declare const ScaleBigInt: {
+    encode: (data: bigint) => Buffer;
+    decode: (repr: Uint8Array) => bigint;
+};
+export declare const Bech32mSymbol: unique symbol;
+export type HasCodec<T> = {
+    [Bech32mSymbol]: Bech32mCodec<T>;
+};
+export type CodecTarget<T> = T extends HasCodec<infer U> ? U : never;
+export declare class MidnightBech32m {
+    static readonly prefix = "mn";
+    static encode<T extends HasCodec<T>>(networkId: NetworkId, item: T): MidnightBech32m;
+    static validateSegment(segmentName: string, segment: string): void;
+    static parse(bech32string: string): MidnightBech32m;
+    readonly type: string;
+    readonly network: NetworkId;
+    readonly data: Buffer;
+    constructor(type: string, network: NetworkId, data: Buffer);
+    decode<TClass extends HasCodec<any>>(tclass: TClass, networkId: NetworkId): CodecTarget<TClass>;
+    asString(): string;
+    toString(): string;
+}
+export declare class Bech32mCodec<T> {
+    readonly type: string;
+    readonly dataToBytes: (data: T) => Buffer;
+    readonly dataFromBytes: (bytes: Buffer) => T;
+    constructor(type: string, dataToBytes: (data: T) => Buffer, dataFromBytes: (bytes: Buffer) => T);
+    encode(networkId: NetworkId, data: T): MidnightBech32m;
+    decode(networkId: NetworkId, repr: MidnightBech32m): T;
+    static createContext(networkId: NetworkId): FormatContext;
+}
+export declare class ShieldedAddress {
+    static readonly codec: Bech32mCodec<ShieldedAddress>;
+    static readonly [Bech32mSymbol]: Bech32mCodec<ShieldedAddress>;
+    readonly [Bech32mSymbol]: Bech32mCodec<ShieldedAddress>;
+    readonly coinPublicKey: ShieldedCoinPublicKey;
+    readonly encryptionPublicKey: ShieldedEncryptionPublicKey;
+    constructor(coinPublicKey: ShieldedCoinPublicKey, encryptionPublicKey: ShieldedEncryptionPublicKey);
+    coinPublicKeyString(): string;
+    encryptionPublicKeyString(): string;
+    equals(other: ShieldedAddress): boolean;
+}
+export declare class ShieldedEncryptionSecretKey {
+    static readonly codec: Bech32mCodec<ShieldedEncryptionSecretKey>;
+    readonly zswap: EncryptionSecretKey;
+    constructor(zswap: EncryptionSecretKey);
+}
+export declare class ShieldedCoinPublicKey {
+    static readonly keyLength = 32;
+    static readonly codec: Bech32mCodec<ShieldedCoinPublicKey>;
+    static fromHexString(hexString: string): ShieldedCoinPublicKey;
+    readonly data: Buffer;
+    constructor(data: Buffer);
+    toHexString(): string;
+    equals(other: string): boolean;
+    equals(other: ShieldedCoinPublicKey): boolean;
+}
+export declare class ShieldedEncryptionPublicKey {
+    static readonly keyLength = 32;
+    static readonly codec: Bech32mCodec<ShieldedEncryptionPublicKey>;
+    static fromHexString(hexString: string): ShieldedEncryptionPublicKey;
+    readonly data: Buffer;
+    constructor(data: Buffer);
+    toHexString(): string;
+    equals(other: string): boolean;
+    equals(other: ShieldedEncryptionPublicKey): boolean;
+}
+export declare class UnshieldedAddress {
+    readonly data: Buffer;
+    static readonly keyLength = 32;
+    static readonly codec: Bech32mCodec<UnshieldedAddress>;
+    static readonly [Bech32mSymbol]: Bech32mCodec<UnshieldedAddress>;
+    readonly [Bech32mSymbol]: Bech32mCodec<UnshieldedAddress>;
+    constructor(data: Buffer);
+    get hexString(): UserAddress;
+    equals(other: string): boolean;
+    equals(other: UnshieldedAddress): boolean;
+}
+export declare class DustAddress {
+    readonly data: bigint;
+    static readonly codec: Bech32mCodec<DustAddress>;
+    static readonly [Bech32mSymbol]: Bech32mCodec<DustAddress>;
+    readonly [Bech32mSymbol]: Bech32mCodec<DustAddress>;
+    static readonly encodePublicKey: (networkId: string, publicKey: DustPublicKey) => string;
+    constructor(data: bigint);
+    serialize(): Buffer;
+    equals(other: bigint): boolean;
+    equals(other: DustAddress): boolean;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,233 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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-v8';
+import { bech32m } from '@scure/base';
+import * as subsquidScale from '@subsquid/scale-codec';
+export const mainnet = Symbol('Mainnet');
+const NetworkId = {
+    toString: (networkId) => {
+        return networkId === mainnet ? 'mainnet' : networkId;
+    },
+};
+export const BLSScalar = {
+    bytes: 32,
+    modulus: BigInt('0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001'),
+};
+export const ScaleBigInt = {
+    encode: (data) => {
+        const sink = new subsquidScale.ByteSink();
+        sink.compact(data);
+        return Buffer.from(sink.toBytes());
+    },
+    decode: (repr) => {
+        const src = new subsquidScale.Src(repr);
+        const res = src.compact();
+        src.assertEOF();
+        return BigInt(res);
+    },
+};
+export const Bech32mSymbol = Symbol('MidnightBech32m');
+export class MidnightBech32m {
+    static prefix = 'mn';
+    static encode(networkId, item) {
+        return item[Bech32mSymbol].encode(networkId, item);
+    }
+    static validateSegment(segmentName, segment) {
+        const result = /^[A-Za-z1-9-]+$/.test(segment);
+        if (!result) {
+            throw new Error(`Segment ${segmentName}: ${segment} contains disallowed characters. Allowed characters are only numbers, latin letters and a hyphen`);
+        }
+    }
+    static parse(bech32string) {
+        const bech32parsed = bech32m.decodeToBytes(bech32string);
+        const [prefix, type, network = mainnet] = bech32parsed.prefix.split('_');
+        if (prefix != MidnightBech32m.prefix) {
+            throw new Error(`Expected prefix ${MidnightBech32m.prefix}`);
+        }
+        MidnightBech32m.validateSegment('type', type);
+        if (network != mainnet) {
+            MidnightBech32m.validateSegment('network', network);
+        }
+        return new MidnightBech32m(type, network, Buffer.from(bech32parsed.bytes));
+    }
+    type;
+    network;
+    data;
+    constructor(type, network, data) {
+        this.data = data;
+        this.network = network;
+        this.type = type;
+        MidnightBech32m.validateSegment('type', type);
+        if (network != mainnet) {
+            MidnightBech32m.validateSegment('network', network);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    decode(tclass, networkId) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return tclass[Bech32mSymbol].decode(networkId, this);
+    }
+    asString() {
+        const networkSegment = this.network == mainnet ? '' : `_${this.network}`;
+        return bech32m.encode(`${MidnightBech32m.prefix}_${this.type}${networkSegment}`, bech32m.toWords(this.data), false);
+    }
+    toString() {
+        return this.asString();
+    }
+}
+export class Bech32mCodec {
+    type;
+    dataToBytes;
+    dataFromBytes;
+    constructor(type, dataToBytes, dataFromBytes) {
+        this.dataFromBytes = dataFromBytes;
+        this.dataToBytes = dataToBytes;
+        this.type = type;
+    }
+    encode(networkId, data) {
+        const context = Bech32mCodec.createContext(networkId);
+        return new MidnightBech32m(this.type, context.networkId, this.dataToBytes(data));
+    }
+    decode(networkId, repr) {
+        const context = Bech32mCodec.createContext(networkId);
+        if (repr.type != this.type) {
+            throw new Error(`Expected type ${this.type}, got ${repr.type}`);
+        }
+        if (context.networkId != repr.network) {
+            throw new Error(`Expected ${NetworkId.toString(context.networkId)} address, got ${NetworkId.toString(repr.network)} one`);
+        }
+        return this.dataFromBytes(repr.data);
+    }
+    static createContext(networkId) {
+        if (networkId === 'mainnet') {
+            return { networkId: mainnet };
+        }
+        else {
+            return { networkId };
+        }
+    }
+}
+export class ShieldedAddress {
+    static codec = new Bech32mCodec('shield-addr', (addr) => Buffer.concat([addr.coinPublicKey.data, addr.encryptionPublicKey.data]), (bytes) => {
+        const coinPublicKey = new ShieldedCoinPublicKey(bytes.subarray(0, ShieldedCoinPublicKey.keyLength));
+        const encryptionPublicKey = new ShieldedEncryptionPublicKey(bytes.subarray(ShieldedCoinPublicKey.keyLength));
+        return new ShieldedAddress(coinPublicKey, encryptionPublicKey);
+    });
+    static [Bech32mSymbol] = ShieldedAddress.codec;
+    [Bech32mSymbol] = ShieldedAddress.codec;
+    coinPublicKey;
+    encryptionPublicKey;
+    constructor(coinPublicKey, encryptionPublicKey) {
+        this.encryptionPublicKey = encryptionPublicKey;
+        this.coinPublicKey = coinPublicKey;
+    }
+    coinPublicKeyString() {
+        return this.coinPublicKey.data.toString('hex');
+    }
+    encryptionPublicKeyString() {
+        return this.encryptionPublicKey.data.toString('hex');
+    }
+    equals(other) {
+        return this.coinPublicKey.equals(other.coinPublicKey) && this.encryptionPublicKey.equals(other.encryptionPublicKey);
+    }
+}
+export class ShieldedEncryptionSecretKey {
+    static codec = new Bech32mCodec('shield-esk', (esk) => Buffer.from(esk.zswap.yesIKnowTheSecurityImplicationsOfThis_serialize()), (repr) => new ShieldedEncryptionSecretKey(EncryptionSecretKey.deserialize(repr)));
+    // There are some bits in serialization of field elements and elliptic curve points, that are hard to replicate
+    // Thus using zswap implementation directly for serialization purposes
+    zswap;
+    constructor(zswap) {
+        this.zswap = zswap;
+    }
+}
+export class ShieldedCoinPublicKey {
+    static keyLength = 32;
+    static codec = new Bech32mCodec('shield-cpk', (cpk) => cpk.data, (repr) => new ShieldedCoinPublicKey(repr));
+    static fromHexString(hexString) {
+        return new ShieldedCoinPublicKey(Buffer.from(hexString, 'hex'));
+    }
+    data;
+    constructor(data) {
+        this.data = data;
+        if (data.length != ShieldedCoinPublicKey.keyLength) {
+            throw new Error('Coin public key needs to be 32 bytes long');
+        }
+    }
+    toHexString() {
+        return this.data.toString('hex');
+    }
+    equals(other) {
+        const otherKey = typeof other === 'string' ? ShieldedCoinPublicKey.fromHexString(other) : other;
+        return otherKey.data.equals(this.data);
+    }
+}
+export class ShieldedEncryptionPublicKey {
+    static keyLength = 32;
+    static codec = new Bech32mCodec('shield-epk', (cpk) => cpk.data, (repr) => new ShieldedEncryptionPublicKey(repr));
+    static fromHexString(hexString) {
+        return new ShieldedEncryptionPublicKey(Buffer.from(hexString, 'hex'));
+    }
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    toHexString() {
+        return this.data.toString('hex');
+    }
+    equals(other) {
+        const otherKey = typeof other === 'string' ? ShieldedEncryptionPublicKey.fromHexString(other) : other;
+        return otherKey.data.equals(this.data);
+    }
+}
+export class UnshieldedAddress {
+    data;
+    static keyLength = 32;
+    static codec = new Bech32mCodec('addr', (addr) => addr.data, (repr) => new UnshieldedAddress(repr));
+    static [Bech32mSymbol] = UnshieldedAddress.codec;
+    [Bech32mSymbol] = UnshieldedAddress.codec;
+    constructor(data) {
+        if (data.length != UnshieldedAddress.keyLength) {
+            throw new Error('Unshielded address needs to be 32 bytes long');
+        }
+        this.data = data;
+    }
+    get hexString() {
+        return this.data.toString('hex');
+    }
+    equals(other) {
+        const otherAddress = typeof other === 'string' ? new UnshieldedAddress(Buffer.from(other, 'hex')) : other;
+        return otherAddress.data.equals(this.data);
+    }
+}
+export class DustAddress {
+    data;
+    static codec = new Bech32mCodec('dust', (daddr) => daddr.serialize(), (repr) => new DustAddress(ScaleBigInt.decode(repr)));
+    static [Bech32mSymbol] = DustAddress.codec;
+    [Bech32mSymbol] = DustAddress.codec;
+    static encodePublicKey = (networkId, publicKey) => {
+        return DustAddress.codec.encode(networkId, new DustAddress(publicKey)).asString();
+    };
+    constructor(data) {
+        if (data >= BLSScalar.modulus) {
+            throw new Error('Dust address is too large');
+        }
+        this.data = data;
+    }
+    serialize() {
+        return ScaleBigInt.encode(this.data);
+    }
+    equals(other) {
+        const otherAddress = typeof other === 'bigint' ? other : other.data;
+        return otherAddress === this.data;
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@midnightntwrk/wallet-sdk-address-format",
+  "version": "3.1.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Midnight Foundation",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/midnightntwrk/midnight-wallet.git",
+    "directory": "packages/address-format"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@midnight-ntwrk/ledger-v8": "^8.1.0",
+    "@scure/base": "^2.0.0",
+    "@subsquid/scale-codec": "^4.0.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -b ./tsconfig.json --noEmit --force",
+    "test": "vitest run",
+    "lint": "eslint --max-warnings 0",
+    "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",
+    "publint": "publint --strict"
+  }
+}