crypto-aio 0.0.3 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-21
+
+crypto-aio 0.2.0 settles everything 1.0 will promise: the API is locked by reports in CI,
+the driver port is final, stored Operations carry a record format, and the gaps that could
+make a paid transfer look failed are closed. Entries marked **Breaking** need a change from
+some users; [Upgrade to 1.0](https://vhidvz.github.io/crypto-aio/reference/upgrading.html)
+says what to do for each.
+
+### Added
+
+- `SECURITY.md`: how to report a vulnerability privately, and what is in scope.
+- Operation records carry `format` (`OPERATION_FORMAT`, 1), the record format they were
+  stored in; a record without one (0.1.0) reads as format 1. A process never reads a record
+  of a newer format: the read throws the new `RECORD_FORMAT_UNSUPPORTED`, and a worker
+  releases its claim for a newer process. The `OperationStore` contract suite checks that
+  a store keeps `format`, and tests pin the intent hash and the store keys as 0.1.0 wrote
+  them.
+- API reports (`etc/api/*.api.md`, one per entry point), generated by API Extractor: CI fails
+  when the public API changes without its report (`pnpm api:update`).
+- Release tooling: a tag such as `1.0.0-rc.1` publishes under npm's `next` dist-tag, a
+  release tag must match `package.json` and have a `CHANGELOG.md` section, which becomes the
+  GitHub Release's notes, and a release runs every CI check before it publishes.
+- CI runs on Node.js 22.12.0, 22, 24 and 26, audits the runtime dependencies, and checks the
+  package's exports and types with `publint` and `@arethetypeswrong/cli`
+  (`pnpm lint:package`). CodeQL and Dependabot are configured.
+
+### Changed
+
+- **Breaking:** crypto-aio needs Node.js 22.12 or later (`engines.node` is `>=22.12`), the
+  version every family already needed for Solana. `engines` no longer names an npm version,
+  so npm 11 installs without an engine warning.
+- `package.json` declares `"type": "commonjs"`.
+- **Breaking:** a transfer whose transaction executed but shows no transfer to the
+  recipient fails with the new `TX_UNEVIDENCED`, not `TX_REVERTED`: an EVM or Tron token
+  that logged no `Transfer` to the recipient, or TON jettons sent to a wallet the master
+  does not name. Value may have moved, so check the chain before paying again; a
+  `TX_REVERTED` now always means the execution failed. Drivers say which with
+  `failure: 'reverted' | 'unevidenced'` (`TxFailure`) on `observe` and `includedFinal`, and
+  the core keeps it on the Attempt's observation (`failure`, a field stores must keep).
+- **Breaking:** an endpoint reads `healthy` in `status()` and `getNetworkStatus()` only
+  once its height is known, when its family probes heights: before that it is `unknown`,
+  where a confirmed identity alone used to make it `healthy`.
+- **Breaking:** a proof needs `proofQuorum` endpoints even after some drop out of its count
+  (down for three health intervals): the quorum is capped by the endpoints configured, not
+  by those still counted, so the one endpoint left never proves alone; proofs wait for the
+  others instead. The new `transport.degradedProofs: true` restores the old behavior, which
+  favours liveness.
+- `lifecycle.leaseWaitMs` (default: `leaseMs`): how long a transfer waits for its wallet's
+  address lease before `SEQUENCE_BUSY`, so transfers can queue behind a slow signer.
+- Fuzz tests feed every decoder of untrusted bytes (Solana messages and transactions, Tron
+  protobuf, Bitcoin and EVM raw transactions, Avalanche transactions, cb58, exact-integer
+  JSON) random and mutated input; they may refuse it, never throw an unclassified error.
+  A nightly workflow runs them deeper, runs the live read-only integration suites, and
+  runs the unit suites on the newest release of every SDK.
+- The pack check compiles a project that imports every entry point with TypeScript 5.3 (the
+  oldest supported, with `skipLibCheck`), the tested 5.9 and 7, under `nodenext` and
+  `bundler` resolution.
+- `@solana/web3.js` 3 is supported next to 1.99 (peer range `^1.99.0 || ^3.0.0`). The
+  Solana driver now compiles its messages and derives token account addresses itself
+  (checked byte for byte against the SDK), so signed bytes no longer depend on the SDK
+  version; the SDK only backs `native()`. The pack check loads the family with 3.x too.
+- `BuildContext.decimals`: the decimals the core scaled a transfer's amounts with. The
+  Solana driver refuses a token transfer whose mint has other decimals
+  (`ASSET_RESOLUTION`), which a wrong registration would otherwise sign as a mis-scaled
+  `transferChecked`.
+- `ReplacementPolicy.comparePrice` (optional): the EVM family ranks earlier cancels by
+  price, so a repeat cancel climbs from the highest one without an explicit `fee`.
+- `assets` on the root container's options registers tokens (decimals, symbol, aliases)
+  without writing a plugin.
+- `PROVIDER_MISCONFIGURED` for refused credentials carries `details.httpStatus` (401 or 403).
+- Solana: the signature fee is computed (5,000 lamports per signature), and an endpoint's
+  `getFeeForMessage` quote must match the message's fee exactly; any other quote fails the
+  estimate with a retryable `PROVIDER_UNAVAILABLE`, so one endpoint can neither inflate an
+  estimate (refusing a payable transfer) nor deflate it. Whether an explicit fee fits in
+  u64 is decided locally.
+- **Breaking:** Bitcoin: a wallet whose signer does not declare the scheme its address type
+  signs with (a `p2tr` wallet on an ECDSA-only signer, such as a KMS key) is refused with
+  `CONFIG_INVALID` when the wallet resolves (`ready()`, `walletAddress()`, `transfer()`,
+  `prepareTransfer()`), before anything is built or reserved, instead of failing at
+  signing. A Schnorr-only signer on a non-`p2tr` wallet gets the same error, where it got
+  `INVALID_ADDRESS`. Watch-only wallets are unaffected. Drivers declare this with the
+  optional `ChainDriver.signingSchemes(wallet)`.
+- **Breaking:** EVM and Tron: a token whose contract answers `deprecated()` with `true`
+  (Tether's `TetherToken`, USDT on Ethereum and Tron) is refused before signing with
+  `ASSET_RESOLUTION`, rather than sent through a contract that forwards it and logs no
+  `Transfer`. Every token estimate makes one more read.
+- **Breaking:** EVM: the `maxGasLimit` option (`chains.<id>.options`, a handle's `options`,
+  or a network's `params.maxGasLimit`) bounds the gas limit of every transfer, replacement
+  and cancel, by default 2^24 (`DEFAULT_MAX_GAS_LIMIT`, Ethereum's EIP-7825 cap). An
+  estimate (with its headroom) or an override above it fails with `INVALID_INTENT` before
+  signing (`details.required`, `details.maxGasLimit`).
+- EVM: on OP Stack chains since Isthmus, the operator fee (`GasPriceOracle.getOperatorFee`
+  for the gas limit) is its own `operator` charge and `details.operatorFee`, counted in
+  `details.expected` and the funds check.
+- **Breaking:** the Bitcoin scanner reads each block's own bytes (`/block/:hash/raw`) and
+  delivers only transactions its header commits to: the merkle root (refusing the
+  CVE-2012-2459 duplicate), a coinbase first, and the BIP141 witness commitment; the header
+  read at the height must match those bytes. A scanned transaction's `from`, input values and
+  fee come from the previous transactions' bytes, checked against the txids its inputs name.
+  A block that does not match is a retryable `PROVIDER_INCONSISTENT` and decides nothing. A
+  filtered scan uses the indexer's JSON pages only to find spends from watched addresses,
+  checked against the bytes; an unfiltered one reads one previous transaction per distinct
+  parent outside the block, so scan with `filter.addresses`. `details.vout[].type` is named
+  from the script, as Blockstream electrs names it.
+- The transport's `http` reads a binary answer with `responseType: 'bytes'`, within
+  `maxResponseBytes`.
+- A reference PostgreSQL implementation of the four store ports, in
+  `examples/postgres-store` (schema, source, README; not part of the package), passes every
+  store contract suite and an engine crash-and-recover run against PostgreSQL 16 in CI.
+- `pnpm test:evm-local` proves the EVM write path on a local anvil node, with ethers and
+  web3: proven finality, idempotent repeats, concurrent nonces, an ERC-20, replace, cancel,
+  crash recovery, funds checks and a reorg. CI runs it on every change.
+- **Breaking:** an idempotency key and a scanner's `cursorKey` must be well-formed text
+  without U+0000 (`INVALID_INTENT`, `CONFIG_INVALID`): a database may refuse U+0000, and a
+  driver may turn a lone surrogate into U+FFFD, so two keys would become one.
+- The store ports say which clock stamps times (the container's, or a wall clock the
+  processes share), and that a store may refuse an attempt id another Operation holds; the
+  contract suite no longer reuses one. `createFakeEnv` takes a `clock`, so stores built
+  beforehand can share it, and `FaultyOperationStore` passes `purge` through. The memory
+  store lists and purges nothing for a negative `limit`, as for 0.
+- `RecoveryReport.unresent`: a `signed` or ambiguous Operation whose wallet no longer
+  resolves is now checked on chain and counted `unresent`, where it was counted `failed`
+  without its check.
+- **Breaking (types only):** `Blockchain`'s constructor is private (handles come from
+  `aio.blockchain()` or `Blockchain.create()`), and its internal `protected` methods are gone
+  from the type declarations. `CryptoAio`'s constructor has one signature, `(options?)`.
+
+### Deprecated
+
+- `library: 'web3'` (and `Library.WEB3`): web3.js is no longer maintained upstream (4.16.0 is
+  its last release). It keeps working through 1.x, warns once per process with a
+  `DeprecationWarning` (code `CRYPTO_AIO_WEB3`), and is removed in 2.0. Use `ethers`.
+
+### Fixed
+
+- `evmChainPlugin` registers each `assets` ERC-20 under its EIP-55 checksummed contract,
+  whatever case it is given in, so a token's alias, its ref, its transfers and its balances
+  share one asset id (a lower-case contract made two assets, and deposits missed the
+  alias's). A token of another standard, a malformed contract, or a mixed-case contract with
+  a wrong checksum is refused with `CONFIG_INVALID` at registration.
+- `stringifyTagged` encodes a Node.js `Buffer` as bytes, as the memory store keeps it; it was
+  written as `{ type: 'Buffer', data }` and read back as a plain object by a durable store.
+- TON: `transfer bounced` and `jetton transfer bounced` no longer rest on the indexer's
+  word. The provider's raw records of the wallet transaction and of each delivery, checked
+  against their hashes and linked by message hash, must show the bounce; until they do, or
+  while the provider's endpoints disagree, the transfer stays undecided (a warning with code
+  `BOUNCE_UNPROVEN` when they contradict the indexer). A lone lying indexer can delay a
+  verdict, never fail a transfer that landed.
+
+## [0.1.0] - 2026-10-01
+
+### Added
+
+- initial release 🎉​🎊​.
+
+[Unreleased]: https://github.com/vhidvz/crypto-aio/compare/0.2.0...HEAD
+[0.2.0]: https://github.com/vhidvz/crypto-aio/compare/0.1.0...0.2.0
+[0.1.0]: https://github.com/vhidvz/crypto-aio/releases/tag/0.1.0

package/README.md

@@ -1,25 +1,175 @@
-# Crypto-AIO
+<h1 align="center">
+  <a href="https://vhidvz.github.io/crypto-aio/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vhidvz/crypto-aio/main/docs/public/crypto-aio-logo-dark.svg">
+      <img alt="crypto-aio" src="https://raw.githubusercontent.com/vhidvz/crypto-aio/main/docs/public/crypto-aio-logo.svg" width="420">
+    </picture>
+  </a>
+</h1>
 
-All-In-One Crypto-Currency for Backend
+<div align="center">
 
-[![Build, Test and Publish](https://github.com/vhidvz/crypto-aio/actions/workflows/npm-ci.yml/badge.svg)](https://github.com/vhidvz/crypto-aio/actions/workflows/npm-ci.yml)
 [![npm](https://img.shields.io/npm/v/crypto-aio)](https://www.npmjs.com/package/crypto-aio)
+[![CI](https://github.com/vhidvz/crypto-aio/actions/workflows/ci.yml/badge.svg)](https://github.com/vhidvz/crypto-aio/actions/workflows/ci.yml)
 ![npm](https://img.shields.io/npm/dm/crypto-aio)
-[![Coverage](https://raw.githubusercontent.com/vhidvz/crypto-aio/main/docs/coverage.svg)](https://htmlpreview.github.io/?https://github.com/vhidvz/crypto-aio/blob/main/docs/coverage/lcov-report/index.html)
-[![GitHub](https://img.shields.io/github/license/vhidvz/crypto-aio?style=flat)](https://github.com/vhidvz/crypto-aio/blob/master/LICENSE)
-[![documentation](https://img.shields.io/badge/documentation-click_to_read-c27cf4)](https://vhidvz.github.io/crypto-aio/)
+[![Coverage](https://raw.githubusercontent.com/vhidvz/crypto-aio/main/coverage-badge.svg)](https://htmlpreview.github.io/?https://github.com/vhidvz/crypto-aio/blob/main/coverage/lcov-report/index.html)
+[![License](https://img.shields.io/github/license/vhidvz/crypto-aio?style=flat)](LICENSE)
+[![documentation](https://img.shields.io/badge/documentation-read_the_docs-5b5fef)](https://vhidvz.github.io/crypto-aio/)
 
-## Quick Start
+**One TypeScript API for moving money on blockchains.** Balances, transfers, confirmations
+and deposit scanning across EVM chains, Bitcoin, Tron, Solana, TON and the Avalanche X-Chain and
+P-Chain, built for exchanges, wallets and payment systems.
 
+[Documentation](https://vhidvz.github.io/crypto-aio/) ·
+[Quick start](https://vhidvz.github.io/crypto-aio/start/quick-start.html) ·
+[Learn from zero](https://vhidvz.github.io/crypto-aio/learn/) ·
+[Examples](https://vhidvz.github.io/crypto-aio/build/examples.html) ·
+[API](https://vhidvz.github.io/crypto-aio/reference/api.html)
+
+</div>
+
+## Why crypto-aio
+
+Every chain has an SDK that can build, sign and send a transaction. None of them is a payment
+system. The hard part of moving money is everything around the transaction: a reply that never
+arrives, a process that dies between signing and sending, two servers sending from one wallet, a
+node that says "final" about a block that is later replaced. crypto-aio is the layer that handles
+those cases, written once, with the same API on every chain:
+
+- **Pay exactly once.** Every transfer carries your own idempotency key. Repeat the call after a
+  timeout, a crash or a lost reply, and you get the same payment back, never a second one.
+- **Crash-safe.** A signed transaction is stored before it is sent. After a restart, the library
+  sends those exact bytes again; recovery never signs.
+- **Final means proven.** A transfer is final only on finalized chain data that a quorum of
+  independent endpoints agree on, never on one node's word.
+- **Deposits that survive reorgs.** Durable scanners deliver every block at least once, and roll
+  back when the chain reorganizes.
+- **Keys stay with signers.** In memory, or behind your HSM, KMS or MPC custody, with a policy
+  hook before every signature. Logs, errors and events never carry a secret.
+- **One shape, explicit differences.** What a chain cannot do is a named capability, not a silent
+  difference.
+
+**Who it is for:** backend developers building exchanges, custodial wallets, payment processors
+and treasury systems on Node.js. New to crypto? The documentation teaches everything from first
+principles, starting with [what a ledger is](https://vhidvz.github.io/crypto-aio/learn/foundations/ledgers.html).
+
+## Supported networks
+
+| Family | Chains | Through |
+| --- | --- | --- |
+| EVM | Ethereum, BNB Smart Chain, Polygon, Avalanche C-Chain, Arbitrum, Optimism, Base, and any EVM chain you add | `ethers` 6 (or the deprecated `web3` 4) |
+| Bitcoin | mainnet, testnet, testnet4, signet, regtest | `bitcoinjs-lib` 7 and an Esplora indexer |
+| Tron | mainnet, Shasta, Nile | `tronweb` 6 |
+| Solana | mainnet, devnet, testnet | `@solana/web3.js` 1 or 3 |
+| TON | mainnet, testnet | `@ton/ton` 16 and toncenter |
+| Avalanche X-Chain and P-Chain | mainnet, Fuji | `@avalabs/avalanchejs` 5 and the Avalanche Data API |
+
+What each network supports, family by family, is in
+[Networks](https://vhidvz.github.io/crypto-aio/reference/networks/).
+
+## Install
+
+crypto-aio needs Node.js 22.12 or later. Install the package, and only the
+SDK of each family you use:
+
+```sh
+npm install crypto-aio ethers           # EVM chains
+npm install crypto-aio bitcoinjs-lib    # Bitcoin
+npm install crypto-aio tronweb          # Tron
+npm install crypto-aio @solana/web3.js  # Solana
+npm install crypto-aio @ton/ton @ton/core @ton/crypto  # TON
+npm install crypto-aio @avalabs/avalanchejs  # Avalanche X-Chain and P-Chain
+```
+
+A handle whose SDK is missing fails with `DEPENDENCY_MISSING` and names the install command.
+The type declarations need TypeScript 5.3 or later, and each family's entry point
+(`crypto-aio/evm`, …) the types of its SDK; some SDKs' own declarations need TypeScript 5.7
+unless `skipLibCheck` is on. TypeScript 7 is supported.
+
+## Your first transfer, with no network and no keys
+
+`crypto-aio/testing` ships an in-memory chain, so you can see the whole flow before you configure
+anything:
+
+<!-- runnable -->
 ```ts
-import { CryptoAio } from 'crypto-aio';
+import { createFakeEnv } from 'crypto-aio/testing';
+
+const env = await createFakeEnv(); // an in-memory chain, a funded wallet, and a handle
+const sub = await env.run(
+  env.bc.transfer({ to: env.stranger(), amount: '0.001' }, { idempotencyKey: 'order-42' }),
+);
+env.chain.mine(4); // the fake chain makes blocks when you ask
+const { status } = await env.run(sub.wait({ finality: 'final' }));
+console.log(status.state, status.evidence); // final proven
+```
+
+The [Quick start](https://vhidvz.github.io/crypto-aio/start/quick-start.html) explains each line.
 
-const caio = new CryptoAio();
+## On a real network
 
-caio.eth.getGasPrice();
+```ts
+import { Blockchain, configure, localSigner, secret } from 'crypto-aio';
+
+configure({
+  providers: {
+    alchemy: { preset: 'alchemy', apiKey: secret(process.env.ALCHEMY_KEY ?? '') },
+    infura: { preset: 'infura', apiKey: secret(process.env.INFURA_KEY ?? '') },
+  },
+  signers: { hot: localSigner({ id: 'hot', secp256k1: secret(process.env.HOT_KEY ?? '') }) },
+  wallets: { treasury: { signer: 'hot' } },
+  chains: { ethereum: { network: 'sepolia', provider: ['alchemy', 'infura'], wallet: 'treasury' } },
+  lifecycle: { requireIdempotencyKey: true },
+});
 
-caio.eth.createAccount();
-caio.eth.account.create();
+const eth = Blockchain.create({ chain: 'ethereum' });
+const me = await eth.walletAddress();
+console.log((await eth.getBalance(me.canonical)).amount.format()); // e.g. '0.5 ETH'
 
-caio.eth.account.getBalance();
+const sub = await eth.transfer(
+  { to: '0x3535353535353535353535353535353535353535', amount: '0.01' },
+  { idempotencyKey: 'withdrawal-42' }, // your own id: repeating the call never pays twice
+);
+const { status } = await sub.wait({ finality: 'final' });
+console.log(status.state, status.evidence); // 'final' 'proven'
 ```
+
+The same calls work on every chain above. [Connect to a real
+network](https://vhidvz.github.io/crypto-aio/build/connect.html) has the configuration for each
+family.
+
+## Where to go next
+
+| If you… | Start here |
+| --- | --- |
+| Are new to cryptocurrency or blockchains | The [learning path](https://vhidvz.github.io/crypto-aio/learn/): money, keys, transactions and finality, then the engineering of safe payments, then a tour of crypto-aio |
+| Know blockchains and want the model fast | [crypto-aio in 10 minutes](https://vhidvz.github.io/crypto-aio/start/mental-model.html), then the [hands-on tutorial](https://vhidvz.github.io/crypto-aio/start/tutorial.html) |
+| Want to build now | [Examples](https://vhidvz.github.io/crypto-aio/build/examples.html) and the [Build guides](https://vhidvz.github.io/crypto-aio/build/) |
+| Need an exact answer | [API](https://vhidvz.github.io/crypto-aio/reference/api.html), [Configuration](https://vhidvz.github.io/crypto-aio/reference/configuration.html), [Errors](https://vhidvz.github.io/crypto-aio/reference/errors.html) |
+| Are going to production | [Production architecture](https://vhidvz.github.io/crypto-aio/tour/production.html) and the [checklist](https://vhidvz.github.io/crypto-aio/build/production.html) |
+| Want to add a chain or a store | [Explore](https://vhidvz.github.io/crypto-aio/explore/): plugins, stores and the source map |
+
+## Status
+
+crypto-aio is at **0.2.0**, on its way to 1.0, from which [semantic
+versioning](https://vhidvz.github.io/crypto-aio/reference/stability.html) covers the whole API,
+the driver port and what a process stores; the 0.0.x releases on npm are an older, unrelated
+API. [Known limitations](https://vhidvz.github.io/crypto-aio/reference/limitations.html) lists
+what it does not do yet, and [Upgrade to 1.0](https://vhidvz.github.io/crypto-aio/reference/upgrading.html)
+what changes from 0.1.0. Only in-memory stores ship: production needs durable stores of your
+own, proven with the contract suites in `crypto-aio/testing`; [examples/postgres-store](examples/postgres-store)
+is a reference implementation on PostgreSQL. Release notes are in the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Issues and pull requests are welcome. `pnpm install` and `pnpm check` (lint, typecheck and tests)
+are all a change needs locally, plus `pnpm api:update` when it changes the public API (CI
+compares the API with the reports in `etc/api/`). `pnpm test:evm-local` also signs, broadcasts
+and proves real EVM transactions on a local anvil node, which it starts and stops; CI runs it
+on every change. The [source map](https://vhidvz.github.io/crypto-aio/explore/source-map.html)
+explains the repository, and [docs/README.md](docs/README.md) how the documentation is built and
+tested.
+
+## License
+
+[MIT](LICENSE)

package/dist/adapters/avalanche/address.d.ts

@@ -0,0 +1,15 @@
+import type { NormalizedAddress } from '../../core/model/address';
+import type { AvalancheNetworkConfig } from './network';
+export declare const ADDRESS_BYTES = 20;
+type AddressParams = Pick<AvalancheNetworkConfig, 'alias' | 'hrp'>;
+/** The 20 address bytes of a compressed secp256k1 public key. */
+export declare function addressBytesOf(publicKey: Uint8Array): Uint8Array;
+/** `X-avax1…`: the canonical form of 20 address bytes on this chain. */
+export declare function formatAddress(bytes: Uint8Array, params: AddressParams): string;
+/**
+ * The address bytes of `address`; throws `INVALID_ADDRESS` with a fixed text that never
+ * repeats the input, which may be a pasted secret.
+ */
+export declare function decodeAddress(address: string, params: AddressParams): Uint8Array;
+export declare function normalizeAddress(address: string, params: AddressParams): NormalizedAddress;
+export {};

package/dist/adapters/avalanche/address.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADDRESS_BYTES = void 0;
+exports.addressBytesOf = addressBytesOf;
+exports.formatAddress = formatAddress;
+exports.decodeAddress = decodeAddress;
+exports.normalizeAddress = normalizeAddress;
+/**
+ * X-Chain and P-Chain addresses (SDK-free). An address is 20 bytes, the RIPEMD-160 of the
+ * SHA-256 of a compressed secp256k1 public key, written in bech32 with the network's
+ * human-readable part (`avax`, `fuji`) behind the chain's alias: `X-avax1…`, `P-avax1…`.
+ * The canonical form carries the alias, lower case. A bare `avax1…` is accepted and
+ * normalized to this chain's alias; the other chain's alias (`P-` on the X-Chain), a
+ * C-Chain or another network's address, and anything that is not 20 bytes are refused: the
+ * same key's bytes on another chain are a cross-chain transfer, which a transfer never is.
+ */
+const ripemd160_1 = require("@noble/hashes/ripemd160");
+const sha256_1 = require("@noble/hashes/sha256");
+const base_1 = require("@scure/base");
+const error_1 = require("../../core/errors/error");
+exports.ADDRESS_BYTES = 20;
+/** Bech32 allows at most 90 characters; the alias and `-` add two. */
+const MAX_ADDRESS_LENGTH = 92;
+const invalid = (reason) => new error_1.ValidationError('INVALID_ADDRESS', `not an address of this chain: ${reason}`);
+/** The 20 address bytes of a compressed secp256k1 public key. */
+function addressBytesOf(publicKey) {
+    if (publicKey.length !== 33 || (publicKey[0] !== 2 && publicKey[0] !== 3)) {
+        throw new error_1.ValidationError('INVALID_ADDRESS', 'an Avalanche address needs a 33-byte compressed secp256k1 public key');
+    }
+    return (0, ripemd160_1.ripemd160)((0, sha256_1.sha256)(publicKey));
+}
+/** `X-avax1…`: the canonical form of 20 address bytes on this chain. */
+function formatAddress(bytes, params) {
+    return `${params.alias}-${base_1.bech32.encode(params.hrp, base_1.bech32.toWords(bytes))}`;
+}
+/**
+ * The address bytes of `address`; throws `INVALID_ADDRESS` with a fixed text that never
+ * repeats the input, which may be a pasted secret.
+ */
+function decodeAddress(address, params) {
+    if (typeof address !== 'string' || address.length > MAX_ADDRESS_LENGTH) {
+        throw invalid('malformed');
+    }
+    const dash = address.indexOf('-');
+    if (dash !== -1 && address.slice(0, dash) !== params.alias) {
+        throw invalid(`the chain alias is not '${params.alias}'`);
+    }
+    const body = dash === -1 ? address : address.slice(dash + 1);
+    let decoded;
+    try {
+        decoded = base_1.bech32.decode(body, 90);
+    }
+    catch {
+        throw invalid('malformed bech32');
+    }
+    if (decoded.prefix !== params.hrp) {
+        throw invalid(`the network prefix is not '${params.hrp}'`);
+    }
+    let bytes;
+    try {
+        bytes = base_1.bech32.fromWords(decoded.words);
+    }
+    catch {
+        throw invalid('malformed bech32');
+    }
+    if (bytes.length !== exports.ADDRESS_BYTES)
+        throw invalid('not 20 bytes');
+    return bytes;
+}
+function normalizeAddress(address, params) {
+    const canonical = formatAddress(decodeAddress(address, params), params);
+    return { canonical, display: canonical };
+}
+//# sourceMappingURL=address.js.map

package/dist/adapters/avalanche/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../../src/adapters/avalanche/address.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * X-Chain and P-Chain addresses (SDK-free). An address is 20 bytes, the RIPEMD-160 of the\n * SHA-256 of a compressed secp256k1 public key, written in bech32 with the network's\n * human-readable part (`avax`, `fuji`) behind the chain's alias: `X-avax1…`, `P-avax1…`.\n * The canonical form carries the alias, lower case. A bare `avax1…` is accepted and\n * normalized to this chain's alias; the other chain's alias (`P-` on the X-Chain), a\n * C-Chain or another network's address, and anything that is not 20 bytes are refused: the\n * same key's bytes on another chain are a cross-chain transfer, which a transfer never is.\n */\nimport { ripemd160 } from '@noble/hashes/ripemd160';\nimport { sha256 } from '@noble/hashes/sha256';\nimport { bech32 } from '@scure/base';\nimport { ValidationError } from '../../core/errors/error';\nimport type { NormalizedAddress } from '../../core/model/address';\nimport type { AvalancheNetworkConfig } from './network';\n\nexport const ADDRESS_BYTES = 20;\n\n/** Bech32 allows at most 90 characters; the alias and `-` add two. */\nconst MAX_ADDRESS_LENGTH = 92;\n\ntype AddressParams = Pick<AvalancheNetworkConfig, 'alias' | 'hrp'>;\n\nconst invalid = (reason: string): ValidationError =>\n  new ValidationError('INVALID_ADDRESS', `not an address of this chain: ${reason}`);\n\n/** The 20 address bytes of a compressed secp256k1 public key. */\nexport function addressBytesOf(publicKey: Uint8Array): Uint8Array {\n  if (publicKey.length !== 33 || (publicKey[0] !== 2 && publicKey[0] !== 3)) {\n    throw new ValidationError(\n      'INVALID_ADDRESS',\n      'an Avalanche address needs a 33-byte compressed secp256k1 public key',\n    );\n  }\n  return ripemd160(sha256(publicKey));\n}\n\n/** `X-avax1…`: the canonical form of 20 address bytes on this chain. */\nexport function formatAddress(bytes: Uint8Array, params: AddressParams): string {\n  return `${params.alias}-${bech32.encode(params.hrp, bech32.toWords(bytes))}`;\n}\n\n/**\n * The address bytes of `address`; throws `INVALID_ADDRESS` with a fixed text that never\n * repeats the input, which may be a pasted secret.\n */\nexport function decodeAddress(address: string, params: AddressParams): Uint8Array {\n  if (typeof address !== 'string' || address.length > MAX_ADDRESS_LENGTH) {\n    throw invalid('malformed');\n  }\n  const dash = address.indexOf('-');\n  if (dash !== -1 && address.slice(0, dash) !== params.alias) {\n    throw invalid(`the chain alias is not '${params.alias}'`);\n  }\n  const body = dash === -1 ? address : address.slice(dash + 1);\n  let decoded: { prefix: string; words: number[] };\n  try {\n    decoded = bech32.decode(body as `${string}1${string}`, 90);\n  } catch {\n    throw invalid('malformed bech32');\n  }\n  if (decoded.prefix !== params.hrp) {\n    throw invalid(`the network prefix is not '${params.hrp}'`);\n  }\n  let bytes: Uint8Array;\n  try {\n    bytes = bech32.fromWords(decoded.words);\n  } catch {\n    throw invalid('malformed bech32');\n  }\n  if (bytes.length !== ADDRESS_BYTES) throw invalid('not 20 bytes');\n  return bytes;\n}\n\nexport function normalizeAddress(\n  address: string,\n  params: AddressParams,\n): NormalizedAddress {\n  const canonical = formatAddress(decodeAddress(address, params), params);\n  return { canonical, display: canonical };\n}\n"]}

package/dist/adapters/avalanche/api.d.ts

@@ -0,0 +1,100 @@
+import { ProviderError } from '../../core/errors/error';
+import type { Transport } from '../../core/transport/types';
+import type { AvalancheCallTags, AvalancheVm } from './types';
+/** A block as the node reports it; ids are CB58. */
+export interface NodeBlock {
+    readonly id: string;
+    readonly parentId: string;
+    readonly height: bigint;
+    /** Unix seconds; absent on P-Chain blocks from before the Banff upgrade. */
+    readonly timestamp?: number;
+    /** Every transaction the block carries, decision and proposal alike. */
+    readonly txIds: readonly string[];
+}
+/** The P-Chain's view of a transaction (`platform.getTxStatus`). */
+export type PlatformStatus = 'Committed' | 'Aborted' | 'Processing' | 'Dropped' | 'Unknown';
+export interface FeeState {
+    readonly capacity: bigint;
+    readonly excess: bigint;
+    readonly price: bigint;
+    readonly timestamp: string;
+}
+/** The P-Chain's fee dimensions' weights: bandwidth, reads, writes, compute. */
+export type FeeWeights = readonly [number, number, number, number];
+/** Where the indexer says a transaction is. */
+export interface Location {
+    readonly height: bigint;
+    readonly hash: string;
+}
+export declare const malformed: (what: string) => ProviderError;
+/** A definitive JSON-RPC "not found" (`not found`, `couldn't get tx: not found`, …). */
+export declare function isNodeNotFound(error: unknown): boolean;
+/** A definitive HTTP 404 from the Data API. */
+export declare function isHttpNotFound(error: unknown): boolean;
+/** A non-negative integer height, as a number, a bigint or a decimal string. */
+export declare function parseHeight(value: unknown, what?: string): bigint;
+/** `0x…` hex with a trailing 4-byte SHA-256 checksum, as AvalancheGo encodes bytes. */
+export declare function decodeChecked(value: unknown, what: string): Uint8Array;
+/** `0x…` hex of `bytes` with AvalancheGo's checksum. */
+export declare function encodeChecked(bytes: Uint8Array): string;
+/** The JSON block of `getBlock`/`getBlockByHeight`, X-Chain or P-Chain, any block type. */
+export declare function parseBlock(answer: unknown): NodeBlock;
+export declare function parsePlatformStatus(answer: unknown): PlatformStatus;
+/** `getUTXOs` asks for at most this many outputs per page (AvalancheGo's maximum). */
+export declare const UTXO_PAGE = 1024;
+export declare class AvalancheNode {
+    #private;
+    constructor(transport: Transport, vm: AvalancheVm);
+    height(tags: AvalancheCallTags): Promise<bigint>;
+    /** The accepted block at `height`; `null` when the node has none there (yet). */
+    blockAt(height: bigint, tags: AvalancheCallTags): Promise<NodeBlock | null>;
+    blockById(blockId: string, tags: AvalancheCallTags): Promise<NodeBlock | null>;
+    /**
+     * An accepted transaction's signed bytes, which must hash to `txId`; `null` when the node
+     * does not have it in its accepted state.
+     */
+    txBytes(txId: string, tags: AvalancheCallTags): Promise<Uint8Array | null>;
+    /** P-Chain only: committed, aborted, in a mempool, dropped by one, or unknown. */
+    txStatus(txId: string, tags: AvalancheCallTags): Promise<PlatformStatus>;
+    /**
+     * Every output the node lists for `address` (its UTXO set), as raw UTXO bytes, read page
+     * by page. An output listed twice alike is kept once; listed twice differently, the
+     * answer is malformed.
+     */
+    utxos(address: string, tags: AvalancheCallTags): Promise<Uint8Array[]>;
+    /** Issues signed bytes; resolves to the id the node gives them. */
+    issueTx(bytes: Uint8Array, tags: AvalancheCallTags): Promise<string>;
+    /** X-Chain: the fixed fee of a transaction (`txFee`), in nAVAX. */
+    txFee(tags: AvalancheCallTags): Promise<bigint>;
+    /** P-Chain: the current gas price and capacity (Etna's dynamic fees). */
+    feeState(tags: AvalancheCallTags): Promise<FeeState>;
+    /** P-Chain: the weights of the four fee dimensions and the minimum gas price. */
+    feeConfig(tags: AvalancheCallTags): Promise<{
+        readonly weights: FeeWeights;
+        readonly minPrice: bigint;
+    }>;
+}
+/** One transaction of an address's history, as the Data API lists it (newest first). */
+export interface HistoryEntry {
+    readonly txId: string;
+    /** Absent for an X-Chain transaction from before its linearization (no block). */
+    readonly location?: Location;
+}
+export declare class DataApi {
+    #private;
+    constructor(transport: Transport);
+    /** Where the indexer says `txId` is; `null` when it does not know it (404). */
+    locate(txId: string, tags: AvalancheCallTags): Promise<Location | null | 'no-block'>;
+    /** A page of `address`'s transactions, newest first. */
+    history(address: string, options: {
+        readonly cursor?: string;
+        readonly pageSize: number;
+    }, tags: AvalancheCallTags): Promise<{
+        readonly items: readonly HistoryEntry[];
+        readonly next?: string;
+    }>;
+    /** The hash of the indexer's block at height 0 (its identity probe). */
+    static blockZero(answer: unknown): string;
+    /** The indexer's newest block height (its height probe). */
+    static latestHeight(answer: unknown): bigint;
+}