b017 0.0.0-b1 → 0.2.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 (45) hide show
  1. package/CHANGELOG.md +568 -39
  2. package/LICENSE.txt +56 -56
  3. package/README.md +310 -206
  4. package/dist/index.d.ts +15 -7
  5. package/dist/index.js +14 -5
  6. package/dist/lib/boltLib.d.ts +29 -3
  7. package/dist/lib/boltLib.js +60 -12
  8. package/dist/lib/genesis.d.ts +20 -0
  9. package/dist/lib/genesis.js +45 -0
  10. package/dist/lib/multi/multiBoltLib.d.ts +22 -2
  11. package/dist/lib/multi/multiBoltLib.js +114 -129
  12. package/dist/lib/scanner/beef.d.ts +11 -0
  13. package/dist/lib/scanner/beef.js +63 -0
  14. package/dist/lib/scanner/fingerprints.d.ts +12 -2
  15. package/dist/lib/scanner/fingerprints.js +45 -12
  16. package/dist/lib/scanner/verifyEvents.d.ts +84 -6
  17. package/dist/lib/scanner/verifyEvents.js +520 -45
  18. package/dist/lib/single/singleAncestor.d.ts +27 -3
  19. package/dist/lib/single/singleAncestor.js +49 -18
  20. package/dist/lib/single/singleSpend.d.ts +12 -3
  21. package/dist/lib/single/singleSpend.js +48 -16
  22. package/dist/tokens/BOLT.d.ts +6 -5
  23. package/dist/tokens/GenesisMultiBOLT.d.ts +29 -0
  24. package/dist/tokens/GenesisMultiBOLT.js +48 -0
  25. package/dist/tokens/MultiBOLT.d.ts +17 -12
  26. package/dist/tokens/MultiBOLT.js +82 -74
  27. package/dist/tokens/templates/AuthBolt.sx.template.d.ts +35 -0
  28. package/dist/tokens/templates/AuthBolt.sx.template.js +82 -0
  29. package/dist/tokens/templates/FixedMulti.sx.template.d.ts +13 -0
  30. package/dist/tokens/templates/FixedMulti.sx.template.js +23 -0
  31. package/dist/tokens/templates/MinSimple.sx.template.d.ts +10 -1
  32. package/dist/tokens/templates/MinSimple.sx.template.js +15 -1
  33. package/dist/tokens/templates/OpenMulti.sx.template.d.ts +13 -0
  34. package/dist/tokens/templates/OpenMulti.sx.template.js +23 -0
  35. package/dist/tokens/templates/SerialBolt.sx.template.d.ts +23 -0
  36. package/dist/tokens/templates/SerialBolt.sx.template.js +61 -0
  37. package/dist/tokens/templates/SimpleMulti.sx.template.d.ts +12 -6
  38. package/dist/tokens/templates/SimpleMulti.sx.template.js +33 -25
  39. package/dist/tokens/templates/pay2Proof.d.ts +2 -1
  40. package/dist/tokens/templates/pay2Proof.js +1 -1
  41. package/package.json +64 -58
  42. package/dist/tokens/templates/MinSimpleBalance.sx.template.d.ts +0 -24
  43. package/dist/tokens/templates/MinSimpleBalance.sx.template.js +0 -59
  44. package/dist/tokens/templates/MinSimpleDiscount.sx.template.d.ts +0 -23
  45. package/dist/tokens/templates/MinSimpleDiscount.sx.template.js +0 -58
@@ -1,28 +1,40 @@
1
1
  // multiBoltLib.ts
2
- // SimpleMultiBolt-specific ancestor reconstruction + CTX helpers.
2
+ // Fungible-family ancestor reconstruction + CTX helpers: SimpleMultiBolt and the genesis family
3
+ // (FixedBolt, OpenBolt), each described by a MultiLayout.
4
+ //
5
+ // FixedBolt / OpenBolt (genesis layout v3) put two leading lock pushes before the SimpleMultiBolt fields:
6
+ // genesisOutpoint | lastMergeOrGenesisOutpoint (36 B, null on the mint), then mintData (issuer bytes on the
7
+ // mint only, OP_0 after). So every lock / CTX-scriptCode field index is +2, and the ancestor pieces gain
8
+ // Vin{1,2}CTXMintData (FixedBolt: 74 per ancestor, skip 148) plus Vin{1,2}CTXLmg and Vout1Lmg (OpenBolt: 77,
9
+ // skip 154). Piece semantics mirror the sibling toolchain's simulator (the source of truth).
3
10
  //
4
11
  // SimpleMultiBolt is the optimised fungible contract: 16-byte balance, mandatory change/funding.
5
- // - 11 lock data chunks.
6
- // - 198 unlock args; 89 ancestor pieces per ancestor.
12
+ // - 10 lock data chunks (outputIndexN removed: its only read always saw 00).
13
+ // - 164 unlock args; 72 ancestor pieces per ancestor. (Was 198/89 until the dead ancestor args - the
14
+ // S2-unread issuer keys and the unreachable has2TokenOutputs Vout2* args - were removed, then 170/75
15
+ // until outputIndexN and its three ancestor mirrors went.)
7
16
  //
8
17
  // Layout constants:
9
- // - ctxHeader sits at unlock chunk index 192 -> ARGS2CTX_SMB = 192
10
- // - lock data-push count -> PUSHDATAS_SMB = 11
11
- // - live section start in a token unlock script -> SKIP_SMB = 178
18
+ // - ctxHeader sits at unlock chunk index 158 -> ARGS2CTX_SMB = 158
19
+ // - lock data-push count -> PUSHDATAS_SMB = 10
20
+ // - live section start in a token unlock script -> SKIP_SMB = 144
12
21
  // - txoType lock chunk index -> TXOTYPE_IDX_SMB = 6
13
22
  //
14
23
  // Self-contained: depends only on @bsv/sdk (no sx tooling at runtime).
15
24
  import { Script, Utils } from "@bsv/sdk";
16
25
  import { txVersion, txLockTime, spentOutpoint, vinChunk, vinSequence, vinScript, voutChunk, outputValue, outputScript, scriptChunksFromBin, } from "../boltLib.js";
17
26
  const { Reader, Writer } = Utils;
18
- const ARGS2CTX_SMB = 192;
19
- const PUSHDATAS_SMB = 11;
20
- const SKIP_SMB = 178;
21
- const TXOTYPE_IDX_SMB = 6;
27
+ /** Unlock chunk index where a token spend's own (current-tx) args start = 2 x pieces. */
28
+ export const skipOf = (l) => 2 * l.pieces.length;
29
+ /** Unlock chunk index of ctxHeader: skip + 5 interop + fund, change, pkh1, pkh2, nextBalanceCommit,
30
+ * nextTxoType, inputIndexN, sig, pubKey. */
31
+ export const args2ctxOf = (l) => skipOf(l) + 14;
32
+ /** Lock chunk index of txoType. */
33
+ export const txoTypeIdxOf = (l) => 6 + l.leading;
22
34
  // ---- CTX reconstruction from a prior token tx's vin unlocking script ----
23
35
  // ctxHeader is at ARGS2CTX_SMB; ctxCodeLockScriptCode/footer/lockLen at +3/+4/+5.
24
36
  // piece 0 = ctxHeader (104 bytes); piece 2 = ctxFooter (the bytes after the scriptCode).
25
- const getVinCTXPieceSMB = (tx, vinIndex, piece) => {
37
+ const getVinCTXPieceSMB = (tx, vinIndex, piece, ARGS2CTX_SMB) => {
26
38
  const w = new Utils.Writer();
27
39
  const inputScript = tx.inputs[vinIndex]?.unlockingScript;
28
40
  if (!inputScript?.chunks?.[ARGS2CTX_SMB])
@@ -49,8 +61,8 @@ const getVinCTXPieceSMB = (tx, vinIndex, piece) => {
49
61
  return w.toArray();
50
62
  };
51
63
  // Extract a single committed lock-data arg out of the reconstructed CTX scriptCode.
52
- // argIdx indexes the 11 SMB lock data chunks (balance=0 ... issuerPubKey=10).
53
- const getVinCTXDataArgSMB = (tx, vinIndex, argIdx) => {
64
+ // argIdx indexes the lock data chunks (SMB: balance=0 ... issuerPubKey=10; the genesis family +2).
65
+ const getVinCTXDataArgSMB = (tx, vinIndex, argIdx, ARGS2CTX_SMB) => {
54
66
  const inputScript = tx.inputs[vinIndex]?.unlockingScript;
55
67
  if (!inputScript?.chunks?.[ARGS2CTX_SMB])
56
68
  return [];
@@ -78,13 +90,13 @@ const getVinCTXDataArgSMB = (tx, vinIndex, argIdx) => {
78
90
  };
79
91
  // SimpleMultiBolt action bytes (no swap): 20 transferSettle, 21 transferCommit,
80
92
  // 22 splitSettle, 23 splitCommit, 24 mergeSettle, 25 mergeCommit.
81
- const determineTxTypeSMB = (tx) => {
93
+ const determineTxTypeSMB = (tx, layout) => {
82
94
  const firstToken = tx.outputs[0];
83
- const txoType = firstToken.lockingScript.chunks[TXOTYPE_IDX_SMB];
95
+ const txoType = firstToken.lockingScript.chunks[txoTypeIdxOf(layout)];
84
96
  const typeByte = txoType?.data?.[0] || -1;
85
97
  return typeByte.toString(16);
86
98
  };
87
- // The 89 SimpleMultiBolt ancestor piece names per ancestor.
99
+ // The 72 SimpleMultiBolt ancestor piece names per ancestor.
88
100
  export const PIECE_NAMES = [
89
101
  "Version",
90
102
  "Vin1Outpoint",
@@ -96,8 +108,8 @@ export const PIECE_NAMES = [
96
108
  "Vin1CTXHeader", "Vin1CTXBalance", "Vin1CTXBalanceCommit",
97
109
  "Vin1CTXPubKeyHash", "Vin1CTXPubKeyHashCommit", "Vin1CTXPubKeyHashCommit2",
98
110
  "Vin1CTXOtherGrandparentOutpoint",
99
- "Vin1CTXTxoType", "Vin1CTXOutputIndexN",
100
- "Vin1CTXParentOutpoint", "Vin1CTXGrandparentOutpoint", "Vin1CTXIssuerPubKey",
111
+ "Vin1CTXTxoType",
112
+ "Vin1CTXParentOutpoint", "Vin1CTXGrandparentOutpoint",
101
113
  "Vin1CTXFooter", "Vin1NSequence",
102
114
  "Vin2Outpoint",
103
115
  "Vin2GrandparentProofVoutIdx", "Vin2InteropProofVoutIdx",
@@ -108,28 +120,48 @@ export const PIECE_NAMES = [
108
120
  "Vin2CTXHeader", "Vin2CTXBalance", "Vin2CTXBalanceCommit",
109
121
  "Vin2CTXPubKeyHash", "Vin2CTXPubKeyHashCommit", "Vin2CTXPubKeyHashCommit2",
110
122
  "Vin2CTXOtherGrandparentOutpoint",
111
- "Vin2CTXTxoType", "Vin2CTXOutputIndexN",
112
- "Vin2CTXParentOutpoint", "Vin2CTXGrandparentOutpoint", "Vin2CTXIssuerPubKey",
123
+ "Vin2CTXTxoType",
124
+ "Vin2CTXParentOutpoint", "Vin2CTXGrandparentOutpoint",
113
125
  "Vin2CTXFooter", "Vin2NSequence",
114
126
  "VinFundOutpoint", "VinFundScript", "VinFundNSequence",
115
127
  "Vout1Balance", "Vout1BalanceCommit",
116
128
  "Vout1PubKeyHash", "Vout1PubKeyHashCommit", "Vout1PubKeyHashCommit2",
117
129
  "Vout1OtherGrandparentOutpoint",
118
- "Vout1TxoType", "Vout1OutputIndexN",
119
- "Vout1ParentOutpoint", "Vout1GrandparentOutpoint", "Vout1IssuerPubKey",
120
- "Vout2Balance", "Vout2BalanceCommit",
121
- "Vout2PubKeyHash", "Vout2PubKeyHashCommit", "Vout2PubKeyHashCommit2",
122
- "Vout2OtherGrandparentOutpoint",
123
- "Vout2TxoType", "Vout2OutputIndexN",
124
- "Vout2ParentOutpoint", "Vout2GrandparentOutpoint", "Vout2IssuerPubKey",
130
+ "Vout1TxoType",
131
+ "Vout1ParentOutpoint", "Vout1GrandparentOutpoint",
125
132
  "ProofPubKeyHash1", "ProofPubKeyHash2",
126
133
  "ChangeValue", "ChangeScript", "NLockTime",
127
134
  ];
128
- // Extract one named ancestor piece from a SimpleMultiBolt transaction.
129
- export const ancestorPiece = (name, tx) => {
135
+ const insertAfter = (list, anchor, ...names) => {
136
+ const i = list.indexOf(anchor);
137
+ return [...list.slice(0, i + 1), ...names, ...list.slice(i + 1)];
138
+ };
139
+ const insertBefore = (list, anchor, ...names) => {
140
+ const i = list.indexOf(anchor);
141
+ return [...list.slice(0, i), ...names, ...list.slice(i)];
142
+ };
143
+ export const SIMPLE_MULTI_LAYOUT = { name: "SimpleMultiBolt", pieces: PIECE_NAMES, leading: 0 };
144
+ /** FixedBolt: + the ancestor spent token's mintData after each CTXHeader (74 pieces, skip 148). */
145
+ export const FIXED_BOLT_LAYOUT = {
146
+ name: "FixedBolt",
147
+ pieces: insertAfter(insertAfter(PIECE_NAMES, "Vin1CTXHeader", "Vin1CTXMintData"), "Vin2CTXHeader", "Vin2CTXMintData"),
148
+ leading: 2,
149
+ };
150
+ /** OpenBolt: + each spent token's LMG before its mintData, and the rebuilt output's LMG (77 pieces, skip 154). */
151
+ export const OPEN_BOLT_LAYOUT = {
152
+ name: "OpenBolt",
153
+ pieces: insertBefore(insertAfter(insertAfter(PIECE_NAMES, "Vin1CTXHeader", "Vin1CTXLmg", "Vin1CTXMintData"), "Vin2CTXHeader", "Vin2CTXLmg", "Vin2CTXMintData"), "Vout1Balance", "Vout1Lmg"),
154
+ leading: 2,
155
+ };
156
+ // Extract one named ancestor piece from a fungible-family transaction (SimpleMultiBolt by default).
157
+ export const ancestorPiece = (name, tx, layout = SIMPLE_MULTI_LAYOUT) => {
130
158
  let res = [];
131
159
  const ancestorTx = tx;
132
- const txType = determineTxTypeSMB(ancestorTx);
160
+ const SKIP_SMB = skipOf(layout);
161
+ const A2C = args2ctxOf(layout);
162
+ const L = layout.leading;
163
+ const ctxArg = (vin, k) => getVinCTXDataArgSMB(ancestorTx, vin, k + L, A2C);
164
+ const txType = determineTxTypeSMB(ancestorTx, layout);
133
165
  const hasTwoTokenInputs = txType === "25"; // mergeCommit (swap removed)
134
166
  const hasTwoBolts = txType === "23"; // splitCommit
135
167
  const fundVinIdx = ancestorTx.inputs.length - 1;
@@ -188,43 +220,44 @@ export const ancestorPiece = (name, tx) => {
188
220
  res = vinChunk(ancestorTx, 0, SKIP_SMB + 13);
189
221
  break;
190
222
  case "Vin1CTXHeader":
191
- res = getVinCTXPieceSMB(ancestorTx, 0, 0);
223
+ res = getVinCTXPieceSMB(ancestorTx, 0, 0, A2C);
224
+ break;
225
+ // genesis family: the ancestor spent token's leading pushes (lock chunk 0 = genesis / LMG, 1 = mintData)
226
+ case "Vin1CTXLmg":
227
+ res = getVinCTXDataArgSMB(ancestorTx, 0, 0, A2C);
228
+ break;
229
+ case "Vin1CTXMintData":
230
+ res = getVinCTXDataArgSMB(ancestorTx, 0, 1, A2C);
192
231
  break;
193
232
  case "Vin1CTXBalance":
194
- res = getVinCTXDataArgSMB(ancestorTx, 0, 0);
233
+ res = ctxArg(0, 0);
195
234
  break;
196
235
  case "Vin1CTXBalanceCommit":
197
- res = getVinCTXDataArgSMB(ancestorTx, 0, 1);
236
+ res = ctxArg(0, 1);
198
237
  break;
199
238
  case "Vin1CTXPubKeyHash":
200
- res = getVinCTXDataArgSMB(ancestorTx, 0, 2);
239
+ res = ctxArg(0, 2);
201
240
  break;
202
241
  case "Vin1CTXPubKeyHashCommit":
203
- res = getVinCTXDataArgSMB(ancestorTx, 0, 3);
242
+ res = ctxArg(0, 3);
204
243
  break;
205
244
  case "Vin1CTXPubKeyHashCommit2":
206
- res = getVinCTXDataArgSMB(ancestorTx, 0, 4);
245
+ res = ctxArg(0, 4);
207
246
  break;
208
247
  case "Vin1CTXOtherGrandparentOutpoint":
209
- res = getVinCTXDataArgSMB(ancestorTx, 0, 5);
248
+ res = ctxArg(0, 5);
210
249
  break;
211
250
  case "Vin1CTXTxoType":
212
- res = getVinCTXDataArgSMB(ancestorTx, 0, 6);
213
- break;
214
- case "Vin1CTXOutputIndexN":
215
- res = getVinCTXDataArgSMB(ancestorTx, 0, 7);
251
+ res = ctxArg(0, 6);
216
252
  break;
217
253
  case "Vin1CTXParentOutpoint":
218
- res = getVinCTXDataArgSMB(ancestorTx, 0, 8);
254
+ res = ctxArg(0, 7);
219
255
  break;
220
256
  case "Vin1CTXGrandparentOutpoint":
221
- res = getVinCTXDataArgSMB(ancestorTx, 0, 9);
222
- break;
223
- case "Vin1CTXIssuerPubKey":
224
- res = getVinCTXDataArgSMB(ancestorTx, 0, 10);
257
+ res = ctxArg(0, 8);
225
258
  break;
226
259
  case "Vin1CTXFooter":
227
- res = getVinCTXPieceSMB(ancestorTx, 0, 2);
260
+ res = getVinCTXPieceSMB(ancestorTx, 0, 2, A2C);
228
261
  break;
229
262
  case "Vin1NSequence":
230
263
  res = vinSequence(ancestorTx, 0);
@@ -292,55 +325,55 @@ export const ancestorPiece = (name, tx) => {
292
325
  break;
293
326
  case "Vin2CTXHeader":
294
327
  if (hasTwoTokenInputs)
295
- res = getVinCTXPieceSMB(ancestorTx, 1, 0);
328
+ res = getVinCTXPieceSMB(ancestorTx, 1, 0, A2C);
329
+ break;
330
+ case "Vin2CTXLmg":
331
+ if (hasTwoTokenInputs)
332
+ res = getVinCTXDataArgSMB(ancestorTx, 1, 0, A2C);
333
+ break;
334
+ case "Vin2CTXMintData":
335
+ if (hasTwoTokenInputs)
336
+ res = getVinCTXDataArgSMB(ancestorTx, 1, 1, A2C);
296
337
  break;
297
338
  case "Vin2CTXBalance":
298
339
  if (hasTwoTokenInputs)
299
- res = getVinCTXDataArgSMB(ancestorTx, 1, 0);
340
+ res = ctxArg(1, 0);
300
341
  break;
301
342
  case "Vin2CTXBalanceCommit":
302
343
  if (hasTwoTokenInputs)
303
- res = getVinCTXDataArgSMB(ancestorTx, 1, 1);
344
+ res = ctxArg(1, 1);
304
345
  break;
305
346
  case "Vin2CTXPubKeyHash":
306
347
  if (hasTwoTokenInputs)
307
- res = getVinCTXDataArgSMB(ancestorTx, 1, 2);
348
+ res = ctxArg(1, 2);
308
349
  break;
309
350
  case "Vin2CTXPubKeyHashCommit":
310
351
  if (hasTwoTokenInputs)
311
- res = getVinCTXDataArgSMB(ancestorTx, 1, 3);
352
+ res = ctxArg(1, 3);
312
353
  break;
313
354
  case "Vin2CTXPubKeyHashCommit2":
314
355
  if (hasTwoTokenInputs)
315
- res = getVinCTXDataArgSMB(ancestorTx, 1, 4);
356
+ res = ctxArg(1, 4);
316
357
  break;
317
358
  case "Vin2CTXOtherGrandparentOutpoint":
318
359
  if (hasTwoTokenInputs)
319
- res = getVinCTXDataArgSMB(ancestorTx, 1, 5);
360
+ res = ctxArg(1, 5);
320
361
  break;
321
362
  case "Vin2CTXTxoType":
322
363
  if (hasTwoTokenInputs)
323
- res = getVinCTXDataArgSMB(ancestorTx, 1, 6);
324
- break;
325
- case "Vin2CTXOutputIndexN":
326
- if (hasTwoTokenInputs)
327
- res = getVinCTXDataArgSMB(ancestorTx, 1, 7);
364
+ res = ctxArg(1, 6);
328
365
  break;
329
366
  case "Vin2CTXParentOutpoint":
330
367
  if (hasTwoTokenInputs)
331
- res = getVinCTXDataArgSMB(ancestorTx, 1, 8);
368
+ res = ctxArg(1, 7);
332
369
  break;
333
370
  case "Vin2CTXGrandparentOutpoint":
334
371
  if (hasTwoTokenInputs)
335
- res = getVinCTXDataArgSMB(ancestorTx, 1, 9);
336
- break;
337
- case "Vin2CTXIssuerPubKey":
338
- if (hasTwoTokenInputs)
339
- res = getVinCTXDataArgSMB(ancestorTx, 1, 10);
372
+ res = ctxArg(1, 8);
340
373
  break;
341
374
  case "Vin2CTXFooter":
342
375
  if (hasTwoTokenInputs)
343
- res = getVinCTXPieceSMB(ancestorTx, 1, 2);
376
+ res = getVinCTXPieceSMB(ancestorTx, 1, 2, A2C);
344
377
  break;
345
378
  case "Vin2NSequence":
346
379
  if (hasTwoTokenInputs)
@@ -360,83 +393,35 @@ export const ancestorPiece = (name, tx) => {
360
393
  res = vinSequence(ancestorTx, fundVinIdx);
361
394
  break;
362
395
  // ---- Vout1 (first token output, always present) ----
363
- case "Vout1Balance":
396
+ case "Vout1Lmg":
364
397
  res = voutChunk(ancestorTx, 0, 0);
398
+ break; // OpenBolt: the rebuilt output's LMG
399
+ case "Vout1Balance":
400
+ res = voutChunk(ancestorTx, 0, 0 + L);
365
401
  break;
366
402
  case "Vout1BalanceCommit":
367
- res = voutChunk(ancestorTx, 0, 1);
403
+ res = voutChunk(ancestorTx, 0, 1 + L);
368
404
  break;
369
405
  case "Vout1PubKeyHash":
370
- res = voutChunk(ancestorTx, 0, 2);
406
+ res = voutChunk(ancestorTx, 0, 2 + L);
371
407
  break;
372
408
  case "Vout1PubKeyHashCommit":
373
- res = voutChunk(ancestorTx, 0, 3);
409
+ res = voutChunk(ancestorTx, 0, 3 + L);
374
410
  break;
375
411
  case "Vout1PubKeyHashCommit2":
376
- res = voutChunk(ancestorTx, 0, 4);
412
+ res = voutChunk(ancestorTx, 0, 4 + L);
377
413
  break;
378
414
  case "Vout1OtherGrandparentOutpoint":
379
- res = voutChunk(ancestorTx, 0, 5);
415
+ res = voutChunk(ancestorTx, 0, 5 + L);
380
416
  break;
381
417
  case "Vout1TxoType":
382
- res = voutChunk(ancestorTx, 0, 6);
383
- break;
384
- case "Vout1OutputIndexN":
385
- res = voutChunk(ancestorTx, 0, 7);
418
+ res = voutChunk(ancestorTx, 0, 6 + L);
386
419
  break;
387
420
  case "Vout1ParentOutpoint":
388
- res = voutChunk(ancestorTx, 0, 8);
421
+ res = voutChunk(ancestorTx, 0, 7 + L);
389
422
  break;
390
423
  case "Vout1GrandparentOutpoint":
391
- res = voutChunk(ancestorTx, 0, 9);
392
- break;
393
- case "Vout1IssuerPubKey":
394
- res = voutChunk(ancestorTx, 0, 10);
395
- break;
396
- // ---- Vout2 (second token output, only splitSettle) ----
397
- case "Vout2Balance":
398
- if (hasTwoBolts)
399
- res = voutChunk(ancestorTx, 1, 0);
400
- break;
401
- case "Vout2BalanceCommit":
402
- if (hasTwoBolts)
403
- res = voutChunk(ancestorTx, 1, 1);
404
- break;
405
- case "Vout2PubKeyHash":
406
- if (hasTwoBolts)
407
- res = voutChunk(ancestorTx, 1, 2);
408
- break;
409
- case "Vout2PubKeyHashCommit":
410
- if (hasTwoBolts)
411
- res = voutChunk(ancestorTx, 1, 3);
412
- break;
413
- case "Vout2PubKeyHashCommit2":
414
- if (hasTwoBolts)
415
- res = voutChunk(ancestorTx, 1, 4);
416
- break;
417
- case "Vout2OtherGrandparentOutpoint":
418
- if (hasTwoBolts)
419
- res = voutChunk(ancestorTx, 1, 5);
420
- break;
421
- case "Vout2TxoType":
422
- if (hasTwoBolts)
423
- res = voutChunk(ancestorTx, 1, 6);
424
- break;
425
- case "Vout2OutputIndexN":
426
- if (hasTwoBolts)
427
- res = voutChunk(ancestorTx, 1, 7);
428
- break;
429
- case "Vout2ParentOutpoint":
430
- if (hasTwoBolts)
431
- res = voutChunk(ancestorTx, 1, 8);
432
- break;
433
- case "Vout2GrandparentOutpoint":
434
- if (hasTwoBolts)
435
- res = voutChunk(ancestorTx, 1, 9);
436
- break;
437
- case "Vout2IssuerPubKey":
438
- if (hasTwoBolts)
439
- res = voutChunk(ancestorTx, 1, 10);
424
+ res = voutChunk(ancestorTx, 0, 8 + L);
440
425
  break;
441
426
  // ---- Bolt (pay2Bolt) outputs ----
442
427
  case "ProofPubKeyHash1":
@@ -463,10 +448,10 @@ export const ancestorPiece = (name, tx) => {
463
448
  }
464
449
  return res;
465
450
  };
466
- // 89 ancestorA + 89 ancestorB = 178 empty chunks (no leading miscData) for melt.
467
- export const createEmptyFungibleAncestorChunksSMB = () => {
451
+ // 2 x pieces empty chunks (SMB 144, FixedBolt 148, OpenBolt 154; no leading miscData) for melt.
452
+ export const createEmptyFungibleAncestorChunksSMB = (layout = SIMPLE_MULTI_LAYOUT) => {
468
453
  const emptyChunks = [];
469
- for (let i = 0; i < SKIP_SMB; i++) {
454
+ for (let i = 0; i < skipOf(layout); i++) {
470
455
  emptyChunks.push(...scriptChunksFromBin([]));
471
456
  }
472
457
  return emptyChunks;
@@ -0,0 +1,11 @@
1
+ import { Transaction } from "@bsv/sdk";
2
+ /** True when the hex string / bytes begin with a BEEF magic (V1, V2 or Atomic). */
3
+ export declare function isBeef(x: string | Uint8Array | number[]): boolean;
4
+ /** Serialise `tx` and every attached source tx (with merkle paths where known) as Atomic BEEF over BEEF V2. */
5
+ export declare function toAtomicBeef(tx: Transaction): number[];
6
+ /**
7
+ * Parse BEEF V2 (plain or Atomic) into its subject transaction, with every ancestor wired in through
8
+ * `sourceTransaction` (and `merklePath` on proven ones). Throws on BEEF V1, on a BEEF that is not self-contained
9
+ * (a tx neither proven by a BUMP nor having all its inputs in the BEEF, or txid-only entries), or on no subject.
10
+ */
11
+ export declare function fromBeef(input: string | Uint8Array | number[]): Transaction;
@@ -0,0 +1,63 @@
1
+ // beef.ts - the data package for an off-chain (SPV) token transfer: Atomic BEEF (BRC-95) over BEEF V2 (BRC-96).
2
+ //
3
+ // A commit or settle received by SPV is only verifiable if the txs it spends travel with it, back to txs a block
4
+ // has proven. BEEF carries exactly that: the subject tx, every unproven ancestor, and a BUMP (merkle path) for the
5
+ // proven ones. b017 uses the CURRENT format only: BEEF V2, wrapped as Atomic BEEF so the package names ONE subject.
6
+ // BEEF V1 (BRC-62) is refused. The scanner checks the package is SELF-CONTAINED (every tx is proven by a BUMP or has
7
+ // all its inputs in the BEEF) but fromBeef does NOT check a BUMP's merkle root against a block header; do that with
8
+ // `Beef.verify(chainTracker)` / `tx.merklePath.verify(txid, chainTracker)`, which needs a header source. The one
9
+ // BUMP verifyEvents checks itself is an ANCHOR's, against the headers the caller supplies (isKnownBlockRoot).
10
+ import { Beef, Utils } from "@bsv/sdk";
11
+ const BEEF_V2 = 4022206466; // 0200BEEF (LE)
12
+ const MAGIC_V1 = "0100beef";
13
+ const MAGIC_V2 = "0200beef";
14
+ const MAGIC_ATOMIC = "01010101";
15
+ /** True when the hex string / bytes begin with a BEEF magic (V1, V2 or Atomic). */
16
+ export function isBeef(x) {
17
+ const head = typeof x === "string" ? x.slice(0, 8).toLowerCase() : Utils.toHex(Array.from(x).slice(0, 4));
18
+ return head === MAGIC_V1 || head === MAGIC_V2 || head === MAGIC_ATOMIC;
19
+ }
20
+ /** The SDK orders a BEEF by each input's `sourceTXID`; an in-memory tx often carries only `sourceTransaction`, which
21
+ * would make every tx look input-less and lose the dependency order. Fill it in across the attached graph. */
22
+ function fillSourceTxids(tx, seen = new Set()) {
23
+ if (seen.has(tx))
24
+ return;
25
+ seen.add(tx);
26
+ for (const input of tx.inputs) {
27
+ if (!input.sourceTransaction)
28
+ continue;
29
+ if (input.sourceTXID === undefined)
30
+ input.sourceTXID = input.sourceTransaction.id("hex");
31
+ fillSourceTxids(input.sourceTransaction, seen);
32
+ }
33
+ }
34
+ /** Serialise `tx` and every attached source tx (with merkle paths where known) as Atomic BEEF over BEEF V2. */
35
+ export function toAtomicBeef(tx) {
36
+ fillSourceTxids(tx);
37
+ const beef = new Beef(BEEF_V2);
38
+ beef.mergeTransaction(tx);
39
+ return beef.toBinaryAtomic(tx.id("hex"));
40
+ }
41
+ /**
42
+ * Parse BEEF V2 (plain or Atomic) into its subject transaction, with every ancestor wired in through
43
+ * `sourceTransaction` (and `merklePath` on proven ones). Throws on BEEF V1, on a BEEF that is not self-contained
44
+ * (a tx neither proven by a BUMP nor having all its inputs in the BEEF, or txid-only entries), or on no subject.
45
+ */
46
+ export function fromBeef(input) {
47
+ const bytes = typeof input === "string" ? Utils.toArray(input, "hex") : Array.from(input);
48
+ const beef = Beef.fromBinary(bytes);
49
+ if (beef.version !== BEEF_V2)
50
+ throw new Error("BEEF V1 (BRC-62) is not accepted; use BEEF V2 (BRC-96) / Atomic BEEF (BRC-95)");
51
+ if (!beef.isValid(false))
52
+ throw new Error("BEEF is not self-contained: a tx is neither proven by a BUMP nor has all its inputs in the BEEF");
53
+ // The SDK counts a tx with no inputs and no BUMP as vacuously valid. A real tx always spends something, so an
54
+ // unproven tx with no inputs is a fabricated root: refuse it.
55
+ for (const t of beef.txs)
56
+ if (t.tx && t.bumpIndex === undefined && t.tx.inputs.length === 0)
57
+ throw new Error(`BEEF is not self-contained: tx ${t.txid.slice(0, 8)} has no inputs and no BUMP`);
58
+ const subject = beef.atomicTxid ?? [...beef.txs].reverse().find((t) => t.tx)?.txid;
59
+ const tx = subject ? beef.findAtomicTransaction(subject) : undefined;
60
+ if (!tx)
61
+ throw new Error("BEEF has no subject transaction");
62
+ return tx;
63
+ }
@@ -1,18 +1,28 @@
1
1
  import { Script } from "@bsv/sdk";
2
- export type TokenType = "MinSimpleBOLT" | "MinSimpleDiscountBOLT" | "MinSimpleBalanceBOLT" | "SimpleMultiBOLT";
2
+ export type TokenType = "MinSimpleBOLT" | "AuthBOLT" | "SimpleMultiBOLT" | "FixedBOLT" | "OpenBOLT" | "SerialBOLT";
3
+ /** Genesis-family recognition phase: the mint (null field, any mintData) or any later output. */
4
+ export type TokenPhase = "mint" | "postMint";
3
5
  export interface TypeSpec {
4
6
  type: TokenType;
5
7
  dataPushCount: number;
8
+ /** Exact push lengths (for the genesis family: the postMint spec; the mint spec relaxes pushes 0-1). */
6
9
  pushLengths: number[];
7
10
  suffixHashHex: string;
11
+ /** Genesis family: leads with the 36-byte genesis / LMG field and the mintData push. */
12
+ genesis: boolean;
8
13
  }
9
14
  export declare const sha256Hex: (bin: number[]) => string;
10
15
  export declare const REGISTRY: Record<TokenType, TypeSpec>;
11
16
  /**
12
- * Recognise a locking script as a genuine BOLT token of a known type (or null).
17
+ * Recognise a locking script as a genuine BOLT token of a known type, with its genesis-family phase (or null).
13
18
  * Requires BOTH the leading-push layout AND the static-code hash to match a registered type —
14
19
  * so a tampered contract body or a non-token script is rejected.
15
20
  */
21
+ export declare function recognizeToken(lock: Script | null | undefined, expected?: TokenType): {
22
+ type: TokenType;
23
+ phase?: TokenPhase;
24
+ } | null;
25
+ /** Recognise a locking script as a genuine BOLT token of a known type (or null). See recognizeToken. */
16
26
  export declare function recognizeType(lock: Script | null | undefined, expected?: TokenType): TokenType | null;
17
27
  /** The issuerPubKey is always the last dynamic data push of a recognised token. */
18
28
  export declare function issuerPubKeyOf(lock: Script, type: TokenType): number[];
@@ -3,27 +3,42 @@
3
3
  // A type's fingerprint is { pushLengths (the data-push byte layout) , suffixHash = sha256(static code) }.
4
4
  // issuerPubKey is always the LAST dynamic push (33 bytes); it identifies the issuer, not the type.
5
5
  //
6
+ // The genesis family (FixedBOLT, OpenBOLT, SerialBOLT) leads with two more pushes: a 36-byte outpoint field and the
7
+ // issuer's mintData, which is variable on the MINT and empty (OP_0) on every later output. So each has TWO specs:
8
+ // mint field 0 = 36 zero bytes (null), mintData 0..255 bytes;
9
+ // postMint field 0 = 36 bytes, not all zero, mintData exactly 0 bytes.
10
+ // Every other push is exact-length in both. A non-empty mintData after the mint is therefore unrecognised.
11
+ //
6
12
  // The same golden-hash idea also fingerprints the p2Proof output (the b017 marker proof carried by
7
13
  // commit txs and consumed by settle txs): its only dynamic field is the 20-byte beneficiary pkh, so
8
14
  // recognizeP2P hashes the static skeleton (incl. the b017 marker bytes) and checks the pkh length.
9
15
  import { Hash, Script, Utils } from "@bsv/sdk";
10
16
  import MinSimpleTemplate from "../../tokens/templates/MinSimple.sx.template.js";
11
- import MinSimpleDiscountTemplate from "../../tokens/templates/MinSimpleDiscount.sx.template.js";
12
- import MinSimpleBalanceTemplate from "../../tokens/templates/MinSimpleBalance.sx.template.js";
17
+ import AuthBoltTemplate from "../../tokens/templates/AuthBolt.sx.template.js";
13
18
  import SimpleMultiTemplate from "../../tokens/templates/SimpleMulti.sx.template.js";
19
+ import FixedMultiTemplate from "../../tokens/templates/FixedMulti.sx.template.js";
20
+ import OpenMultiTemplate from "../../tokens/templates/OpenMulti.sx.template.js";
21
+ import SerialBoltTemplate from "../../tokens/templates/SerialBolt.sx.template.js";
14
22
  import Pay2ProofTemplate from "../../tokens/templates/pay2Proof.js";
15
23
  // Leading dynamic-push byte lengths per type (issuerPubKey is always the last, 33 bytes).
16
24
  const LAYOUTS = Object.freeze({
17
25
  MinSimpleBOLT: [20, 20, 1, 36, 36, 33],
18
- MinSimpleDiscountBOLT: [1, 20, 20, 1, 36, 36, 33],
19
- MinSimpleBalanceBOLT: [16, 20, 20, 1, 36, 36, 33],
20
- SimpleMultiBOLT: [16, 16, 20, 20, 20, 36, 1, 1, 36, 36, 33],
26
+ AuthBOLT: [20, 20, 1, 36, 36, 33], // same lock layout as MinSimpleBOLT: told apart by the suffix hash alone
27
+ SimpleMultiBOLT: [16, 16, 20, 20, 20, 36, 1, 36, 36, 33], // the outputIndexN push removed (CHANGELOG, Unreleased)
28
+ FixedBOLT: [36, 0, 16, 16, 20, 20, 20, 36, 1, 36, 36, 33],
29
+ OpenBOLT: [36, 0, 16, 16, 20, 20, 20, 36, 1, 36, 36, 33],
30
+ SerialBOLT: [36, 0, 20, 20, 1, 36, 36, 33],
21
31
  });
32
+ const GENESIS = new Set(["FixedBOLT", "OpenBOLT", "SerialBOLT"]);
33
+ /** mintData is pushed with at most PUSHDATA1. */
34
+ const MINT_DATA_MAX = 255;
22
35
  const SUFFIX = {
23
36
  MinSimpleBOLT: new MinSimpleTemplate().staticSuffix(),
24
- MinSimpleDiscountBOLT: new MinSimpleDiscountTemplate().staticSuffix(),
25
- MinSimpleBalanceBOLT: new MinSimpleBalanceTemplate().staticSuffix(),
37
+ AuthBOLT: new AuthBoltTemplate().staticSuffix(),
26
38
  SimpleMultiBOLT: new SimpleMultiTemplate().staticSuffix(),
39
+ FixedBOLT: new FixedMultiTemplate().staticSuffix(),
40
+ OpenBOLT: new OpenMultiTemplate().staticSuffix(),
41
+ SerialBOLT: new SerialBoltTemplate().staticSuffix(),
27
42
  };
28
43
  export const sha256Hex = (bin) => Utils.toHex(Hash.sha256(bin));
29
44
  export const REGISTRY = Object.freeze(Object.fromEntries(Object.keys(LAYOUTS).map((type) => [
@@ -33,14 +48,28 @@ export const REGISTRY = Object.freeze(Object.fromEntries(Object.keys(LAYOUTS).ma
33
48
  dataPushCount: LAYOUTS[type].length,
34
49
  pushLengths: Object.freeze([...LAYOUTS[type]]),
35
50
  suffixHashHex: sha256Hex(SUFFIX[type].toBinary()),
51
+ genesis: GENESIS.has(type),
36
52
  }),
37
53
  ])));
54
+ /** The leading pushes match a spec: exact lengths, except the genesis family's mint / postMint pair (see top). */
55
+ function pushesMatch(lock, spec) {
56
+ const n = spec.dataPushCount;
57
+ const lens = lock.chunks.slice(0, n).map((c) => c.data?.length ?? 0);
58
+ if (!spec.genesis)
59
+ return lens.every((l, i) => l === spec.pushLengths[i]) ? "exact" : null;
60
+ if (!lens.every((l, i) => i < 2 || l === spec.pushLengths[i]) || lens[0] !== 36)
61
+ return null;
62
+ const nullField = lock.chunks[0].data.every((b) => b === 0);
63
+ if (nullField)
64
+ return lens[1] <= MINT_DATA_MAX ? "mint" : null;
65
+ return lens[1] === 0 ? "postMint" : null;
66
+ }
38
67
  /**
39
- * Recognise a locking script as a genuine BOLT token of a known type (or null).
68
+ * Recognise a locking script as a genuine BOLT token of a known type, with its genesis-family phase (or null).
40
69
  * Requires BOTH the leading-push layout AND the static-code hash to match a registered type —
41
70
  * so a tampered contract body or a non-token script is rejected.
42
71
  */
43
- export function recognizeType(lock, expected) {
72
+ export function recognizeToken(lock, expected) {
44
73
  if (!lock || !Array.isArray(lock.chunks))
45
74
  return null;
46
75
  for (const spec of Object.values(REGISTRY)) {
@@ -49,16 +78,20 @@ export function recognizeType(lock, expected) {
49
78
  const n = spec.dataPushCount;
50
79
  if (lock.chunks.length <= n)
51
80
  continue;
52
- const lens = lock.chunks.slice(0, n).map((c) => c.data?.length ?? 0);
53
- if (!lens.every((l, i) => l === spec.pushLengths[i]))
81
+ const m = pushesMatch(lock, spec);
82
+ if (!m)
54
83
  continue;
55
84
  const suffix = new Script(lock.chunks.slice(n));
56
85
  if (sha256Hex(suffix.toBinary()) !== spec.suffixHashHex)
57
86
  continue;
58
- return spec.type;
87
+ return m === "exact" ? { type: spec.type } : { type: spec.type, phase: m };
59
88
  }
60
89
  return null;
61
90
  }
91
+ /** Recognise a locking script as a genuine BOLT token of a known type (or null). See recognizeToken. */
92
+ export function recognizeType(lock, expected) {
93
+ return recognizeToken(lock, expected)?.type ?? null;
94
+ }
62
95
  /** The issuerPubKey is always the last dynamic data push of a recognised token. */
63
96
  export function issuerPubKeyOf(lock, type) {
64
97
  return lock.chunks[REGISTRY[type].dataPushCount - 1]?.data ?? [];