@arkade-os/sdk 0.4.46 → 0.4.48-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/dist/adapters/expo.cjs +5 -5
  2. package/dist/adapters/expo.d.cts +2 -2
  3. package/dist/adapters/expo.d.ts +2 -2
  4. package/dist/adapters/expo.js +3 -3
  5. package/dist/adapters/indexedDB.cjs +5 -5
  6. package/dist/adapters/indexedDB.js +4 -4
  7. package/dist/{ark-C9ognsOV.d.cts → ark-CoJgwTi_.d.cts} +26 -2
  8. package/dist/{ark-C9ognsOV.d.ts → ark-CoJgwTi_.d.ts} +26 -2
  9. package/dist/{asyncStorageTaskQueue-CmBYVlxw.d.cts → asyncStorageTaskQueue-CwknfM_j.d.cts} +1 -1
  10. package/dist/{asyncStorageTaskQueue-BAKZ5cS5.d.ts → asyncStorageTaskQueue-D2Zl7yAB.d.ts} +1 -1
  11. package/dist/{chunk-SOXGAA52.cjs → chunk-3HUZAIKI.cjs} +14 -14
  12. package/dist/{chunk-SOXGAA52.cjs.map → chunk-3HUZAIKI.cjs.map} +1 -1
  13. package/dist/{chunk-R2SVAM5Q.js → chunk-4AIHKC65.js} +3 -3
  14. package/dist/{chunk-R2SVAM5Q.js.map → chunk-4AIHKC65.js.map} +1 -1
  15. package/dist/{chunk-FWG4TSPN.js → chunk-C7TXXTMS.js} +4 -5
  16. package/dist/chunk-C7TXXTMS.js.map +1 -0
  17. package/dist/{chunk-7IYIFMF4.cjs → chunk-CFQO5MCM.cjs} +94 -20
  18. package/dist/chunk-CFQO5MCM.cjs.map +1 -0
  19. package/dist/{chunk-6TQJOD72.cjs → chunk-EA3IWZ4W.cjs} +7 -7
  20. package/dist/{chunk-6TQJOD72.cjs.map → chunk-EA3IWZ4W.cjs.map} +1 -1
  21. package/dist/{chunk-CWJ7ZCP7.js → chunk-GM6JRQP5.js} +87 -16
  22. package/dist/chunk-GM6JRQP5.js.map +1 -0
  23. package/dist/{chunk-MQB5H4X5.cjs → chunk-L5ND2FJJ.cjs} +4 -5
  24. package/dist/chunk-L5ND2FJJ.cjs.map +1 -0
  25. package/dist/{chunk-D46YDM36.cjs → chunk-RJMFTTRJ.cjs} +1586 -286
  26. package/dist/chunk-RJMFTTRJ.cjs.map +1 -0
  27. package/dist/chunk-RQSA7ADZ.cjs +2286 -0
  28. package/dist/chunk-RQSA7ADZ.cjs.map +1 -0
  29. package/dist/{chunk-P6VBP3CT.js → chunk-SV4PCGKM.js} +1388 -100
  30. package/dist/chunk-SV4PCGKM.js.map +1 -0
  31. package/dist/chunk-XN3554FT.js +2244 -0
  32. package/dist/chunk-XN3554FT.js.map +1 -0
  33. package/dist/{chunk-JTCQ6QXQ.js → chunk-ZRY2KSK5.js} +4 -4
  34. package/dist/{chunk-JTCQ6QXQ.js.map → chunk-ZRY2KSK5.js.map} +1 -1
  35. package/dist/contracts/handlers/index.cjs +11 -7
  36. package/dist/contracts/handlers/index.d.cts +3 -3
  37. package/dist/contracts/handlers/index.d.ts +3 -3
  38. package/dist/contracts/handlers/index.js +2 -2
  39. package/dist/{delegate-aOd5qINr.d.ts → delegate-CuaDqqQi.d.ts} +1 -1
  40. package/dist/{delegate-DVEgyRwI.d.cts → delegate-Dl87_zMA.d.cts} +1 -1
  41. package/dist/index-BC_G0VTh.d.cts +512 -0
  42. package/dist/index-CKwpZEpw.d.ts +512 -0
  43. package/dist/index.cjs +221 -161
  44. package/dist/index.d.cts +3129 -2089
  45. package/dist/index.d.ts +3129 -2089
  46. package/dist/index.js +4 -4
  47. package/dist/repositories/realm/index.cjs +19 -19
  48. package/dist/repositories/realm/index.d.cts +2 -2
  49. package/dist/repositories/realm/index.d.ts +2 -2
  50. package/dist/repositories/realm/index.js +5 -5
  51. package/dist/repositories/sqlite/index.cjs +18 -18
  52. package/dist/repositories/sqlite/index.d.cts +2 -2
  53. package/dist/repositories/sqlite/index.d.ts +2 -2
  54. package/dist/repositories/sqlite/index.js +5 -5
  55. package/dist/{taskRunner-B48-V-Pb.d.ts → taskRunner-Df8YQpn1.d.ts} +1 -1
  56. package/dist/{taskRunner-nNecmQ2C.d.cts → taskRunner-RYihSj9E.d.cts} +1 -1
  57. package/dist/wallet/expo/background.cjs +14 -14
  58. package/dist/wallet/expo/background.d.cts +3 -3
  59. package/dist/wallet/expo/background.d.ts +3 -3
  60. package/dist/wallet/expo/background.js +6 -6
  61. package/dist/wallet/expo/index.cjs +14 -14
  62. package/dist/wallet/expo/index.d.cts +4 -4
  63. package/dist/wallet/expo/index.d.ts +4 -4
  64. package/dist/wallet/expo/index.js +5 -5
  65. package/dist/{wallet-BUg3D4WJ.d.cts → wallet-B6s7_5bJ.d.cts} +136 -3
  66. package/dist/{wallet-DM0oShTu.d.ts → wallet-C61huH8i.d.ts} +136 -3
  67. package/dist/worker/expo/index.cjs +9 -9
  68. package/dist/worker/expo/index.d.cts +4 -4
  69. package/dist/worker/expo/index.d.ts +4 -4
  70. package/dist/worker/expo/index.js +5 -5
  71. package/package.json +1 -1
  72. package/dist/chunk-4KXOCVXP.cjs +0 -973
  73. package/dist/chunk-4KXOCVXP.cjs.map +0 -1
  74. package/dist/chunk-7IYIFMF4.cjs.map +0 -1
  75. package/dist/chunk-CWJ7ZCP7.js.map +0 -1
  76. package/dist/chunk-D46YDM36.cjs.map +0 -1
  77. package/dist/chunk-FWG4TSPN.js.map +0 -1
  78. package/dist/chunk-MQB5H4X5.cjs.map +0 -1
  79. package/dist/chunk-P6VBP3CT.js.map +0 -1
  80. package/dist/chunk-QKC2T54O.js +0 -960
  81. package/dist/chunk-QKC2T54O.js.map +0 -1
  82. package/dist/index-CPzL4tqg.d.ts +0 -259
  83. package/dist/index-D8vmtWWO.d.cts +0 -259
@@ -1,8 +1,8 @@
1
1
  import { Transaction } from '@scure/btc-signer';
2
2
  import { Bytes } from '@scure/btc-signer/utils.js';
3
- import { J as BatchStartedEvent, K as TreeSigningStartedEvent, L as TxTree, M as TreeNoncesEvent, N as BatchFinalizationEvent, P as BatchFinalizedEvent, Q as BatchFailedEvent, U as TreeTxEvent, X as TreeSignatureEvent, j as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, Y as DescriptorProvider, g as IContractManager, Z as IReadonlyWallet, _ as ReadonlyIdentity, $ as Network, a0 as OnchainProvider, p as IndexerProvider, a1 as DelegateProvider, a2 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a3 as ExitCaptureMode, a4 as ExitDataSource, q as RelativeTimelock, e as ActivityRegistry, a5 as IReadonlyAssetManager, a6 as ContractSyncState, o as ArkProvider, a7 as NetworkName, a8 as ArkInfo, a9 as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, f as Activity, d as ExtendedCoin, aa as Coin, ab as ContractManager, I as IWallet, a as Identity, ac as CSVMultisigTapscript, ad as SettlementConfig, k as IAssetManager, ae as VtxoManager, h as IDelegateManager, S as SendBitcoinParams, i as SettleParams, R as Recipient, af as SignerSession, ag as SignedIntent, ah as Intent } from './ark-C9ognsOV.cjs';
3
+ import { J as BatchStartedEvent, K as TreeSigningStartedEvent, L as TxTree, M as TreeNoncesEvent, N as BatchFinalizationEvent, P as BatchFinalizedEvent, Q as BatchFailedEvent, U as TreeTxEvent, X as TreeSignatureEvent, j as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, Y as DescriptorProvider, g as IContractManager, Z as IReadonlyWallet, _ as ReadonlyIdentity, $ as Network, a0 as OnchainProvider, p as IndexerProvider, a1 as DelegateProvider, a2 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a3 as ExitCaptureMode, a4 as ExitDataSource, q as RelativeTimelock, e as ActivityRegistry, a5 as IReadonlyAssetManager, a6 as ContractSyncState, o as ArkProvider, a7 as NetworkName, a8 as ArkInfo, a9 as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, f as Activity, d as ExtendedCoin, aa as Coin, ab as ContractManager, I as IWallet, a as Identity, ac as CSVMultisigTapscript, ad as SettlementConfig, k as IAssetManager, ae as VtxoManager, h as IDelegateManager, S as SendBitcoinParams, i as SettleParams, R as Recipient, af as SignerSession, ag as SignedIntent, ah as Intent } from './ark-CoJgwTi_.cjs';
4
4
  import { TransactionOutput } from '@scure/btc-signer/psbt.js';
5
- import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-DVEgyRwI.cjs';
5
+ import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-Dl87_zMA.cjs';
6
6
 
7
7
  declare class ArkError extends Error {
8
8
  readonly code: number;
@@ -486,6 +486,62 @@ interface BoardingUtxoGroup {
486
486
  csvTimelock: RelativeTimelock;
487
487
  coins: ExtendedCoin[];
488
488
  }
489
+ /**
490
+ * Why a VTXO at an arkcash address could not be swept by {@link Wallet.claimCash}.
491
+ *
492
+ * - `swept` — the server swept the batch at expiry. Recoverable in principle,
493
+ * but only through a settlement, which the thin sweep cannot do.
494
+ * - `subdust` — below dust, so it sits at an OP_RETURN script with no spendable
495
+ * leaf. Unspendable as cash; `createCash` prevents minting these.
496
+ * - `already-spent` — someone else claimed it first.
497
+ * - `has-assets` — asset-bearing; the BTC-only sweep would burn the assets.
498
+ * - `sweep-failed` — spendable, but its own sweep was rejected.
499
+ */
500
+ type ArkCashUnclaimedReason = "swept" | "subdust" | "already-spent" | "has-assets" | "sweep-failed";
501
+ /** A VTXO {@link Wallet.claimCash} left behind, with the reason why. */
502
+ interface ArkCashUnclaimedVtxo {
503
+ txid: string;
504
+ vout: number;
505
+ /** Value in satoshis. */
506
+ value: number;
507
+ reason: ArkCashUnclaimedReason;
508
+ }
509
+ /**
510
+ * Outcome of {@link Wallet.claimCash}: what was swept, and what was not.
511
+ *
512
+ * The shape is open — further buckets may be added alongside `unclaimed` as
513
+ * more of the non-sweepable states become claimable.
514
+ */
515
+ interface ArkCashClaimResult {
516
+ /** Satoshis swept to this wallet. */
517
+ swept: number;
518
+ unclaimed: {
519
+ /** Satoshis left behind. */
520
+ amount: number;
521
+ vtxos: ArkCashUnclaimedVtxo[];
522
+ };
523
+ }
524
+ /**
525
+ * Thrown when {@link Wallet.createCash} funds the note but its `send` call
526
+ * fails after the transaction may already have been submitted.
527
+ *
528
+ * The whole value of the note lives in `cash`: it carries the private key that
529
+ * controls the funded output. If `send` committed and this error is discarded,
530
+ * the sats are stranded at an address only this token can reach. Callers that
531
+ * cannot rule out a post-submit failure must persist `cash` — passing it to
532
+ * {@link Wallet.claimCash} recovers the funds whether or not the send landed.
533
+ */
534
+ declare class ArkCashCreateError extends Error {
535
+ /** The encoded arkcash token controlling the funded output. */
536
+ readonly cash: string;
537
+ /** The original failure from `send`. */
538
+ readonly cause: unknown;
539
+ constructor(
540
+ /** The encoded arkcash token controlling the funded output. */
541
+ cash: string,
542
+ /** The original failure from `send`. */
543
+ cause: unknown);
544
+ }
489
545
  /**
490
546
  * Freshness of the wallet's provider-backed sync, composed from the boot
491
547
  * server-info source and the contract-manager's indexer-sync health. It
@@ -1264,6 +1320,73 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
1264
1320
  }>;
1265
1321
  private hasPendingTxFlag;
1266
1322
  private setPendingTxFlag;
1323
+ /**
1324
+ * Create an ArkCash bearer instrument.
1325
+ *
1326
+ * Generates a fresh keypair, sends the specified amount to a DefaultVtxo
1327
+ * controlled by the new key, and returns the encoded arkcash string.
1328
+ * The receiver can claim the funds using `claimCash()` without ever
1329
+ * sharing their address.
1330
+ *
1331
+ * ArkCash is a short-lived instrument: it carries a private key, so it is
1332
+ * meant to be handed over and claimed promptly, not held. A note left
1333
+ * unclaimed past its batch expiry is swept by the server and `claimCash`
1334
+ * can only report it, not move it.
1335
+ *
1336
+ * @param amount - Amount in satoshis to send. Must be a whole number of
1337
+ * sats at or above the dust threshold — a below-dust amount would mint an
1338
+ * OP_RETURN output that is unspendable as cash.
1339
+ * @returns The encoded arkcash string (e.g., "arkcash1...")
1340
+ */
1341
+ createCash(amount: number): Promise<string>;
1342
+ /**
1343
+ * Claim an ArkCash bearer instrument: sweep what can be swept, report the
1344
+ * rest.
1345
+ *
1346
+ * Every spendable VTXO at the arkcash address is swept to this wallet in
1347
+ * its own offchain transaction, signed with the key carried by the arkcash
1348
+ * string. Nothing is ever persisted: no contract is imported, and the
1349
+ * arkcash key is not stored. Anything that cannot be swept — server-swept,
1350
+ * subdust, already claimed, or asset-bearing — is returned in `unclaimed`
1351
+ * with a per-VTXO reason and otherwise ignored.
1352
+ *
1353
+ * The arkcash string is the recovery token: a claim interrupted between
1354
+ * submit and finalize is completed by simply re-running `claimCash`, which
1355
+ * drains any pending arkcash transaction on the server before sweeping.
1356
+ *
1357
+ * @param cashStr - The encoded arkcash string (e.g., "arkcash1...")
1358
+ * @returns The swept total and the report of what was left behind. The
1359
+ * shape is open: further buckets may be added alongside `unclaimed`.
1360
+ */
1361
+ claimCash(cashStr: string): Promise<ArkCashClaimResult>;
1362
+ /**
1363
+ * Split the VTXOs at an arkcash address into the ones the thin sweep can
1364
+ * move and the ones it can only report.
1365
+ */
1366
+ private classifyCashVtxos;
1367
+ /** Read every page of an unfiltered VTXO query for the given scripts. */
1368
+ private fetchAllVtxos;
1369
+ /**
1370
+ * Complete any sweep a previous `claimCash` registered but never finalized.
1371
+ * A thin variant of {@link finalizePendingTxs}, scoped to the arkcash key:
1372
+ * the intent is signed with it, and so are the returned checkpoints.
1373
+ *
1374
+ * A drained sweep is not automatically *ours*. Whoever registered it chose
1375
+ * the destination, so a tx a different claimer left half-finished pays that
1376
+ * claimer — finalizing it is still right (the input is spent either way, and
1377
+ * completing it unsticks the funds), but only the value it actually pays to
1378
+ * `myPkScript` may be counted as claimed here.
1379
+ *
1380
+ * @param vtxos - VTXOs at the arkcash contract's own pkScript, spent ones
1381
+ * included (a registered sweep marks its input spent). Any other outpoint —
1382
+ * subdust above all — would make the proof invalid, since it describes every
1383
+ * input by that pkScript.
1384
+ * @returns The number of pending txs finalized, the sats among them paid to
1385
+ * this wallet, and the outpoints those txs consumed to pay it.
1386
+ */
1387
+ private finalizePendingCashTxs;
1388
+ /** Sum the outputs of an ark tx PSBT that pay the given scriptPubKey. */
1389
+ private arkTxAmountPaidTo;
1267
1390
  /**
1268
1391
  * Send BTC and/or assets to one or more recipients.
1269
1392
  *
@@ -1319,6 +1442,16 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
1319
1442
  private updateDbAfterOffchainTx;
1320
1443
  private updateDbAfterSettle;
1321
1444
  }
1445
+ /**
1446
+ * Select virtual outputs to reach a target amount, prioritizing those closer to expiry
1447
+ * @param coins List of virtual outputs to select from
1448
+ * @param targetAmount Target amount to reach in satoshis
1449
+ * @returns Selected virtual outputs and change amount
1450
+ */
1451
+ declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount: number): {
1452
+ inputs: ExtendedVirtualCoin[];
1453
+ changeAmount: bigint;
1454
+ };
1322
1455
  /**
1323
1456
  * Wait for incoming funds to the wallet
1324
1457
  * @param wallet - The wallet to wait for incoming funds
@@ -1326,4 +1459,4 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
1326
1459
  */
1327
1460
  declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
1328
1461
 
1329
- export { ArkError as A, Batch as B, type IncomingFunds as I, type ProviderConnectionState as P, ReadonlyWallet as R, type ServerInfoSource as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, ArkErrorName as d, type BoardingUtxoGroup as e, type ProviderKind as f, ProviderUnavailableError as g, isArkError as i, maybeArkError as m, waitForIncomingFunds as w };
1462
+ export { type ArkCashClaimResult as A, Batch as B, type IncomingFunds as I, type ProviderConnectionState as P, ReadonlyWallet as R, type ServerInfoSource as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, ArkCashCreateError as d, type ArkCashUnclaimedReason as e, type ArkCashUnclaimedVtxo as f, ArkError as g, ArkErrorName as h, type BoardingUtxoGroup as i, type ProviderKind as j, ProviderUnavailableError as k, isArkError as l, maybeArkError as m, selectVirtualCoins as s, waitForIncomingFunds as w };
@@ -1,8 +1,8 @@
1
1
  import { Transaction } from '@scure/btc-signer';
2
2
  import { Bytes } from '@scure/btc-signer/utils.js';
3
- import { J as BatchStartedEvent, K as TreeSigningStartedEvent, L as TxTree, M as TreeNoncesEvent, N as BatchFinalizationEvent, P as BatchFinalizedEvent, Q as BatchFailedEvent, U as TreeTxEvent, X as TreeSignatureEvent, j as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, Y as DescriptorProvider, g as IContractManager, Z as IReadonlyWallet, _ as ReadonlyIdentity, $ as Network, a0 as OnchainProvider, p as IndexerProvider, a1 as DelegateProvider, a2 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a3 as ExitCaptureMode, a4 as ExitDataSource, q as RelativeTimelock, e as ActivityRegistry, a5 as IReadonlyAssetManager, a6 as ContractSyncState, o as ArkProvider, a7 as NetworkName, a8 as ArkInfo, a9 as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, f as Activity, d as ExtendedCoin, aa as Coin, ab as ContractManager, I as IWallet, a as Identity, ac as CSVMultisigTapscript, ad as SettlementConfig, k as IAssetManager, ae as VtxoManager, h as IDelegateManager, S as SendBitcoinParams, i as SettleParams, R as Recipient, af as SignerSession, ag as SignedIntent, ah as Intent } from './ark-C9ognsOV.js';
3
+ import { J as BatchStartedEvent, K as TreeSigningStartedEvent, L as TxTree, M as TreeNoncesEvent, N as BatchFinalizationEvent, P as BatchFinalizedEvent, Q as BatchFailedEvent, U as TreeTxEvent, X as TreeSignatureEvent, j as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, Y as DescriptorProvider, g as IContractManager, Z as IReadonlyWallet, _ as ReadonlyIdentity, $ as Network, a0 as OnchainProvider, p as IndexerProvider, a1 as DelegateProvider, a2 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a3 as ExitCaptureMode, a4 as ExitDataSource, q as RelativeTimelock, e as ActivityRegistry, a5 as IReadonlyAssetManager, a6 as ContractSyncState, o as ArkProvider, a7 as NetworkName, a8 as ArkInfo, a9 as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, f as Activity, d as ExtendedCoin, aa as Coin, ab as ContractManager, I as IWallet, a as Identity, ac as CSVMultisigTapscript, ad as SettlementConfig, k as IAssetManager, ae as VtxoManager, h as IDelegateManager, S as SendBitcoinParams, i as SettleParams, R as Recipient, af as SignerSession, ag as SignedIntent, ah as Intent } from './ark-CoJgwTi_.js';
4
4
  import { TransactionOutput } from '@scure/btc-signer/psbt.js';
5
- import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-aOd5qINr.js';
5
+ import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-CuaDqqQi.js';
6
6
 
7
7
  declare class ArkError extends Error {
8
8
  readonly code: number;
@@ -486,6 +486,62 @@ interface BoardingUtxoGroup {
486
486
  csvTimelock: RelativeTimelock;
487
487
  coins: ExtendedCoin[];
488
488
  }
489
+ /**
490
+ * Why a VTXO at an arkcash address could not be swept by {@link Wallet.claimCash}.
491
+ *
492
+ * - `swept` — the server swept the batch at expiry. Recoverable in principle,
493
+ * but only through a settlement, which the thin sweep cannot do.
494
+ * - `subdust` — below dust, so it sits at an OP_RETURN script with no spendable
495
+ * leaf. Unspendable as cash; `createCash` prevents minting these.
496
+ * - `already-spent` — someone else claimed it first.
497
+ * - `has-assets` — asset-bearing; the BTC-only sweep would burn the assets.
498
+ * - `sweep-failed` — spendable, but its own sweep was rejected.
499
+ */
500
+ type ArkCashUnclaimedReason = "swept" | "subdust" | "already-spent" | "has-assets" | "sweep-failed";
501
+ /** A VTXO {@link Wallet.claimCash} left behind, with the reason why. */
502
+ interface ArkCashUnclaimedVtxo {
503
+ txid: string;
504
+ vout: number;
505
+ /** Value in satoshis. */
506
+ value: number;
507
+ reason: ArkCashUnclaimedReason;
508
+ }
509
+ /**
510
+ * Outcome of {@link Wallet.claimCash}: what was swept, and what was not.
511
+ *
512
+ * The shape is open — further buckets may be added alongside `unclaimed` as
513
+ * more of the non-sweepable states become claimable.
514
+ */
515
+ interface ArkCashClaimResult {
516
+ /** Satoshis swept to this wallet. */
517
+ swept: number;
518
+ unclaimed: {
519
+ /** Satoshis left behind. */
520
+ amount: number;
521
+ vtxos: ArkCashUnclaimedVtxo[];
522
+ };
523
+ }
524
+ /**
525
+ * Thrown when {@link Wallet.createCash} funds the note but its `send` call
526
+ * fails after the transaction may already have been submitted.
527
+ *
528
+ * The whole value of the note lives in `cash`: it carries the private key that
529
+ * controls the funded output. If `send` committed and this error is discarded,
530
+ * the sats are stranded at an address only this token can reach. Callers that
531
+ * cannot rule out a post-submit failure must persist `cash` — passing it to
532
+ * {@link Wallet.claimCash} recovers the funds whether or not the send landed.
533
+ */
534
+ declare class ArkCashCreateError extends Error {
535
+ /** The encoded arkcash token controlling the funded output. */
536
+ readonly cash: string;
537
+ /** The original failure from `send`. */
538
+ readonly cause: unknown;
539
+ constructor(
540
+ /** The encoded arkcash token controlling the funded output. */
541
+ cash: string,
542
+ /** The original failure from `send`. */
543
+ cause: unknown);
544
+ }
489
545
  /**
490
546
  * Freshness of the wallet's provider-backed sync, composed from the boot
491
547
  * server-info source and the contract-manager's indexer-sync health. It
@@ -1264,6 +1320,73 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
1264
1320
  }>;
1265
1321
  private hasPendingTxFlag;
1266
1322
  private setPendingTxFlag;
1323
+ /**
1324
+ * Create an ArkCash bearer instrument.
1325
+ *
1326
+ * Generates a fresh keypair, sends the specified amount to a DefaultVtxo
1327
+ * controlled by the new key, and returns the encoded arkcash string.
1328
+ * The receiver can claim the funds using `claimCash()` without ever
1329
+ * sharing their address.
1330
+ *
1331
+ * ArkCash is a short-lived instrument: it carries a private key, so it is
1332
+ * meant to be handed over and claimed promptly, not held. A note left
1333
+ * unclaimed past its batch expiry is swept by the server and `claimCash`
1334
+ * can only report it, not move it.
1335
+ *
1336
+ * @param amount - Amount in satoshis to send. Must be a whole number of
1337
+ * sats at or above the dust threshold — a below-dust amount would mint an
1338
+ * OP_RETURN output that is unspendable as cash.
1339
+ * @returns The encoded arkcash string (e.g., "arkcash1...")
1340
+ */
1341
+ createCash(amount: number): Promise<string>;
1342
+ /**
1343
+ * Claim an ArkCash bearer instrument: sweep what can be swept, report the
1344
+ * rest.
1345
+ *
1346
+ * Every spendable VTXO at the arkcash address is swept to this wallet in
1347
+ * its own offchain transaction, signed with the key carried by the arkcash
1348
+ * string. Nothing is ever persisted: no contract is imported, and the
1349
+ * arkcash key is not stored. Anything that cannot be swept — server-swept,
1350
+ * subdust, already claimed, or asset-bearing — is returned in `unclaimed`
1351
+ * with a per-VTXO reason and otherwise ignored.
1352
+ *
1353
+ * The arkcash string is the recovery token: a claim interrupted between
1354
+ * submit and finalize is completed by simply re-running `claimCash`, which
1355
+ * drains any pending arkcash transaction on the server before sweeping.
1356
+ *
1357
+ * @param cashStr - The encoded arkcash string (e.g., "arkcash1...")
1358
+ * @returns The swept total and the report of what was left behind. The
1359
+ * shape is open: further buckets may be added alongside `unclaimed`.
1360
+ */
1361
+ claimCash(cashStr: string): Promise<ArkCashClaimResult>;
1362
+ /**
1363
+ * Split the VTXOs at an arkcash address into the ones the thin sweep can
1364
+ * move and the ones it can only report.
1365
+ */
1366
+ private classifyCashVtxos;
1367
+ /** Read every page of an unfiltered VTXO query for the given scripts. */
1368
+ private fetchAllVtxos;
1369
+ /**
1370
+ * Complete any sweep a previous `claimCash` registered but never finalized.
1371
+ * A thin variant of {@link finalizePendingTxs}, scoped to the arkcash key:
1372
+ * the intent is signed with it, and so are the returned checkpoints.
1373
+ *
1374
+ * A drained sweep is not automatically *ours*. Whoever registered it chose
1375
+ * the destination, so a tx a different claimer left half-finished pays that
1376
+ * claimer — finalizing it is still right (the input is spent either way, and
1377
+ * completing it unsticks the funds), but only the value it actually pays to
1378
+ * `myPkScript` may be counted as claimed here.
1379
+ *
1380
+ * @param vtxos - VTXOs at the arkcash contract's own pkScript, spent ones
1381
+ * included (a registered sweep marks its input spent). Any other outpoint —
1382
+ * subdust above all — would make the proof invalid, since it describes every
1383
+ * input by that pkScript.
1384
+ * @returns The number of pending txs finalized, the sats among them paid to
1385
+ * this wallet, and the outpoints those txs consumed to pay it.
1386
+ */
1387
+ private finalizePendingCashTxs;
1388
+ /** Sum the outputs of an ark tx PSBT that pay the given scriptPubKey. */
1389
+ private arkTxAmountPaidTo;
1267
1390
  /**
1268
1391
  * Send BTC and/or assets to one or more recipients.
1269
1392
  *
@@ -1319,6 +1442,16 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
1319
1442
  private updateDbAfterOffchainTx;
1320
1443
  private updateDbAfterSettle;
1321
1444
  }
1445
+ /**
1446
+ * Select virtual outputs to reach a target amount, prioritizing those closer to expiry
1447
+ * @param coins List of virtual outputs to select from
1448
+ * @param targetAmount Target amount to reach in satoshis
1449
+ * @returns Selected virtual outputs and change amount
1450
+ */
1451
+ declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount: number): {
1452
+ inputs: ExtendedVirtualCoin[];
1453
+ changeAmount: bigint;
1454
+ };
1322
1455
  /**
1323
1456
  * Wait for incoming funds to the wallet
1324
1457
  * @param wallet - The wallet to wait for incoming funds
@@ -1326,4 +1459,4 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
1326
1459
  */
1327
1460
  declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
1328
1461
 
1329
- export { ArkError as A, Batch as B, type IncomingFunds as I, type ProviderConnectionState as P, ReadonlyWallet as R, type ServerInfoSource as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, ArkErrorName as d, type BoardingUtxoGroup as e, type ProviderKind as f, ProviderUnavailableError as g, isArkError as i, maybeArkError as m, waitForIncomingFunds as w };
1462
+ export { type ArkCashClaimResult as A, Batch as B, type IncomingFunds as I, type ProviderConnectionState as P, ReadonlyWallet as R, type ServerInfoSource as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, ArkCashCreateError as d, type ArkCashUnclaimedReason as e, type ArkCashUnclaimedVtxo as f, ArkError as g, ArkErrorName as h, type BoardingUtxoGroup as i, type ProviderKind as j, ProviderUnavailableError as k, isArkError as l, maybeArkError as m, selectVirtualCoins as s, waitForIncomingFunds as w };
@@ -1,10 +1,10 @@
1
1
  'use strict';
2
2
 
3
- var chunk6TQJOD72_cjs = require('../../chunk-6TQJOD72.cjs');
4
- require('../../chunk-D46YDM36.cjs');
5
- require('../../chunk-7IYIFMF4.cjs');
6
- require('../../chunk-4KXOCVXP.cjs');
7
- require('../../chunk-MQB5H4X5.cjs');
3
+ var chunkEA3IWZ4W_cjs = require('../../chunk-EA3IWZ4W.cjs');
4
+ require('../../chunk-RJMFTTRJ.cjs');
5
+ require('../../chunk-CFQO5MCM.cjs');
6
+ require('../../chunk-RQSA7ADZ.cjs');
7
+ require('../../chunk-L5ND2FJJ.cjs');
8
8
  require('../../chunk-5BLDMQED.cjs');
9
9
 
10
10
  // src/worker/expo/taskQueue.ts
@@ -121,19 +121,19 @@ var AsyncStorageTaskQueue = class {
121
121
 
122
122
  Object.defineProperty(exports, "CONTRACT_POLL_TASK_TYPE", {
123
123
  enumerable: true,
124
- get: function () { return chunk6TQJOD72_cjs.CONTRACT_POLL_TASK_TYPE; }
124
+ get: function () { return chunkEA3IWZ4W_cjs.CONTRACT_POLL_TASK_TYPE; }
125
125
  });
126
126
  Object.defineProperty(exports, "contractPollProcessor", {
127
127
  enumerable: true,
128
- get: function () { return chunk6TQJOD72_cjs.contractPollProcessor; }
128
+ get: function () { return chunkEA3IWZ4W_cjs.contractPollProcessor; }
129
129
  });
130
130
  Object.defineProperty(exports, "createTaskDependencies", {
131
131
  enumerable: true,
132
- get: function () { return chunk6TQJOD72_cjs.createTaskDependencies; }
132
+ get: function () { return chunkEA3IWZ4W_cjs.createTaskDependencies; }
133
133
  });
134
134
  Object.defineProperty(exports, "runTasks", {
135
135
  enumerable: true,
136
- get: function () { return chunk6TQJOD72_cjs.runTasks; }
136
+ get: function () { return chunkEA3IWZ4W_cjs.runTasks; }
137
137
  });
138
138
  exports.AsyncStorageTaskQueue = AsyncStorageTaskQueue;
139
139
  exports.InMemoryTaskQueue = InMemoryTaskQueue;
@@ -1,7 +1,7 @@
1
- import { T as TaskProcessor } from '../../taskRunner-nNecmQ2C.cjs';
2
- export { C as CreateTaskDependenciesOptions, I as InMemoryTaskQueue, b as TaskDependencies, c as TaskItem, a as TaskQueue, d as TaskResult, e as createTaskDependencies, r as runTasks } from '../../taskRunner-nNecmQ2C.cjs';
3
- export { a as AsyncStorageLike, A as AsyncStorageTaskQueue } from '../../asyncStorageTaskQueue-CmBYVlxw.cjs';
4
- import '../../ark-C9ognsOV.cjs';
1
+ import { T as TaskProcessor } from '../../taskRunner-RYihSj9E.cjs';
2
+ export { C as CreateTaskDependenciesOptions, I as InMemoryTaskQueue, b as TaskDependencies, c as TaskItem, a as TaskQueue, d as TaskResult, e as createTaskDependencies, r as runTasks } from '../../taskRunner-RYihSj9E.cjs';
3
+ export { a as AsyncStorageLike, A as AsyncStorageTaskQueue } from '../../asyncStorageTaskQueue-CwknfM_j.cjs';
4
+ import '../../ark-CoJgwTi_.cjs';
5
5
  import '@scure/btc-signer/transaction.js';
6
6
  import '@scure/btc-signer/utils.js';
7
7
  import '@scure/btc-signer/psbt.js';
@@ -1,7 +1,7 @@
1
- import { T as TaskProcessor } from '../../taskRunner-B48-V-Pb.js';
2
- export { C as CreateTaskDependenciesOptions, I as InMemoryTaskQueue, b as TaskDependencies, c as TaskItem, a as TaskQueue, d as TaskResult, e as createTaskDependencies, r as runTasks } from '../../taskRunner-B48-V-Pb.js';
3
- export { a as AsyncStorageLike, A as AsyncStorageTaskQueue } from '../../asyncStorageTaskQueue-BAKZ5cS5.js';
4
- import '../../ark-C9ognsOV.js';
1
+ import { T as TaskProcessor } from '../../taskRunner-Df8YQpn1.js';
2
+ export { C as CreateTaskDependenciesOptions, I as InMemoryTaskQueue, b as TaskDependencies, c as TaskItem, a as TaskQueue, d as TaskResult, e as createTaskDependencies, r as runTasks } from '../../taskRunner-Df8YQpn1.js';
3
+ export { a as AsyncStorageLike, A as AsyncStorageTaskQueue } from '../../asyncStorageTaskQueue-D2Zl7yAB.js';
4
+ import '../../ark-CoJgwTi_.js';
5
5
  import '@scure/btc-signer/transaction.js';
6
6
  import '@scure/btc-signer/utils.js';
7
7
  import '@scure/btc-signer/psbt.js';
@@ -1,8 +1,8 @@
1
- export { CONTRACT_POLL_TASK_TYPE, contractPollProcessor, createTaskDependencies, runTasks } from '../../chunk-R2SVAM5Q.js';
2
- import '../../chunk-P6VBP3CT.js';
3
- import '../../chunk-CWJ7ZCP7.js';
4
- import '../../chunk-QKC2T54O.js';
5
- import '../../chunk-FWG4TSPN.js';
1
+ export { CONTRACT_POLL_TASK_TYPE, contractPollProcessor, createTaskDependencies, runTasks } from '../../chunk-4AIHKC65.js';
2
+ import '../../chunk-SV4PCGKM.js';
3
+ import '../../chunk-GM6JRQP5.js';
4
+ import '../../chunk-XN3554FT.js';
5
+ import '../../chunk-C7TXXTMS.js';
6
6
  import '../../chunk-NSBPE2FW.js';
7
7
 
8
8
  // src/worker/expo/taskQueue.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arkade-os/sdk",
3
- "version": "0.4.46",
3
+ "version": "0.4.48-rc.0",
4
4
  "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",