@miradexio/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiraDex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# @miradex/client
+
+Headless TypeScript SDK for cross-chain swaps. Runs entirely in your
+process — browser, Node.js — and does the
+security-critical work itself: key generation, signing, deposit
+verification, adaptor-signature handling, on-chain state recovery,
+and the BTC↔XMR atomic-swap drive loop. The server proposes state;
+the SDK verifies every claim against an independent on-chain source.
+A compromised server cannot move user funds.
+
+## Providers
+
+| Provider | Pairs | Settlement model |
+| --- | --- | --- |
+| `atomicswap` | BTC ↔ XMR | Cryptographic atomic swap (HTLC + adaptor signatures) |
+| `thorchain` | 13 native gas assets (BTC, ETH, BSC, AVAX, …) | THORChain TSS-managed vaults |
+| `chainflip` | BTC, ETH, ARB, DOT, SOL — multiple assets | Chainflip state-chain deposit channels |
+| `near_intents` | 16 chains | Solver-pulled intent settlement (Defuse 1Click) |
+
+`atomicswap` is the only provider that is non-custodial in the strict
+cryptographic sense — funds are never under any third-party control
+at any step. The other three move funds through validator-managed
+vaults or solver escrows; the SDK still verifies every state claim
+against the upstream's own infrastructure, but the atomic-swap
+protocol's trust model is qualitatively different and is documented
+separately in
+[`ATOMIC-SWAP-PAPER.md`](./ATOMIC-SWAP-PAPER.md).
+Per-provider trust analysis is in [`PROTOCOLS.md`](./PROTOCOLS.md).
+
+---
+
+## Table of contents
+
+- [@miradex/client](#miradexclient)
+  - [Providers](#providers)
+  - [Table of contents](#table-of-contents)
+  - [Quick start](#quick-start)
+  - [Providers](#providers-1)
+    - [`atomicswap`](#atomicswap)
+    - [`thorchain`](#thorchain)
+    - [`chainflip`](#chainflip)
+    - [`near_intents`](#near_intents)
+  - [The SDK surface](#the-sdk-surface)
+    - [Sub-path exports](#sub-path-exports)
+    - [`PlatformAdapter`](#platformadapter)
+    - [Direct entry points](#direct-entry-points)
+    - [Events](#events)
+  - [Security model](#security-model)
+  - [Configuration](#configuration)
+    - [`EngineConfig`](#engineconfig)
+  - [Errors](#errors)
+  - [Build](#build)
+    - [Building from source](#building-from-source)
+  - [License](#license)
+
+---
+
+## Quick start
+
+```bash
+pnpm add @miradex/client
+# or
+npm install @miradex/client
+```
+
+```ts
+import { MiradexEngine, type PlatformAdapter } from '@miradex/client';
+
+const platform: PlatformAdapter = /* see §PlatformAdapter */;
+
+const engine = new MiradexEngine(
+  {
+    apiUrl: 'https://api.miradex.io/',
+    network: 'mainnet',
+    slippageBps: 300,
+  },
+  platform,
+);
+
+engine.on('state', (s) => {
+  console.log(s.activeFlow?.kind, s.activeFlow?.snapshot.phase);
+});
+
+// BTC ↔ XMR (atomicswap)
+await engine.startAtomicSwap({
+  amount: '0.01',
+  destAddress: '8...',
+  refundAddress: 'bc1q...',
+});
+
+// Anything else (thorchain, chainflip, near_intents)
+const { quotes } = await engine.apiClient.getQuotes({
+  from: 'BTC',
+  to: 'ETH',
+  amount: '0.01',
+});
+await engine.startSwap({
+  fromToken: 'BTC',
+  fromChain: 'bitcoin',
+  toToken: 'ETH',
+  toChain: 'ethereum',
+  amount: '0.01',
+  destAddress: '0x...',
+  refundAddress: 'bc1q...',
+  selectedQuote: quotes[0],
+});
+```
+
+The engine takes care of quoting via the server, generating
+client-side keys and persisting the keystore (atomic-swap only),
+driving the swap state machine with verification at every step, and
+emitting `EngineEvents` so a UI can render progress.
+
+The full per-provider drive — every protocol step, every
+verification, every error — lives in
+[`PROTOCOLS.md`](./PROTOCOLS.md). The BTC↔XMR atomic-swap protocol gets
+its own attack-by-attack analysis in
+[`ATOMIC-SWAP-PAPER.md`](./ATOMIC-SWAP-PAPER.md).
+
+---
+
+## Providers
+
+### `atomicswap`
+
+BTC ↔ XMR via the eigenwallet-style two-curve atomic-swap protocol.
+The only provider that is non-custodial in the strict cryptographic
+sense: BTC is locked into a 2-of-2 P2WSH
+(`<A> CHECKSIGVERIFY <B> CHECKSIG`) before XMR is locked, and the
+adaptor-signature construction binds Alice's BTC redemption to
+revealing the Monero scalar Bob needs to derive the joint Monero
+spend key. Refund and punish paths are timelocked Bitcoin script;
+liveness past the cancel window is the only operational requirement
+on Bob.
+
+The SDK independently:
+
+- Verifies Alice's DLEQ proof in WASM before any BTC is broadcast.
+- Derives the lock address locally from `(A, B)` and rejects any
+  server-supplied address that does not match.
+- Recomputes the BIP143 sighash for `TxRedeem` and constant-time
+  compares it against the server's claim before adaptor-signing.
+- Fetches the XMR lock tx from a quorum of monerod nodes, re-derives
+  the joint output key, and rejects `unlock_time != 0`.
+- Verifies the recovered `s_a` satisfies `s_a · G == S_a_monero`
+  before sweeping.
+- Bounds-checks every BIP68 sequence, every fee, and the amnesty
+  amount against the configured policy.
+- Refuses to broadcast `TxLock` without first persisting a recovery
+  snapshot.
+
+If anything goes wrong the SDK can refund autonomously without the
+server: `verifyTxCancel` reads `TxCancel` from Electrum, decrypts
+Alice's `tx_full_refund_encsig` with `s_b`, signs with `b`, and
+broadcasts.
+
+### `thorchain`
+
+13 native gas assets (BTC, ETH, BSC, AVAX, …) via THORChain's Asgard
+threshold-signature vaults. The user deposits the source asset to a
+vault address; THORChain's validator set synthesises the destination
+asset from its liquidity pools and broadcasts an outbound tx to the
+destination address. Failed trades auto-refund to the inbound
+sender.
+
+The SDK independently:
+
+- Reads the active vault list from THORNode and Midgard directly
+  (hardcoded URLs per network in
+  [`thorchain-networks.ts`](./src/verification/thorchain-networks.ts)
+  — the server cannot redirect verification to its own nodes).
+- Confirms the deposit address is an active vault.
+- Parses the registered memo and confirms it binds to the user's
+  destination address.
+
+### `chainflip`
+
+BTC, ETH, ARB, DOT, SOL via Chainflip's per-swap deposit channels.
+Each trade gets a unique deposit address with an explicit
+destination + refund-address binding committed at channel creation.
+The validator set executes the swap and sends the output to the
+bound destination; failures or expiries auto-refund.
+
+The SDK independently:
+
+- Reads the channel from the Chainflip broker REST or state-chain
+  JSON-RPC (hardcoded broker endpoints per network).
+- Confirms the channel's destination and refund addresses match
+  what the user supplied.
+- Confirms the source/destination chains match the requested swap.
+
+### `near_intents`
+
+16 chains (TRON, TON, XRP, Optimism, Doge, BCH, …) via Defuse 1Click.
+The 1Click backend returns a per-quote deposit address; a solver
+fronts the destination asset on the destination chain and claims the
+deposit on the source chain after settlement. 1Click auto-refunds to
+`refundTo` if the deposit lands after deadline or no solver bids.
+
+The SDK independently:
+
+- Reads the intent status from 1Click directly and confirms it is
+  registered.
+- Confirms the deposit address is the one 1Click expects.
+- Surfaces 1Click's terminal status (`SUCCESS` / `FAILED`) verbatim.
+
+---
+
+## The SDK surface
+
+### Sub-path exports
+
+For consumers that want only part of the SDK:
+
+| Sub-path | Contents | When to use |
+| --- | --- | --- |
+| `@miradex/client` | The full SDK (`MiradexEngine`, all flows, all verifiers) | Default |
+| `@miradex/client/portable` | Browser/RN-safe subset; no Node built-ins | Bundlers that fail on Node imports |
+| `@miradex/client/api` | `ApiClient` transport only | Building your own UI without the engine |
+| `@miradex/client/atomic-swap` | BTC↔XMR protocol surface (`runAtomicSwap`, `resumeAtomicSwap`, `submitEncsigWhenReady`) | Standalone atomic-swap consumer |
+| `@miradex/client/atomic-swap/presign` | Pre-sig computation, redeem-digest recompute, `deriveLockAddress` | Independent verification & recovery binaries |
+| `@miradex/client/atomic-swap/refund` | TxFullRefund / TxPartialRefund builders + signer | Standalone refund / recovery tools |
+| `@miradex/client/atomic-swap/monero-sweep` | Monero sweep pipeline | Standalone sweep tool, e.g. for cooperative-redeem |
+| `@miradex/client/verification` | Umbrella for all provider verifiers + helpers | Verify-only consumers (audit logs, watchtowers) |
+| `@miradex/client/verification/{thorchain,chainflip,near-intents}` | Per-provider verifier | Light-touch integration |
+| `@miradex/client/lib/bitcoin/tx-verify` | TxCancel independent verifier | Refund tools |
+| `@miradex/client/lib/monero/verify-lock` | XMR lock independent verifier | Auditing, watchtowers |
+
+### `PlatformAdapter`
+
+The engine is decoupled from platform I/O via a `PlatformAdapter`
+interface ([`src/engine/platform.ts`](./src/engine/platform.ts)).
+You implement it once for your environment; the engine consumes it.
+
+Required methods:
+
+- `watchDeposit(address, network, signal, onStatus?)` /
+  `checkDeposit(address, network)` / `fetchUtxo(address, network)` —
+  Bitcoin deposit detection.
+- `saveKeystore(keystore, label)` / `loadKeystore(id)` /
+  `listKeystores()` / `deleteKeystore(id)` — keystore persistence.
+- `estimateFee(network)` — fee-rate query.
+- `broadcastTx(rawHex, network)` — Bitcoin broadcast.
+- `createBlockchainQuerier(network)` /
+  `createBlockchainProvider(network)` — Electrum-equivalent on Node,
+  mempool.space-equivalent in browsers.
+- `generateQr(text)` — QR rendering for deposit addresses.
+- `logger: Logger` — structured logger.
+
+Optional methods (recovery + cache):
+
+- `saveSwapProtocol(swapId, params)` / `loadSwapProtocol(swapId)` —
+  write-through cache of public per-swap params.
+- `saveProtocolSnapshot(swapId, json)` /
+  `loadProtocolSnapshot(swapId)` — one-shot recovery snapshot
+  written between `/presigs` and `/fund`.
+
+Reference implementations:
+
+- **Browser:** the miradex-web adapter
+  ([`miradex-web/lib/miradex-web/browser-adapter.ts`](https://github.com/miradexio/miradex-web/blob/main/lib/miradex-web/browser-adapter.ts))
+  — uses `idb` for IndexedDB, mempool.space + electrs CORS endpoints
+  for Bitcoin queries, `qrcode.react` for QR, browser file download
+  for keystore export.
+- **Node / Electron:** — SQLite + Electrum + filesystem keystore.
+
+### Direct entry points
+
+If you do not want the engine, drive flows directly:
+
+```ts
+import { runAtomicSwap, SwapExecutor } from '@miradex/client';
+
+// Atomic swap, low-level:
+await runAtomicSwap({
+  api: apiClient,
+  params: { amount: '0.01', destAddress: '8...', refundAddress: 'bc1q...', network: 'mainnet' },
+  callbacks: { onProgress, onDepositRequired, saveKeystore, loadKeystore },
+  signal: abortController.signal,
+});
+
+// Routed swap, low-level:
+const executor = new SwapExecutor(apiClient);
+const result = await executor.executeSwap({
+  from: 'BTC', to: 'ETH', amount: '0.01',
+  destAddress: '0x...', refundAddress: 'bc1q...',
+  provider: 'thorchain',
+});
+```
+
+Cancellation: pass an `AbortController.signal` and call `.abort()`.
+The flow throws `SwapCancelledError`. The keystore (and any partial
+on-chain progress) survives.
+
+### Events
+
+`MiradexEngine extends EventEmitter`; useful events are:
+
+- `state` — fires whenever the engine's `EngineState` changes.
+- `flow:progress` — fires when an active flow's pipeline phase
+  changes.
+- `flow:complete` / `flow:error` — terminal-state notifications.
+
+See [`src/engine/miradex-engine.ts`](./src/engine/miradex-engine.ts).
+
+---
+
+## Security model
+
+The SDK does not trust the server beyond reachability and HTTPS message
+integrity: every state claim is verified against an independent
+source — Electrum quorum for Bitcoin, monerod RPC quorum for Monero,
+THORNode + Midgard for THORChain, the Chainflip broker for
+Chainflip, the 1Click backend for NEAR Intents. The full
+attack-by-attack analysis for the BTC↔XMR atomic swap is in
+[`ATOMIC-SWAP-PAPER.md`](./ATOMIC-SWAP-PAPER.md).
+
+---
+
+## Configuration
+
+### `EngineConfig`
+
+The first argument to `new MiradexEngine`:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `apiUrl` | `string` | required | Base URL of the server |
+| `network` | `'mainnet' \| 'testnet' \| 'regtest'` | `'mainnet'` | |
+| `slippageBps` | `number` | `100` (1.00%) | Bounded `[10, 500]` on mainnet/testnet, `[10, 10000]` on regtest. Out-of-range throws `E_SLIPPAGE_OUT_OF_RANGE` |
+| `apiTimeout` | `number` | `60_000` ms | Per-request timeout |
+| `apiMaxRetries` | `number` | `3` | Bounded retry count |
+| `monerodNodes` | `readonly string[]` | network default | Quorum verifier requires ≥ 2 of N to agree |
+| `fetchFn` | `typeof fetch` | `globalThis.fetch` | Override for Tor-proxied fetch |
+
+Sources of network defaults:
+
+- Bitcoin Electrum servers in
+  [`src/lib/default-config.ts`](./src/lib/default-config.ts) (use
+  `ELECTRUM_SERVERS` / `electrumUrlForNetwork`).
+- Monero RPC nodes — `MONERO_MAINNET_NODES` / `MONERO_STAGENET_NODES`
+  re-exported from `@miradex/client`.
+
+---
+
+## Errors
+
+Every verification and protocol error carries a stable `code` string.
+Handle them by code, not by message text — the messages may change
+between releases. Codes are exported from `@miradex/client` as
+`ERROR_CODES`.
+
+```ts
+import { VerificationError, ProtocolError } from '@miradex/client';
+
+try {
+  await engine.startAtomicSwap(params);
+} catch (err) {
+  if (err instanceof VerificationError && err.code === 'E_LOCK_ADDR_MISMATCH') {
+    // Server tried to make us fund an attacker-controlled address.
+  }
+}
+```
+
+Selected codes (full list in the technical paper appendix):
+
+| Code | Cause |
+| --- | --- |
+| `E_LOCK_ADDR_MISMATCH` | Locally-derived P2WSH ≠ server's claim — refusing to fund |
+| `E_DLEQ_PROOF_INVALID` | Alice's DLEQ proof failed verification |
+| `E_DLEQ_PROOF_REQUIRED` | Alice provided keys without a DLEQ proof |
+| `E_REDEEM_DIGEST_MISMATCH` | Locally-recomputed redeem digest ≠ server's claim — refusing encsig |
+| `E_XMR_LOCK_FAILED` | XMR lock did not verify against quorum |
+| `E_S_A_MISMATCH` | `s_a` returned by server does not satisfy `s_a · G == S_a_monero` |
+| `E_S_A_MONERO_MISSING` | `S_a_monero` absent — refusing to release encsig |
+| `E_TIMELOCK_OUT_OF_RANGE` | A BIP68 sequence was outside accepted range |
+| `E_FEE_BELOW_RELAY` / `E_FEE_ABOVE_CAP` | Fee outside policy band |
+| `E_AMNESTY_EXCEEDS_CAP` | Amnesty amount exceeded the configured ratio of lock |
+| `E_SNAPSHOT_WRITE_FAILED` | Refusing to broadcast TxLock without persisting recovery snapshot first |
+| `E_PRESIGS_WEDGED` | Server repeatedly rejected `/presigs` — swap is wedged, fail to surface restart UI |
+| `E_THORCHAIN_VAULT_MISMATCH` | Deposit address not in active THORChain vaults |
+| `E_CHAINFLIP_CHANNEL_MISBINDING` | Chainflip channel binding does not match user's expected destination |
+| `E_NEAR_INTENT_NOT_REGISTERED` | Deposit address unknown to 1Click (HTTP 404) |
+| `E_NEAR_INTENT_FAILED` | 1Click reports `FAILED` |
+| `E_RATE_DRIFT` | Engine's expected output drifted from the accepted quote beyond `slippageBps` |
+| `E_SLIPPAGE_OUT_OF_RANGE` | `slippageBps` outside the network's allowed band |
+
+---
+
+## Build
+
+### Building from source
+
+```bash
+pnpm install
+pnpm -F @miradex/client build       # tsc → dist/
+pnpm -F @miradex/client typecheck
+pnpm -F @miradex/client test
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/address/base58.d.ts

@@ -0,0 +1,9 @@
+export declare function validateBase58Check(address: string, expectedVersions: readonly number[]): {
+    valid: boolean;
+    reason?: string;
+};
+export declare function validateXrpAddress(address: string): {
+    valid: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=base58.d.ts.map

package/dist/address/base58.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base58.d.ts","sourceRoot":"","sources":["../../src/address/base58.ts"],"names":[],"mappings":"AAKA,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAcrC;AAKD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAavF"}

package/dist/address/base58.js

@@ -0,0 +1,33 @@
+import { base58check as b58c } from '@scure/base';
+import { sha256 } from '@noble/hashes/sha2.js';
+const bs58check = b58c(sha256);
+export function validateBase58Check(address, expectedVersions) {
+    try {
+        const decoded = bs58check.decode(address);
+        if (decoded.length < 2)
+            return { valid: false, reason: 'Too short' };
+        const version = decoded[0];
+        if (!expectedVersions.includes(version)) {
+            return { valid: false, reason: `Invalid version byte: 0x${version.toString(16)}` };
+        }
+        return { valid: true };
+    }
+    catch {
+        return { valid: false, reason: 'Invalid base58check encoding' };
+    }
+}
+// XRP uses a different base58 alphabet
+const XRP_ALPHABET = 'rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz';
+export function validateXrpAddress(address) {
+    if (!address.startsWith('r') || address.length < 25 || address.length > 35) {
+        return { valid: false, reason: 'XRP address must start with r and be 25-35 chars' };
+    }
+    // Validate characters are in XRP alphabet
+    for (const c of address) {
+        if (!XRP_ALPHABET.includes(c)) {
+            return { valid: false, reason: `Invalid character '${c}' in XRP address` };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=base58.js.map

package/dist/address/base58.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base58.js","sourceRoot":"","sources":["../../src/address/base58.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;AAE/B,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,gBAAmC;IAEnC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAErE,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;QAC5B,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACrF,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;IAClE,CAAC;AACH,CAAC;AAED,uCAAuC;AACvC,MAAM,YAAY,GAAG,4DAA4D,CAAC;AAElF,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAC3E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,kDAAkD,EAAE,CAAC;IACtF,CAAC;IAED,0CAA0C;IAC1C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,CAAC,kBAAkB,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/address/bech32.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validate a bech32/bech32m address.
+ *
+ * For segwit addresses (BTC bc1, LTC ltc1), the first word is the witness
+ * version and is skipped before fromWords conversion.
+ *
+ * For non-segwit bech32 (Cosmos, THORChain), all words are data.
+ */
+export declare function validateBech32(address: string, expectedHrp: string, minDataLen?: number, maxDataLen?: number): {
+    valid: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=bech32.d.ts.map

package/dist/address/bech32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bech32.d.ts","sourceRoot":"","sources":["../../src/address/bech32.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,UAAU,SAAK,EACf,UAAU,SAAK,GACd;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAiCrC"}

package/dist/address/bech32.js

@@ -0,0 +1,41 @@
+import { bech32, bech32m } from '@scure/base';
+/**
+ * Validate a bech32/bech32m address.
+ *
+ * For segwit addresses (BTC bc1, LTC ltc1), the first word is the witness
+ * version and is skipped before fromWords conversion.
+ *
+ * For non-segwit bech32 (Cosmos, THORChain), all words are data.
+ */
+export function validateBech32(address, expectedHrp, minDataLen = 20, maxDataLen = 40) {
+    try {
+        let decoded;
+        try {
+            decoded = bech32m.decode(address);
+        }
+        catch {
+            decoded = bech32.decode(address);
+        }
+        if (decoded.prefix !== expectedHrp) {
+            return { valid: false, reason: `Expected HRP '${expectedHrp}', got '${decoded.prefix}'` };
+        }
+        // Segwit addresses (bc, ltc) have a witness version as the first word
+        const isSegwit = expectedHrp === 'bc' ||
+            expectedHrp === 'ltc' ||
+            expectedHrp === 'tb' ||
+            expectedHrp === 'tltc';
+        const words = isSegwit ? decoded.words.slice(1) : decoded.words;
+        const data = bech32.fromWords(words);
+        if (data.length < minDataLen || data.length > maxDataLen) {
+            return {
+                valid: false,
+                reason: `Data length ${data.length} out of range [${minDataLen}, ${maxDataLen}]`,
+            };
+        }
+        return { valid: true };
+    }
+    catch {
+        return { valid: false, reason: 'Invalid bech32 encoding' };
+    }
+}
+//# sourceMappingURL=bech32.js.map

package/dist/address/bech32.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bech32.js","sourceRoot":"","sources":["../../src/address/bech32.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,WAAmB,EACnB,UAAU,GAAG,EAAE,EACf,UAAU,GAAG,EAAE;IAEf,IAAI,CAAC;QACH,IAAI,OAA4C,CAAC;QACjD,IAAI,CAAC;YACH,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,OAAgC,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,OAAgC,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACnC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,WAAW,WAAW,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC;QAC5F,CAAC;QAED,sEAAsE;QACtE,MAAM,QAAQ,GACZ,WAAW,KAAK,IAAI;YACpB,WAAW,KAAK,KAAK;YACrB,WAAW,KAAK,IAAI;YACpB,WAAW,KAAK,MAAM,CAAC;QACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;QAEhE,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,MAAM,GAAG,UAAU,IAAI,IAAI,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;YACzD,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,eAAe,IAAI,CAAC,MAAM,kBAAkB,UAAU,KAAK,UAAU,GAAG;aACjF,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/address/evm.d.ts

@@ -0,0 +1,5 @@
+export declare function validateEvmAddress(address: string): {
+    valid: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=evm.d.ts.map

package/dist/address/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../src/address/evm.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BvF"}

package/dist/address/evm.js

@@ -0,0 +1,27 @@
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { bytesToHex } from '../lib/crypto/scalars.js';
+export function validateEvmAddress(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        return { valid: false, reason: 'Must be 0x followed by 40 hex characters' };
+    }
+    // If address is all-lowercase or all-uppercase, skip checksum (valid but unchecksummed)
+    const hex = address.slice(2);
+    if (hex === hex.toLowerCase() || hex === hex.toUpperCase()) {
+        return { valid: true };
+    }
+    // EIP-55 mixed-case checksum validation
+    const hashHex = bytesToHex(keccak_256(new TextEncoder().encode(hex.toLowerCase())));
+    for (let i = 0; i < 40; i++) {
+        const c = hex.charAt(i);
+        const h = parseInt(hashHex.charAt(i), 16);
+        if (/[a-fA-F]/.test(c)) {
+            const shouldBeUpper = h >= 8;
+            const isUpper = c === c.toUpperCase();
+            if (shouldBeUpper !== isUpper) {
+                return { valid: false, reason: 'Invalid EIP-55 checksum' };
+            }
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=evm.js.map

package/dist/address/evm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.js","sourceRoot":"","sources":["../../src/address/evm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAEtD,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;IAC9E,CAAC;IAED,wFAAwF;IACxF,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,GAAG,CAAC,WAAW,EAAE,IAAI,GAAG,KAAK,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,wCAAwC;IACxC,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAE1C,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACtC,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;gBAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/address/index.d.ts

@@ -0,0 +1,15 @@
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+/**
+ * Validate a cryptocurrency address for a given token or chain.
+ * Pure function — works identically in Node.js and browser.
+ */
+export declare function validateAddress(address: string, tokenOrChain: string): ValidationResult;
+export declare function resolveChain(tokenOrChain: string): string;
+export declare function getSupportedChains(): readonly string[];
+/** Tokens commonly received on a given chain. Used to populate the
+ *  Tokens column in the address book without per-row tagging. */
+export declare function tokensForChain(chain: string): readonly string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/address/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/address/index.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoGD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAYvF;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,kBAAkB,IAAI,SAAS,MAAM,EAAE,CAEtD;AAcD;iEACiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE/D"}