# @midnightntwrk/wallet-sdk-address-format

> Bech32m address encoding and decoding for the Midnight network.

Latest version **3.1.2** (published 2026-06-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @midnightntwrk/wallet-sdk-address-format
pnpm add @midnightntwrk/wallet-sdk-address-format
yarn add @midnightntwrk/wallet-sdk-address-format
bun add @midnightntwrk/wallet-sdk-address-format
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.2 |
| Published | 2026-06-19 |
| First published | 2026-06-19 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 20.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 15 |
| Author | Midnight Foundation |
| Maintainers | ntwrk-bot |

## Links

- npm: https://www.npmjs.com/package/@midnightntwrk/wallet-sdk-address-format
- Repository: https://github.com/midnightntwrk/midnight-wallet
- Homepage: https://github.com/midnightntwrk/midnight-wallet#readme
- Issues: https://github.com/midnightntwrk/midnight-wallet/issues
- npm.io page: https://npm.io/package/@midnightntwrk/wallet-sdk-address-format

## Dependencies (3)

- [@scure/base](https://npm.io/package/@scure/base.md) ^2.0.0
- [@subsquid/scale-codec](https://npm.io/package/@subsquid/scale-codec.md) ^4.0.1
- [@midnight-ntwrk/ledger-v8](https://npm.io/package/@midnight-ntwrk/ledger-v8.md) ^8.1.0

## Recent versions

- 3.1.2 (latest) — 2026-06-19
- 4.0.0-canary.20261013150531-6289ea3 (canary) — 2026-10-13
- 3.1.3-canary.20261009161442-8f95733 (canary-v1) — 2026-10-09
- 4.0.0-canary.20261007114939-7ee351c (canary-v2) — 2026-10-07
- 4.0.0-rc.0 (rc) — 2026-09-24
- 4.0.0-beta.4 (beta) — 2026-09-24
- 4.0.0-canary.20261013132526-8a87477 — 2026-10-13
- 4.0.0-canary.20261012130426-60e35b6 — 2026-10-12
- 4.0.0-canary.20261006161905-56542fa — 2026-10-06
- 4.0.0-canary.20261006082857-3c6134f — 2026-10-06
- 3.1.3-canary.20261005170924-1c8b4e7 — 2026-10-05
- 3.1.3-canary.20260930095107-aae483d — 2026-09-30
- 3.1.3-canary.20260929170316-1583a02 — 2026-09-29
- 4.0.0-canary.20260928141213-d0f38b3 — 2026-09-28
- 4.0.0-canary.20260924122254-db9102e — 2026-09-24
- … 82 more at https://npm.io/package/@midnightntwrk/wallet-sdk-address-format/versions

## README

# @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

---
_Source: https://npm.io/package/@midnightntwrk/wallet-sdk-address-format · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._