ecash-wallet

A production-ready wallet class for building and broadcasting eCash (XEC) txs

Use

Install with npm (when published).

npm i ecash-wallet

Import. Create your Wallet and use methods.

import { Wallet } from "ecash-wallet";

const mnemonic = 'morning average minor stable parrot refuse credit exercise february mirror just begin',

const wallet = Wallet.fromMnemonic(mnemonic, chronik);

See tests for detailed methods.

MultisigWallet (MultisigWallet, P2SH m-of-n ECDSA)

MultisigWallet.fromCosigners builds the redeem script with pubkeys sorted by lexicographic byte order (compressed pubkey encoding), matching Electrum-ABC (MultisigWallet.pubkeys_to_redeem_script uses sorted(pubkeys) in electrumabc/wallet.py). Pass cosigners in any order; duplicates are rejected. This convention is only in ecash-wallet; ecash-lib does not impose a multisig pubkey ordering policy.

Exactly one cosigner entry must include a secret key per instance (this party's wallet); other participants use their own MultisigWallet with sk on the matching pubkey entry.

BuiltAction.broadcast() rejects partial multisig txs and does not auto-retry after UTXO conflict errors (sync + rebuild + immediate broadcast only fits fully signed Wallet builds). On failure: sync, rebuild, redo signPartialTx handoff, broadcast again.

Optional broadcast({ finalizationTimeoutSecs: 60 }) uses chronik-client's broadcastAndFinalizeTxs to wait for Avalanche finalization. Default behavior is unchanged: broadcast to mempool only.

Roadmap

ecash-wallet is engineered to be a drop-in wallet lib for any ecash application that needs wallet functionality. The first milestone demonstrating minimal fulfillment of this requirement will be the integration of ecash-wallet into Cashtab.

Phase One, Cashtab feature parity

• XEC actions [x] Send XEC to one recipient [x] Send XEC to many recipients

• GENESIS, MINT, SEND, and BURN for all token types [x] SLP_TOKEN_TYPE_FUNGIBLE [x] ALP_TOKEN_TYPE_STANDARD [x] SLP_TOKEN_TYPE_MINT_VAULT SEND and BURN actions
  [x] SLP_TOKEN_TYPE_NFT1_GROUP [x] SLP_TOKEN_TYPE_NFT1_CHILD (Mint NFTs) [x] DataAction for ALP_TOKEN_TYPE_STANDARD txs [X] BURN txs for arbitrary amounts using BURN method (intentional burn, not SEND) [X] One-step mints for SLP NFTs

• Agora actions (PARTIAL and ONESHOT) [] SLP (requires "chained" txs) [] ALP

Phase Two, extended functionality

[x] Support for chained XEC txs, i.e. handling an Action that requires more than one tx due to the 100,000 byte tx size restriction [x] Support for chained token txs, i.e. handling an Action that requires more than one tx due to token protocol per-tx output limits

Phase Three, wishlist

[] HD wallets [] Fine-grained utxo control, avalanche proofs [] SLP_TOKEN_TYPE_MINT_VAULT GENESIS and MINT actions

Change log

• 0.0.0 Init with constructor and sync method D17773
• 0.0.1 Add utxo getter methods getFuelUtxos and getSpendableCoinbaseUtxos D17779

1.0.0

D17822 Add support for building and broadcasting txs, including ALP and SLP token txs. Update methods and syntax. Add preliminary support for Postage protocol. D18384 Add fromMnemonic constructor, make Wallet a normal export (not uniquely a default export), call broadcastTx using hex rawTx to facilitate testing with mock-chronik-client (practical improvements from implementing ecash-wallet in cashtab-faucet) D18390 Patch the main entry in package.json to point to dist/index.js

1.0.1

D18391 Patch README

1.1.0

D18398 Accept addresses in the transaction ouputs

1.2.0

D18548 Support GENESIS, SEND, and BURN for SLP_TOKEN_TYPE_MINT_VAULT

1.3.0

D18551 Support GENESIS, SEND, MINT, and BURN for SLP_TOKEN_TYPE_NFT1_GROUP

1.4.0

D18558 Support GENESIS, SEND, and BURN for SLP_TOKEN_TYPE_NFT1_CHILD

1.5.0

D18585 Support DataAction for ALP token sends

2.0.0

D18627

• Support intentional SLP burns for arbitrary amounts with a chained tx.
• Support automatic updating of determined wallet utxo set on tx build() (unless user opts out, e.g. for running tests) (NB does not apply to PostageTx)
• BREAKING CHANGE the .broadcast() method no longer throws, returns a success key with more information
• Patch issue where SLP burns are not invalidated for including specified outputs

2.0.1

D18673

• Type errors uncovered when using ecash-wallet as a dep in ecash-agora

2.1.0

D18834

• Support chained txs for minting SLP NFTs without requiring a "fan-out" tx

2.1.1

D18839

• Patch type issue in returning SelectUtxosResult

2.1.2

D18840

• Export the BuiltAction class to support the user of Wallet in the ecash-agora AgoraOffer take method

2.1.3

D18841

• Return sats selection strategy used to select utxos with SelectUtxosResult

2.2.0

D18837

• Update the PostageTx class to support client/server postage interactions

2.3.0

D18867

• Support chained txs to handle XEC-only Actions that would exceed MAX_TX_SERSIZE if built in a single tx

2.3.1

D18920

• Prevent addFuelAndSign from adding unnecessary postage

2.3.2

D18924

• Automatically remove consumed postage utxos from the postage wallet in addFuelAndSign method

2.3.3

D18932

• Tolerate token outputs without the isMintBaton key, but always classify such inputs as if they were isMintBaton: false

2.3.4

D18975

• Publish to catch updated chronik-client dep

2.3.5

D18994

• Publish to catch updated chronik-client dep

2.3.6

D19051

2.3.7

• Publish to catch updated chronik-client dep

D19139

2.3.8

• Add stub methods for HD support (not a functional wallet, but could be used to derive different accounts)

D19233

2.3.9

• Add methods for getting receive and change addresses for HD wallets

D19245

3.0.0 BREAKING CHANGE

• Add sync() support for the HD wallet
• Introduce new WalletUtxo type with included address key, which will help match utxos with keypairs for HD transaction signing (breaking change)

D19249

3.1.0

• Add balanceSats as wallet property that updates on sync()

D19266

3.2.0

• Support for msg signing and txs from HD wallets
• Similar to non-HD, we also "auto-update" the wallet's utxo set after txs are built
• For a consistent API, we introduce methods that return different addresses/scripts depending on whether or not the wallet is HD

D19271

3.2.1

• For ALP burns, if we do not have an exact qty utxo, we infer a SEND action for change
• Introduce action preprocessing and typed error, ExactAtomsNotFoundError, to support this inferrence

D19301

3.3.0

• Support for chained token txs

D19316

3.4.0

• Add maxSendSats method for determining how many sats we can send to leave no balance remaining in the wallet

D19349

3.5.0

• If broadcasting a tx fails due to bad-txns-inputs-missingorspent or txn-mempool-conflict, resync the utxo set and try again

D19348

3.5.1

• Update method name updateBalance instead of updateBalances

D19352

3.6.0

• Add addReceivedTx method to support updating the utxo set and balance of a wallet with an incoming tx, including processing inputs to remove spent UTXOs

D19351

3.6.1

• Make addReceivedTx robust against txs with non-standard address types

D19371

3.6.2

• If broadcasting a tx fails due to finalized-tx-conflict, resync the utxo set and try again

D19376

3.7.0

• Add a WalletAction.inspect() method that can't be broadcasted and won't update the utxos. This can be used to inspect the tx and compute the fees without impacting the wallet.

D19390

3.8.0

• Add a Wallet.isWalletAddress() method to check if an address belongs to the wallet.
• Add a Wallet.getTxAmounts() to get all the balance changes introduced by a transaction from the wallet history.

D19390 D19403

3.9.0

• Add a new class WatchOnlyWallet to support watch only wallets (both HD and single-address)

D19406

3.10.0

• Add support for wallets using a custom prefix

D19441

4.0.0 BREAKING CHANGE

• Add support for building token postage aka "swap" txs (partially signed txs with token outputs that require added token inputs)
• Changes the API as satsStrategy is no longer its own param, now part of SelectUtxosConfig

D19476

4.0.1

• Add a memory limit on iterations for attempts to determine exact atom available in utxo set to prevent OOM crashes

D19556

4.1.0

• Add support for optional p2shInputData key. When used, create a chained tx so that a user may encode arbitrary data in a p2sh input. The approach follows what is modeled by ecash-agora "ad prep" txs that allow advertisable SLP listings for NFTs and partials. This could be used to allow SLP txs to include data, or to expand the data included by an XEC or ALP tx.

D19600

4.2.0

• Add a consolidateUtxos method that consolidates XEC or token utxos by tokenId down to a single utxo

D19613

5.0.0 BREAKING CHANGE

• Requires chronik >= 0.32.10
• Use broadcastTxs instead of broadcastTx to handle chained txs (requires upgraded chronik server)

D19628

5.1.0

• Export the functions from WatchOnlyWallet

D19651

5.2.0

• Support p2sh multisig (ECDSA only) D19777

5.3.0

• Automatically consolidate utxos if a tx fails due to a maxSerSize error not related to too many outputs D19800

5.4.0

• Use batch requests to sync the utxos of HD wallets D19943

5.4.1

• Fix a broken package.json for the eCash dependencies.

5.5.0

• Add optional support for waiting on txs to finalize by using chronik-client exposed broadcastAndFinalizeTxs D20014

5.5.1 D20201

• Upgrade to ecash-lib 4.13.0 for Next.js-friendly WASM loading (embedded base64 on Node.js as well as the browser)

5.6.0 D20222

• Support ALP SEND actions with multiple token IDs and multiple token outputs in a single user action
• Use a single tx when all specified outputs fit within protocol limits (including the 223-byte OP_RETURN limit for multi-tokenId sends); DATA actions may be combined with multi-tokenId sends in the same tx when it fits
• Auto-chain one ALP send per tokenId when outputs or OP_RETURN size require it; chained multi-tokenId ALP sends support SEND actions only (MINT, BURN, etc. are not supported in this path)
• SLP actions remain limited to a single tokenId per action (unchanged)

5.7.0 D20231

• Add syncAndDiscoverAddresses() for HD wallets (Wallet and WatchOnlyWallet): BIP44-style gap-limit scanning to discover receive/change indices when restoring from mnemonic or xpub with no prior index knowledge. Supports shared or per-chain gap limits (gapLimit / receiveGapLimit / changeGapLimit, default 20 via DEFAULT_GAP_LIMIT) and optional startReceiveIndex / startChangeIndex. Normal sync() is unchanged and still assumes indices are already correct.

6.0.0 BREAKING CHANGE D20233

• Unify postage with the funded build() shape: buildPostage() always returns PostageChain[]
• Unchained NO_SATS Actions yield one 1-step chain; chained token sends yield one or more multi-step chains (ALP multi-tokenId: one chain per SEND tokenId)
• Per link: chain.buildStepPostage(i, prevFuelCompletedTxid?) → partial PostageTx for a postage server to fuel-complete before any broadcast
• BREAKING CHANGE Removes the old singular buildPostage(): PostageTx return type; callers must use buildPostage()[0].buildStepPostage(0) for single-tx postage (or iterate chains/steps for chained sends)

6.1.0 D20299

Add optional onAddress callback to syncAndDiscoverAddresses() (SyncAndDiscoverOptions): invoked for each address as it is scanned during HD gap-limit discovery (including the final address that completes the gap), then stops for that chain once the gap limit is reached. Each call receives an AddressSummary (forChange, index, address, and Chronik BatchSummaryRow data). Useful for app-specific heuristics such as WebSocket subscribe lists without a separate gap scan.

Requires Chronik's POST /script/batch/summary endpoint (Chronik server >= 0.33.4, chronik-client >= 4.3.0); if the endpoint is unavailable, gap discovery falls back to per-script queries and the callback is not invoked.

6.1.2 D20528

• Treat findIndex === -1 as a missing requiredUtxo in selectUtxos. The previous typeof index === 'undefined' check never fired (Array.prototype.findIndex returns -1), so a missing outpoint was spliced as undefined and later crashed on .sats.

6.1.1 D20521

• Default omitted PaymentOutput.sats to dustSats in chained XEC size-limit builds, matching paymentOutputsToTxOutputs. A large XEC action with default-dust recipients previously undercounted the chain and failed to build.
• Honor the action dustSats when deciding whether chained alpha user change is above dust, and fill omitted sats on finalized payment outputs so a chained self-send updates the in-memory UTXO set correctly.

6.1.3 D20538

• Patch bump to catch the latest chronik-client

6.2.0 D20561

• Honor optional payment.Action.changeScript so XEC change can go to a script other than the spending wallet. Cannot be combined with noChange. Intermediate chained-tx fuel still goes to the spender.

6.2.1 D20579

• Patch bump to catch the latest ecash-lib

6.2.2 D20768

• Patch bump to catch the latest ecash-lib

6.2.3 D20775

• Patch bump to catch the latest chronik-client

6.2.4 D20822

• Patch bump to catch the latest chronik-client and ecash-lib

6.2.5 D20878

• Patch bump to catch the latest chronik-client and ecash-lib

6.2.6 D20906

• Patch bump to catch the latest chronik-client and ecash-lib