@originals/sdk 1.4.3 → 1.4.5

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 (222) hide show
  1. package/dist/adapters/FeeOracleMock.d.ts +6 -0
  2. package/dist/adapters/FeeOracleMock.js +8 -0
  3. package/dist/adapters/index.d.ts +4 -0
  4. package/dist/adapters/index.js +4 -0
  5. package/dist/adapters/providers/OrdHttpProvider.d.ts +56 -0
  6. package/dist/adapters/providers/OrdHttpProvider.js +110 -0
  7. package/dist/adapters/providers/OrdMockProvider.d.ts +70 -0
  8. package/dist/adapters/providers/OrdMockProvider.js +75 -0
  9. package/dist/adapters/types.d.ts +71 -0
  10. package/dist/adapters/types.js +1 -0
  11. package/dist/bitcoin/BitcoinManager.d.ts +15 -0
  12. package/dist/bitcoin/BitcoinManager.js +262 -0
  13. package/dist/bitcoin/BroadcastClient.d.ts +30 -0
  14. package/dist/bitcoin/BroadcastClient.js +35 -0
  15. package/dist/bitcoin/OrdinalsClient.d.ts +21 -0
  16. package/dist/bitcoin/OrdinalsClient.js +105 -0
  17. package/dist/bitcoin/PSBTBuilder.d.ts +24 -0
  18. package/dist/bitcoin/PSBTBuilder.js +80 -0
  19. package/dist/bitcoin/fee-calculation.d.ts +14 -0
  20. package/dist/bitcoin/fee-calculation.js +31 -0
  21. package/dist/bitcoin/providers/OrdNodeProvider.d.ts +38 -0
  22. package/dist/bitcoin/providers/OrdNodeProvider.js +67 -0
  23. package/dist/bitcoin/providers/OrdinalsProvider.d.ts +33 -0
  24. package/dist/bitcoin/providers/OrdinalsProvider.js +50 -0
  25. package/dist/bitcoin/providers/types.d.ts +63 -0
  26. package/dist/bitcoin/providers/types.js +1 -0
  27. package/dist/bitcoin/transactions/commit.d.ts +89 -0
  28. package/dist/bitcoin/transactions/commit.js +311 -0
  29. package/dist/bitcoin/transactions/index.d.ts +7 -0
  30. package/dist/bitcoin/transactions/index.js +8 -0
  31. package/dist/bitcoin/transfer.d.ts +9 -0
  32. package/dist/bitcoin/transfer.js +26 -0
  33. package/dist/bitcoin/utxo-selection.d.ts +78 -0
  34. package/dist/bitcoin/utxo-selection.js +237 -0
  35. package/dist/bitcoin/utxo.d.ts +26 -0
  36. package/dist/bitcoin/utxo.js +78 -0
  37. package/dist/contexts/credentials-v1.json +195 -0
  38. package/dist/contexts/credentials-v2-examples.json +5 -0
  39. package/dist/contexts/credentials-v2.json +301 -0
  40. package/dist/contexts/credentials.json +195 -0
  41. package/dist/contexts/data-integrity-v2.json +81 -0
  42. package/dist/contexts/dids.json +57 -0
  43. package/dist/contexts/ed255192020.json +93 -0
  44. package/dist/contexts/ordinals-plus.json +23 -0
  45. package/dist/contexts/originals.json +22 -0
  46. package/dist/core/OriginalsSDK.d.ts +158 -0
  47. package/dist/core/OriginalsSDK.js +274 -0
  48. package/dist/crypto/Multikey.d.ts +30 -0
  49. package/dist/crypto/Multikey.js +149 -0
  50. package/dist/crypto/Signer.d.ts +21 -0
  51. package/dist/crypto/Signer.js +196 -0
  52. package/dist/crypto/noble-init.d.ts +18 -0
  53. package/dist/crypto/noble-init.js +106 -0
  54. package/dist/did/BtcoDidResolver.d.ts +57 -0
  55. package/dist/did/BtcoDidResolver.js +166 -0
  56. package/dist/did/DIDManager.d.ts +101 -0
  57. package/dist/did/DIDManager.js +493 -0
  58. package/dist/did/Ed25519Verifier.d.ts +30 -0
  59. package/dist/did/Ed25519Verifier.js +59 -0
  60. package/dist/did/KeyManager.d.ts +17 -0
  61. package/dist/did/KeyManager.js +207 -0
  62. package/dist/did/WebVHManager.d.ts +100 -0
  63. package/dist/did/WebVHManager.js +312 -0
  64. package/dist/did/createBtcoDidDocument.d.ts +10 -0
  65. package/dist/did/createBtcoDidDocument.js +42 -0
  66. package/dist/did/providers/OrdinalsClientProviderAdapter.d.ts +23 -0
  67. package/dist/did/providers/OrdinalsClientProviderAdapter.js +51 -0
  68. package/dist/events/EventEmitter.d.ts +115 -0
  69. package/dist/events/EventEmitter.js +198 -0
  70. package/dist/events/index.d.ts +7 -0
  71. package/dist/events/index.js +6 -0
  72. package/dist/events/types.d.ts +286 -0
  73. package/dist/events/types.js +9 -0
  74. package/dist/examples/basic-usage.d.ts +3 -0
  75. package/dist/examples/basic-usage.js +62 -0
  76. package/dist/examples/create-module-original.d.ts +32 -0
  77. package/dist/examples/create-module-original.js +376 -0
  78. package/dist/examples/full-lifecycle-flow.d.ts +56 -0
  79. package/dist/examples/full-lifecycle-flow.js +419 -0
  80. package/dist/examples/run.d.ts +12 -0
  81. package/dist/examples/run.js +51 -0
  82. package/dist/index.d.ts +43 -0
  83. package/dist/index.js +52 -0
  84. package/dist/kinds/KindRegistry.d.ts +76 -0
  85. package/dist/kinds/KindRegistry.js +216 -0
  86. package/dist/kinds/index.d.ts +33 -0
  87. package/dist/kinds/index.js +36 -0
  88. package/dist/kinds/types.d.ts +363 -0
  89. package/dist/kinds/types.js +25 -0
  90. package/dist/kinds/validators/AgentValidator.d.ts +14 -0
  91. package/dist/kinds/validators/AgentValidator.js +155 -0
  92. package/dist/kinds/validators/AppValidator.d.ts +14 -0
  93. package/dist/kinds/validators/AppValidator.js +135 -0
  94. package/dist/kinds/validators/DatasetValidator.d.ts +14 -0
  95. package/dist/kinds/validators/DatasetValidator.js +148 -0
  96. package/dist/kinds/validators/DocumentValidator.d.ts +14 -0
  97. package/dist/kinds/validators/DocumentValidator.js +180 -0
  98. package/dist/kinds/validators/MediaValidator.d.ts +14 -0
  99. package/dist/kinds/validators/MediaValidator.js +172 -0
  100. package/dist/kinds/validators/ModuleValidator.d.ts +14 -0
  101. package/dist/kinds/validators/ModuleValidator.js +140 -0
  102. package/dist/kinds/validators/base.d.ts +96 -0
  103. package/dist/kinds/validators/base.js +218 -0
  104. package/dist/kinds/validators/index.d.ts +10 -0
  105. package/dist/kinds/validators/index.js +10 -0
  106. package/dist/lifecycle/BatchOperations.d.ts +147 -0
  107. package/dist/lifecycle/BatchOperations.js +251 -0
  108. package/dist/lifecycle/LifecycleManager.d.ts +362 -0
  109. package/dist/lifecycle/LifecycleManager.js +1692 -0
  110. package/dist/lifecycle/OriginalsAsset.d.ts +164 -0
  111. package/dist/lifecycle/OriginalsAsset.js +380 -0
  112. package/dist/lifecycle/ProvenanceQuery.d.ts +126 -0
  113. package/dist/lifecycle/ProvenanceQuery.js +220 -0
  114. package/dist/lifecycle/ResourceVersioning.d.ts +73 -0
  115. package/dist/lifecycle/ResourceVersioning.js +127 -0
  116. package/dist/migration/MigrationManager.d.ts +86 -0
  117. package/dist/migration/MigrationManager.js +412 -0
  118. package/dist/migration/audit/AuditLogger.d.ts +51 -0
  119. package/dist/migration/audit/AuditLogger.js +156 -0
  120. package/dist/migration/checkpoint/CheckpointManager.d.ts +31 -0
  121. package/dist/migration/checkpoint/CheckpointManager.js +96 -0
  122. package/dist/migration/checkpoint/CheckpointStorage.d.ts +26 -0
  123. package/dist/migration/checkpoint/CheckpointStorage.js +89 -0
  124. package/dist/migration/index.d.ts +22 -0
  125. package/dist/migration/index.js +27 -0
  126. package/dist/migration/operations/BaseMigration.d.ts +48 -0
  127. package/dist/migration/operations/BaseMigration.js +83 -0
  128. package/dist/migration/operations/PeerToBtcoMigration.d.ts +25 -0
  129. package/dist/migration/operations/PeerToBtcoMigration.js +67 -0
  130. package/dist/migration/operations/PeerToWebvhMigration.d.ts +19 -0
  131. package/dist/migration/operations/PeerToWebvhMigration.js +46 -0
  132. package/dist/migration/operations/WebvhToBtcoMigration.d.ts +25 -0
  133. package/dist/migration/operations/WebvhToBtcoMigration.js +67 -0
  134. package/dist/migration/rollback/RollbackManager.d.ts +29 -0
  135. package/dist/migration/rollback/RollbackManager.js +146 -0
  136. package/dist/migration/state/StateMachine.d.ts +25 -0
  137. package/dist/migration/state/StateMachine.js +76 -0
  138. package/dist/migration/state/StateTracker.d.ts +36 -0
  139. package/dist/migration/state/StateTracker.js +123 -0
  140. package/dist/migration/types.d.ts +306 -0
  141. package/dist/migration/types.js +33 -0
  142. package/dist/migration/validation/BitcoinValidator.d.ts +13 -0
  143. package/dist/migration/validation/BitcoinValidator.js +83 -0
  144. package/dist/migration/validation/CredentialValidator.d.ts +13 -0
  145. package/dist/migration/validation/CredentialValidator.js +46 -0
  146. package/dist/migration/validation/DIDCompatibilityValidator.d.ts +16 -0
  147. package/dist/migration/validation/DIDCompatibilityValidator.js +127 -0
  148. package/dist/migration/validation/LifecycleValidator.d.ts +10 -0
  149. package/dist/migration/validation/LifecycleValidator.js +52 -0
  150. package/dist/migration/validation/StorageValidator.d.ts +10 -0
  151. package/dist/migration/validation/StorageValidator.js +65 -0
  152. package/dist/migration/validation/ValidationPipeline.d.ts +29 -0
  153. package/dist/migration/validation/ValidationPipeline.js +180 -0
  154. package/dist/resources/ResourceManager.d.ts +231 -0
  155. package/dist/resources/ResourceManager.js +573 -0
  156. package/dist/resources/index.d.ts +11 -0
  157. package/dist/resources/index.js +10 -0
  158. package/dist/resources/types.d.ts +93 -0
  159. package/dist/resources/types.js +80 -0
  160. package/dist/storage/LocalStorageAdapter.d.ts +11 -0
  161. package/dist/storage/LocalStorageAdapter.js +53 -0
  162. package/dist/storage/MemoryStorageAdapter.d.ts +6 -0
  163. package/dist/storage/MemoryStorageAdapter.js +21 -0
  164. package/dist/storage/StorageAdapter.d.ts +16 -0
  165. package/dist/storage/StorageAdapter.js +1 -0
  166. package/dist/storage/index.d.ts +2 -0
  167. package/dist/storage/index.js +2 -0
  168. package/dist/types/bitcoin.d.ts +84 -0
  169. package/dist/types/bitcoin.js +1 -0
  170. package/dist/types/common.d.ts +82 -0
  171. package/dist/types/common.js +1 -0
  172. package/dist/types/credentials.d.ts +75 -0
  173. package/dist/types/credentials.js +1 -0
  174. package/dist/types/did.d.ts +26 -0
  175. package/dist/types/did.js +1 -0
  176. package/dist/types/index.d.ts +5 -0
  177. package/dist/types/index.js +5 -0
  178. package/dist/types/network.d.ts +78 -0
  179. package/dist/types/network.js +145 -0
  180. package/dist/utils/EventLogger.d.ts +71 -0
  181. package/dist/utils/EventLogger.js +232 -0
  182. package/dist/utils/Logger.d.ts +106 -0
  183. package/dist/utils/Logger.js +257 -0
  184. package/dist/utils/MetricsCollector.d.ts +110 -0
  185. package/dist/utils/MetricsCollector.js +264 -0
  186. package/dist/utils/bitcoin-address.d.ts +38 -0
  187. package/dist/utils/bitcoin-address.js +113 -0
  188. package/dist/utils/cbor.d.ts +2 -0
  189. package/dist/utils/cbor.js +9 -0
  190. package/dist/utils/encoding.d.ts +37 -0
  191. package/dist/utils/encoding.js +120 -0
  192. package/dist/utils/hash.d.ts +1 -0
  193. package/dist/utils/hash.js +5 -0
  194. package/dist/utils/retry.d.ts +10 -0
  195. package/dist/utils/retry.js +35 -0
  196. package/dist/utils/satoshi-validation.d.ts +60 -0
  197. package/dist/utils/satoshi-validation.js +156 -0
  198. package/dist/utils/serialization.d.ts +14 -0
  199. package/dist/utils/serialization.js +76 -0
  200. package/dist/utils/telemetry.d.ts +17 -0
  201. package/dist/utils/telemetry.js +24 -0
  202. package/dist/utils/validation.d.ts +5 -0
  203. package/dist/utils/validation.js +98 -0
  204. package/dist/vc/CredentialManager.d.ts +329 -0
  205. package/dist/vc/CredentialManager.js +615 -0
  206. package/dist/vc/Issuer.d.ts +27 -0
  207. package/dist/vc/Issuer.js +70 -0
  208. package/dist/vc/Verifier.d.ts +16 -0
  209. package/dist/vc/Verifier.js +50 -0
  210. package/dist/vc/cryptosuites/bbs.d.ts +44 -0
  211. package/dist/vc/cryptosuites/bbs.js +213 -0
  212. package/dist/vc/cryptosuites/bbsSimple.d.ts +9 -0
  213. package/dist/vc/cryptosuites/bbsSimple.js +12 -0
  214. package/dist/vc/cryptosuites/eddsa.d.ts +30 -0
  215. package/dist/vc/cryptosuites/eddsa.js +81 -0
  216. package/dist/vc/documentLoader.d.ts +16 -0
  217. package/dist/vc/documentLoader.js +59 -0
  218. package/dist/vc/proofs/data-integrity.d.ts +21 -0
  219. package/dist/vc/proofs/data-integrity.js +15 -0
  220. package/dist/vc/utils/jsonld.d.ts +2 -0
  221. package/dist/vc/utils/jsonld.js +15 -0
  222. package/package.json +2 -1
@@ -0,0 +1,78 @@
1
+ /**
2
+ * UTXO Selection for Ordinals Transactions
3
+ *
4
+ * This module implements functions for selecting UTXOs for ordinals transactions.
5
+ * It provides a simple coin selection algorithm optimized for ordinals inscriptions.
6
+ *
7
+ * Ported from legacy ordinalsplus transaction infrastructure.
8
+ */
9
+ import { Utxo, ResourceUtxo, ResourceUtxoSelectionOptions, ResourceUtxoSelectionResult } from '../types/bitcoin.js';
10
+ /**
11
+ * Estimates transaction size in vbytes based on input and output counts
12
+ * This is a simplified calculation, and actual size may vary based on script types
13
+ *
14
+ * @param inputCount Number of inputs in the transaction
15
+ * @param outputCount Number of outputs in the transaction
16
+ * @returns Estimated transaction size in vbytes
17
+ */
18
+ export declare function estimateTransactionSize(inputCount: number, outputCount: number): number;
19
+ /**
20
+ * Tags UTXOs as resource-containing or regular based on provided data
21
+ *
22
+ * @param utxos List of UTXOs to tag
23
+ * @param resourceData Optional data about which UTXOs contain resources
24
+ * @returns Tagged ResourceUtxo[] list with hasResource flags set appropriately
25
+ */
26
+ export declare function tagResourceUtxos(utxos: ResourceUtxo[], resourceData?: {
27
+ [utxoId: string]: boolean;
28
+ }): ResourceUtxo[];
29
+ /**
30
+ * Options for simple UTXO selection
31
+ */
32
+ export interface SimpleUtxoSelectionOptions {
33
+ /** Target amount to reach (in satoshis) */
34
+ targetAmount: number;
35
+ /** Optional maximum amount of UTXOs to use */
36
+ maxNumUtxos?: number;
37
+ /** Optional preference for UTXO selection strategy */
38
+ strategy?: 'minimize_change' | 'minimize_inputs' | 'optimize_size';
39
+ }
40
+ /**
41
+ * Result of simple UTXO selection
42
+ */
43
+ export interface SimpleUtxoSelectionResult {
44
+ /** Selected UTXOs for the transaction */
45
+ selectedUtxos: Utxo[];
46
+ /** Total value of selected UTXOs */
47
+ totalInputValue: number;
48
+ /** Estimated change amount (if any) */
49
+ changeAmount: number;
50
+ }
51
+ /**
52
+ * Selects UTXOs to cover a target amount using a simplified approach.
53
+ * This version is used specifically for commit transactions where we
54
+ * don't need the more complex resource-aware selection.
55
+ *
56
+ * @param utxos - Available UTXOs
57
+ * @param options - Target amount or detailed options
58
+ * @returns Selected UTXOs and related information
59
+ */
60
+ export declare function selectUtxos(utxos: Utxo[], options: number | SimpleUtxoSelectionOptions): SimpleUtxoSelectionResult;
61
+ /**
62
+ * Selects UTXOs for a transaction, excluding UTXOs with resources unless explicitly allowed
63
+ *
64
+ * @param availableUtxos List of available UTXOs to select from
65
+ * @param options Configuration options for the selection process
66
+ * @returns Selection result with chosen UTXOs and fee information
67
+ * @throws Error if insufficient funds or if all available UTXOs contain resources
68
+ */
69
+ export declare function selectResourceUtxos(availableUtxos: ResourceUtxo[], options: ResourceUtxoSelectionOptions): ResourceUtxoSelectionResult;
70
+ /**
71
+ * Convenience function to select UTXOs for a payment, explicitly avoiding resource UTXOs
72
+ *
73
+ * @param availableUtxos List of available UTXOs
74
+ * @param requiredAmount Amount needed for the payment in satoshis
75
+ * @param feeRate Fee rate in satoshis per vbyte
76
+ * @returns Selection result with UTXOs, fee and change information
77
+ */
78
+ export declare function selectUtxosForPayment(availableUtxos: ResourceUtxo[], requiredAmount: number, feeRate: number): ResourceUtxoSelectionResult;
@@ -0,0 +1,237 @@
1
+ /**
2
+ * UTXO Selection for Ordinals Transactions
3
+ *
4
+ * This module implements functions for selecting UTXOs for ordinals transactions.
5
+ * It provides a simple coin selection algorithm optimized for ordinals inscriptions.
6
+ *
7
+ * Ported from legacy ordinalsplus transaction infrastructure.
8
+ */
9
+ import { DUST_LIMIT_SATS } from '../types/bitcoin.js';
10
+ import { calculateFee } from './fee-calculation.js';
11
+ // Minimum dust limit for Bitcoin outputs (546 satoshis)
12
+ const MIN_DUST_LIMIT = DUST_LIMIT_SATS;
13
+ /**
14
+ * Estimates transaction size in vbytes based on input and output counts
15
+ * This is a simplified calculation, and actual size may vary based on script types
16
+ *
17
+ * @param inputCount Number of inputs in the transaction
18
+ * @param outputCount Number of outputs in the transaction
19
+ * @returns Estimated transaction size in vbytes
20
+ */
21
+ export function estimateTransactionSize(inputCount, outputCount) {
22
+ // Rough estimation based on segwit transaction format
23
+ // Transaction overhead: ~10 vbytes
24
+ // Each input: ~68 vbytes (P2WPKH)
25
+ // Each output: ~31 vbytes
26
+ return 10 + (inputCount * 68) + (outputCount * 31);
27
+ }
28
+ /**
29
+ * Tags UTXOs as resource-containing or regular based on provided data
30
+ *
31
+ * @param utxos List of UTXOs to tag
32
+ * @param resourceData Optional data about which UTXOs contain resources
33
+ * @returns Tagged ResourceUtxo[] list with hasResource flags set appropriately
34
+ */
35
+ export function tagResourceUtxos(utxos, resourceData) {
36
+ return utxos.map(utxo => {
37
+ const utxoId = `${utxo.txid}:${utxo.vout}`;
38
+ const hasResource = resourceData ? !!resourceData[utxoId] : utxo.hasResource || false;
39
+ return {
40
+ ...utxo,
41
+ hasResource
42
+ };
43
+ });
44
+ }
45
+ /**
46
+ * Selects UTXOs to cover a target amount using a simplified approach.
47
+ * This version is used specifically for commit transactions where we
48
+ * don't need the more complex resource-aware selection.
49
+ *
50
+ * @param utxos - Available UTXOs
51
+ * @param options - Target amount or detailed options
52
+ * @returns Selected UTXOs and related information
53
+ */
54
+ export function selectUtxos(utxos, options) {
55
+ // Handle simple number input
56
+ const targetAmount = typeof options === 'number'
57
+ ? options
58
+ : options.targetAmount;
59
+ const maxNumUtxos = typeof options === 'number'
60
+ ? undefined
61
+ : options.maxNumUtxos;
62
+ const strategy = typeof options === 'number'
63
+ ? 'minimize_inputs'
64
+ : options.strategy || 'minimize_inputs';
65
+ // Validate inputs
66
+ if (!utxos || utxos.length === 0) {
67
+ throw new Error('No UTXOs provided for selection.');
68
+ }
69
+ if (targetAmount <= 0) {
70
+ throw new Error(`Invalid target amount: ${targetAmount}`);
71
+ }
72
+ // Sort UTXOs based on selected strategy
73
+ let sortedUtxos = [...utxos];
74
+ if (strategy === 'minimize_inputs') {
75
+ // Sort by value descending to use fewest inputs
76
+ sortedUtxos.sort((a, b) => b.value - a.value);
77
+ }
78
+ else if (strategy === 'minimize_change') {
79
+ // Sort by value ascending to minimize change
80
+ sortedUtxos.sort((a, b) => a.value - b.value);
81
+ }
82
+ else if (strategy === 'optimize_size') {
83
+ // Sort by value/size ratio (value density) for optimal fee efficiency
84
+ // For now, just sort by value as a reasonable approximation
85
+ sortedUtxos.sort((a, b) => b.value - a.value);
86
+ }
87
+ const selected = [];
88
+ let totalValue = 0;
89
+ // Add UTXOs until we reach the target amount
90
+ for (const utxo of sortedUtxos) {
91
+ // Skip invalid UTXOs
92
+ if (!utxo.txid || utxo.vout === undefined || !utxo.value) {
93
+ console.warn(`Skipping invalid UTXO: ${utxo.txid}:${utxo.vout}`);
94
+ continue;
95
+ }
96
+ selected.push(utxo);
97
+ totalValue += utxo.value;
98
+ // Check if we've reached the target
99
+ if (totalValue >= targetAmount) {
100
+ break;
101
+ }
102
+ // Check if we've reached the maximum allowed number of UTXOs
103
+ if (maxNumUtxos && selected.length >= maxNumUtxos) {
104
+ break;
105
+ }
106
+ }
107
+ // Check if we have enough funds
108
+ if (totalValue < targetAmount) {
109
+ throw new Error(`Insufficient funds. Required: ${targetAmount}, Available: ${totalValue} from ${utxos.length} UTXOs.`);
110
+ }
111
+ // Calculate change amount
112
+ const changeAmount = totalValue - targetAmount;
113
+ return {
114
+ selectedUtxos: selected,
115
+ totalInputValue: totalValue,
116
+ changeAmount
117
+ };
118
+ }
119
+ /**
120
+ * Selects UTXOs for a transaction, excluding UTXOs with resources unless explicitly allowed
121
+ *
122
+ * @param availableUtxos List of available UTXOs to select from
123
+ * @param options Configuration options for the selection process
124
+ * @returns Selection result with chosen UTXOs and fee information
125
+ * @throws Error if insufficient funds or if all available UTXOs contain resources
126
+ */
127
+ export function selectResourceUtxos(availableUtxos, options) {
128
+ const { requiredAmount, feeRate, allowResourceUtxos = false, preferOlder = false, preferCloserAmount = false, avoidUtxoIds = [] } = options;
129
+ // Convert requiredAmount to bigint for compatibility with fee calculations
130
+ const requiredAmountBigInt = BigInt(requiredAmount);
131
+ // Filter out UTXOs to avoid and those with resources if not allowed
132
+ let eligibleUtxos = availableUtxos.filter(utxo => {
133
+ const utxoId = `${utxo.txid}:${utxo.vout}`;
134
+ const shouldAvoid = avoidUtxoIds.includes(utxoId);
135
+ const containsResource = utxo.hasResource === true;
136
+ // Skip this UTXO if it's in the avoid list
137
+ if (shouldAvoid)
138
+ return false;
139
+ // Skip this UTXO if it contains a resource and we're not allowed to use resource UTXOs
140
+ if (containsResource && !allowResourceUtxos)
141
+ return false;
142
+ return true;
143
+ });
144
+ if (eligibleUtxos.length === 0) {
145
+ // Special error message if we have UTXOs but they all contain resources
146
+ if (availableUtxos.length > 0 && availableUtxos.every(u => u.hasResource)) {
147
+ throw new Error('All available UTXOs contain resources and cannot be used for fees/payments. Please add non-resource UTXOs to your wallet.');
148
+ }
149
+ throw new Error('No eligible UTXOs available for selection');
150
+ }
151
+ // Apply sorting strategy
152
+ if (preferCloserAmount) {
153
+ // Sort by closest to required amount (but still above it)
154
+ eligibleUtxos.sort((a, b) => {
155
+ const aDiff = a.value - requiredAmount;
156
+ const bDiff = b.value - requiredAmount;
157
+ // Prioritize UTXOs that cover the amount
158
+ if (aDiff >= 0 && bDiff < 0)
159
+ return -1;
160
+ if (aDiff < 0 && bDiff >= 0)
161
+ return 1;
162
+ // If both cover or both don't cover, prefer the one closer to required amount
163
+ return Math.abs(aDiff) - Math.abs(bDiff);
164
+ });
165
+ }
166
+ else if (preferOlder) {
167
+ // Prefer older UTXOs (by txid as a proxy for age - not perfect but simple)
168
+ eligibleUtxos.sort((a, b) => a.txid.localeCompare(b.txid));
169
+ }
170
+ else {
171
+ // Default: sort by value descending (largest first)
172
+ eligibleUtxos.sort((a, b) => b.value - a.value);
173
+ }
174
+ // Initial fee estimation (1 input, 2 outputs - payment and change)
175
+ let estimatedVbytes = estimateTransactionSize(1, 2);
176
+ let estimatedFee = calculateFee(estimatedVbytes, feeRate);
177
+ // Target amount including estimated fee
178
+ let targetAmount = requiredAmountBigInt + estimatedFee;
179
+ // Select UTXOs
180
+ const selectedUtxos = [];
181
+ let totalSelectedValue = 0n;
182
+ // First pass: try to find a single UTXO that covers the amount
183
+ const singleUtxo = eligibleUtxos.find(utxo => BigInt(utxo.value) >= targetAmount);
184
+ if (singleUtxo) {
185
+ selectedUtxos.push(singleUtxo);
186
+ totalSelectedValue = BigInt(singleUtxo.value);
187
+ }
188
+ else {
189
+ // Second pass: accumulate UTXOs until we reach the target amount
190
+ for (const utxo of eligibleUtxos) {
191
+ selectedUtxos.push(utxo);
192
+ totalSelectedValue += BigInt(utxo.value);
193
+ // Recalculate fee as we add more inputs
194
+ estimatedVbytes = estimateTransactionSize(selectedUtxos.length, 2);
195
+ estimatedFee = calculateFee(estimatedVbytes, feeRate);
196
+ targetAmount = requiredAmountBigInt + estimatedFee;
197
+ if (totalSelectedValue >= targetAmount) {
198
+ break;
199
+ }
200
+ }
201
+ }
202
+ // Final fee calculation based on actual number of inputs
203
+ estimatedVbytes = estimateTransactionSize(selectedUtxos.length, 2);
204
+ estimatedFee = calculateFee(estimatedVbytes, feeRate);
205
+ // Check if we have enough funds
206
+ if (totalSelectedValue < requiredAmountBigInt + estimatedFee) {
207
+ throw new Error(`Insufficient funds. Required: ${requiredAmountBigInt + estimatedFee}, Available: ${totalSelectedValue}`);
208
+ }
209
+ // Calculate change
210
+ let changeAmount = totalSelectedValue - requiredAmountBigInt - estimatedFee;
211
+ // If change is less than dust limit, add it to the fee
212
+ if (changeAmount > 0n && changeAmount < BigInt(MIN_DUST_LIMIT)) {
213
+ estimatedFee += changeAmount;
214
+ changeAmount = 0n;
215
+ }
216
+ return {
217
+ selectedUtxos,
218
+ totalSelectedValue: Number(totalSelectedValue),
219
+ estimatedFee: Number(estimatedFee),
220
+ changeAmount: Number(changeAmount)
221
+ };
222
+ }
223
+ /**
224
+ * Convenience function to select UTXOs for a payment, explicitly avoiding resource UTXOs
225
+ *
226
+ * @param availableUtxos List of available UTXOs
227
+ * @param requiredAmount Amount needed for the payment in satoshis
228
+ * @param feeRate Fee rate in satoshis per vbyte
229
+ * @returns Selection result with UTXOs, fee and change information
230
+ */
231
+ export function selectUtxosForPayment(availableUtxos, requiredAmount, feeRate) {
232
+ return selectResourceUtxos(availableUtxos, {
233
+ requiredAmount,
234
+ feeRate,
235
+ allowResourceUtxos: false // Never use resource UTXOs for payments
236
+ });
237
+ }
@@ -0,0 +1,26 @@
1
+ import { Utxo } from '../types';
2
+ export interface FeeEstimateOptions {
3
+ bytesPerInput?: number;
4
+ bytesPerOutput?: number;
5
+ baseTxBytes?: number;
6
+ }
7
+ export interface SelectionOptions {
8
+ feeRateSatsPerVb: number;
9
+ targetAmountSats: number;
10
+ allowLocked?: boolean;
11
+ forbidInscriptionBearingInputs?: boolean;
12
+ changeAddress?: string;
13
+ feeEstimate?: FeeEstimateOptions;
14
+ }
15
+ export interface SelectionResult {
16
+ selected: Utxo[];
17
+ feeSats: number;
18
+ changeSats: number;
19
+ }
20
+ export declare const DEFAULT_FEE_ESTIMATE: Required<FeeEstimateOptions>;
21
+ export declare function estimateFeeSats(numInputs: number, numOutputs: number, feeRateSatsPerVb: number, feeEstimate?: FeeEstimateOptions): number;
22
+ export declare class UtxoSelectionError extends Error {
23
+ code: 'INSUFFICIENT_FUNDS' | 'TOO_LOW_FEE' | 'DUST_OUTPUT' | 'CONFLICTING_LOCKS' | 'SAT_SAFETY';
24
+ constructor(code: UtxoSelectionError['code'], message?: string);
25
+ }
26
+ export declare function selectUtxos(utxos: Utxo[], options: SelectionOptions): SelectionResult;
@@ -0,0 +1,78 @@
1
+ import { DUST_LIMIT_SATS } from '../types';
2
+ export const DEFAULT_FEE_ESTIMATE = {
3
+ bytesPerInput: 148,
4
+ bytesPerOutput: 34,
5
+ baseTxBytes: 10
6
+ };
7
+ export function estimateFeeSats(numInputs, numOutputs, feeRateSatsPerVb, feeEstimate = {}) {
8
+ const est = { ...DEFAULT_FEE_ESTIMATE, ...feeEstimate };
9
+ const bytes = est.baseTxBytes + numInputs * est.bytesPerInput + numOutputs * est.bytesPerOutput;
10
+ return Math.ceil(bytes * feeRateSatsPerVb);
11
+ }
12
+ export class UtxoSelectionError extends Error {
13
+ constructor(code, message) {
14
+ super(message || code);
15
+ this.code = code;
16
+ }
17
+ }
18
+ export function selectUtxos(utxos, options) {
19
+ const { feeRateSatsPerVb, targetAmountSats, allowLocked, forbidInscriptionBearingInputs, feeEstimate } = options;
20
+ if (feeRateSatsPerVb <= 0) {
21
+ const err = new UtxoSelectionError('TOO_LOW_FEE', 'TOO_LOW_FEE');
22
+ throw err;
23
+ }
24
+ if (targetAmountSats < DUST_LIMIT_SATS) {
25
+ const err = new UtxoSelectionError('DUST_OUTPUT', 'DUST_OUTPUT');
26
+ throw err;
27
+ }
28
+ // Filter UTXOs based on policy
29
+ let candidateUtxos = utxos.slice().filter(u => typeof u.value === 'number' && u.value > 0);
30
+ const hasLocked = candidateUtxos.some(u => u.locked);
31
+ if (hasLocked && !allowLocked) {
32
+ // If excluding locked leaves insufficient funds, surface a specific error later; but first mark conflict
33
+ // We'll check after filtering
34
+ }
35
+ if (!allowLocked) {
36
+ candidateUtxos = candidateUtxos.filter(u => !u.locked);
37
+ }
38
+ if (forbidInscriptionBearingInputs) {
39
+ candidateUtxos = candidateUtxos.filter(u => !u.inscriptions || u.inscriptions.length === 0);
40
+ }
41
+ // Greedy accumulate until amount + fee is satisfied. Start with 2 outputs (recipient + change), adjust if change is dust.
42
+ const selected = [];
43
+ let accumulated = 0;
44
+ // Sort largest first to reduce change outputs and input count
45
+ candidateUtxos.sort((a, b) => b.value - a.value);
46
+ // We'll iteratively include inputs and recompute fee until covered
47
+ for (const utxo of candidateUtxos) {
48
+ selected.push(utxo);
49
+ accumulated += utxo.value;
50
+ // Assume two outputs initially
51
+ let fee = estimateFeeSats(selected.length, 2, feeRateSatsPerVb, feeEstimate);
52
+ let required = targetAmountSats + fee;
53
+ if (accumulated >= required) {
54
+ // Compute change and dust policy
55
+ let change = accumulated - required;
56
+ if (change > 0 && change < DUST_LIMIT_SATS) {
57
+ // If change would be dust, try recomputing fee for single output (recipient only)
58
+ fee = estimateFeeSats(selected.length, 1, feeRateSatsPerVb, feeEstimate);
59
+ required = targetAmountSats + fee;
60
+ change = accumulated - required;
61
+ if (change > 0 && change < DUST_LIMIT_SATS) {
62
+ // Force add to fee (better than creating dust)
63
+ change = 0;
64
+ }
65
+ }
66
+ if (accumulated >= targetAmountSats + fee) {
67
+ return { selected, feeSats: fee, changeSats: Math.max(0, change) };
68
+ }
69
+ }
70
+ }
71
+ // If we got here, insufficient funds with the given policy
72
+ if (hasLocked && !allowLocked) {
73
+ const err = new UtxoSelectionError('CONFLICTING_LOCKS', 'CONFLICTING_LOCKS');
74
+ throw err;
75
+ }
76
+ const err = new UtxoSelectionError('INSUFFICIENT_FUNDS', 'INSUFFICIENT_FUNDS');
77
+ throw err;
78
+ }
@@ -0,0 +1,195 @@
1
+ {
2
+ "@context": {
3
+ "@version": 1.1,
4
+ "@protected": true,
5
+ "id": "@id",
6
+ "type": "@type",
7
+ "VerifiableCredential": {
8
+ "@id": "https://www.w3.org/2018/credentials#VerifiableCredential",
9
+ "@context": {
10
+ "@version": 1.1,
11
+ "@protected": true,
12
+ "id": "@id",
13
+ "type": "@type",
14
+ "cred": "https://www.w3.org/2018/credentials#",
15
+ "sec": "https://w3id.org/security#",
16
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
17
+ "credentialSchema": {
18
+ "@id": "cred:credentialSchema",
19
+ "@type": "@id",
20
+ "@context": {
21
+ "@version": 1.1,
22
+ "@protected": true,
23
+ "id": "@id",
24
+ "type": "@type",
25
+ "cred": "https://www.w3.org/2018/credentials#",
26
+ "JsonSchemaValidator2018": "cred:JsonSchemaValidator2018"
27
+ }
28
+ },
29
+ "credentialStatus": { "@id": "cred:credentialStatus", "@type": "@id" },
30
+ "credentialSubject": { "@id": "cred:credentialSubject", "@type": "@id" },
31
+ "evidence": { "@id": "cred:evidence", "@type": "@id" },
32
+ "expirationDate": { "@id": "cred:expirationDate", "@type": "xsd:dateTime" },
33
+ "holder": { "@id": "cred:holder", "@type": "@id" },
34
+ "issued": { "@id": "cred:issued", "@type": "xsd:dateTime" },
35
+ "issuer": { "@id": "cred:issuer", "@type": "@id" },
36
+ "issuanceDate": { "@id": "cred:issuanceDate", "@type": "xsd:dateTime" },
37
+ "proof": { "@id": "sec:proof", "@type": "@id", "@container": "@graph" },
38
+ "refreshService": {
39
+ "@id": "cred:refreshService",
40
+ "@type": "@id",
41
+ "@context": {
42
+ "@version": 1.1,
43
+ "@protected": true,
44
+ "id": "@id",
45
+ "type": "@type",
46
+ "cred": "https://www.w3.org/2018/credentials#",
47
+ "ManualRefreshService2018": "cred:ManualRefreshService2018"
48
+ }
49
+ },
50
+ "termsOfUse": { "@id": "cred:termsOfUse", "@type": "@id" },
51
+ "validFrom": { "@id": "cred:validFrom", "@type": "xsd:dateTime" },
52
+ "validUntil": { "@id": "cred:validUntil", "@type": "xsd:dateTime" }
53
+ }
54
+ },
55
+ "VerifiablePresentation": {
56
+ "@id": "https://www.w3.org/2018/credentials#VerifiablePresentation",
57
+ "@context": {
58
+ "@version": 1.1,
59
+ "@protected": true,
60
+ "id": "@id",
61
+ "type": "@type",
62
+ "cred": "https://www.w3.org/2018/credentials#",
63
+ "sec": "https://w3id.org/security#",
64
+ "holder": { "@id": "cred:holder", "@type": "@id" },
65
+ "proof": { "@id": "sec:proof", "@type": "@id", "@container": "@graph" },
66
+ "verifiableCredential": { "@id": "cred:verifiableCredential", "@type": "@id", "@container": "@graph" }
67
+ }
68
+ },
69
+ "EcdsaSecp256k1Signature2019": {
70
+ "@id": "https://w3id.org/security#EcdsaSecp256k1Signature2019",
71
+ "@context": {
72
+ "@version": 1.1,
73
+ "@protected": true,
74
+ "id": "@id",
75
+ "type": "@type",
76
+ "sec": "https://w3id.org/security#",
77
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
78
+ "challenge": "sec:challenge",
79
+ "created": { "@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime" },
80
+ "domain": "sec:domain",
81
+ "expires": { "@id": "sec:expiration", "@type": "xsd:dateTime" },
82
+ "jws": "sec:jws",
83
+ "nonce": "sec:nonce",
84
+ "proofPurpose": {
85
+ "@id": "sec:proofPurpose",
86
+ "@type": "@vocab",
87
+ "@context": {
88
+ "@version": 1.1,
89
+ "@protected": true,
90
+ "id": "@id",
91
+ "type": "@type",
92
+ "sec": "https://w3id.org/security#",
93
+ "assertionMethod": { "@id": "sec:assertionMethod", "@type": "@id", "@container": "@set" },
94
+ "authentication": { "@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set" }
95
+ }
96
+ },
97
+ "proofValue": "sec:proofValue",
98
+ "verificationMethod": { "@id": "sec:verificationMethod", "@type": "@id" }
99
+ }
100
+ },
101
+ "EcdsaSecp256r1Signature2019": {
102
+ "@id": "https://w3id.org/security#EcdsaSecp256r1Signature2019",
103
+ "@context": {
104
+ "@version": 1.1,
105
+ "@protected": true,
106
+ "id": "@id",
107
+ "type": "@type",
108
+ "sec": "https://w3id.org/security#",
109
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
110
+ "challenge": "sec:challenge",
111
+ "created": { "@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime" },
112
+ "domain": "sec:domain",
113
+ "expires": { "@id": "sec:expiration", "@type": "xsd:dateTime" },
114
+ "jws": "sec:jws",
115
+ "nonce": "sec:nonce",
116
+ "proofPurpose": {
117
+ "@id": "sec:proofPurpose",
118
+ "@type": "@vocab",
119
+ "@context": {
120
+ "@version": 1.1,
121
+ "@protected": true,
122
+ "id": "@id",
123
+ "type": "@type",
124
+ "sec": "https://w3id.org/security#",
125
+ "assertionMethod": { "@id": "sec:assertionMethod", "@type": "@id", "@container": "@set" },
126
+ "authentication": { "@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set" }
127
+ }
128
+ },
129
+ "proofValue": "sec:proofValue",
130
+ "verificationMethod": { "@id": "sec:verificationMethod", "@type": "@id" }
131
+ }
132
+ },
133
+ "Ed25519Signature2018": {
134
+ "@id": "https://w3id.org/security#Ed25519Signature2018",
135
+ "@context": {
136
+ "@version": 1.1,
137
+ "@protected": true,
138
+ "id": "@id",
139
+ "type": "@type",
140
+ "sec": "https://w3id.org/security#",
141
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
142
+ "challenge": "sec:challenge",
143
+ "created": { "@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime" },
144
+ "domain": "sec:domain",
145
+ "expires": { "@id": "sec:expiration", "@type": "xsd:dateTime" },
146
+ "jws": "sec:jws",
147
+ "nonce": "sec:nonce",
148
+ "proofPurpose": {
149
+ "@id": "sec:proofPurpose",
150
+ "@type": "@vocab",
151
+ "@context": {
152
+ "@version": 1.1,
153
+ "@protected": true,
154
+ "id": "@id",
155
+ "type": "@type",
156
+ "sec": "https://w3id.org/security#",
157
+ "assertionMethod": { "@id": "sec:assertionMethod", "@type": "@id", "@container": "@set" },
158
+ "authentication": { "@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set" }
159
+ }
160
+ },
161
+ "proofValue": "sec:proofValue",
162
+ "verificationMethod": { "@id": "sec:verificationMethod", "@type": "@id" }
163
+ }
164
+ },
165
+ "RsaSignature2018": {
166
+ "@id": "https://w3id.org/security#RsaSignature2018",
167
+ "@context": {
168
+ "@version": 1.1,
169
+ "@protected": true,
170
+ "challenge": "sec:challenge",
171
+ "created": { "@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime" },
172
+ "domain": "sec:domain",
173
+ "expires": { "@id": "sec:expiration", "@type": "xsd:dateTime" },
174
+ "jws": "sec:jws",
175
+ "nonce": "sec:nonce",
176
+ "proofPurpose": {
177
+ "@id": "sec:proofPurpose",
178
+ "@type": "@vocab",
179
+ "@context": {
180
+ "@version": 1.1,
181
+ "@protected": true,
182
+ "id": "@id",
183
+ "type": "@type",
184
+ "sec": "https://w3id.org/security#",
185
+ "assertionMethod": { "@id": "sec:assertionMethod", "@type": "@id", "@container": "@set" },
186
+ "authentication": { "@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set" }
187
+ }
188
+ },
189
+ "proofValue": "sec:proofValue",
190
+ "verificationMethod": { "@id": "sec:verificationMethod", "@type": "@id" }
191
+ }
192
+ },
193
+ "proof": { "@id": "https://w3id.org/security#proof", "@type": "@id", "@container": "@graph" }
194
+ }
195
+ }
@@ -0,0 +1,5 @@
1
+ {
2
+ "@context": {
3
+ "@vocab": "https://www.w3.org/ns/credentials/examples#"
4
+ }
5
+ }