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
@@ -3,35 +3,113 @@ import { type TokenType } from "./fingerprints.js";
3
3
  export interface ScanOpts {
4
4
  expectedType?: TokenType;
5
5
  trustedIssuerPubKey?: number[] | string;
6
+ /** Your block headers: is `merkleRoot` the merkle root of the block at `height`? An anchor whose merkle path
7
+ * proves it into a header you know is HEADER-PROVEN: consensus already validated it, so its own inputs are not
8
+ * re-executed and its sources need not be supplied (a BEEF stops at proven txs). An UNFUNDED anchor is refused
9
+ * unless it is header-proven. */
10
+ isKnownBlockRoot?: (merkleRoot: string, height: number) => boolean;
11
+ /** Refuse a batch holding an event tx whose outputs exceed its inputs (see ScanResult.offChainOnly). Default
12
+ * false: such a tx is valid OFF chain (a never-broadcast commit / settle certifying auth data) and is only
13
+ * reported. Set true when the events are meant to be broadcast as they are. */
14
+ requireBroadcastable?: boolean;
15
+ }
16
+ /** An event tx whose outputs exceed its inputs: its scripts are valid, but no node will accept it as built. */
17
+ export interface OffChainOnlyTx {
18
+ txid: string;
19
+ inputSats: number;
20
+ outputSats: number;
21
+ }
22
+ /** An async source of block headers (the `@bsv/sdk` ChainTracker shape), usable with verifyAndBroadcast. */
23
+ export interface HeaderSource {
24
+ isValidRootForHeight(root: string, height: number): Promise<boolean>;
25
+ }
26
+ /** A tx an event spends that is not itself part of the event; `proven` = it carries a BUMP (merkle path). */
27
+ export interface SourceTx {
28
+ txid: string;
29
+ proven: boolean;
6
30
  }
7
31
  export type EventKind = "mint" | "transfer" | "split" | "merge" | "melt";
32
+ /** What the network said about a broadcast anchor. "already-seen" = the node already knows the tx (mempool or mined). */
33
+ export type AnchorStatus = "accepted" | "already-seen" | "rejected";
34
+ /** An anchor: the token tx a batch stands on (the settle before its first commit, or the mint). The caller must
35
+ * broadcast it; `status` / `detail` are filled in by verifyAndBroadcast. */
36
+ export interface AnchorRef {
37
+ txid: string;
38
+ kind: "mint" | "settle";
39
+ status?: AnchorStatus;
40
+ detail?: string;
41
+ }
42
+ export interface AnchorBroadcastResult {
43
+ status: AnchorStatus;
44
+ detail?: string;
45
+ }
46
+ /** The caller's broadcaster: send ONE anchor tx (its unproven ancestors are attached through `sourceTransaction`)
47
+ * and report whether the network accepted it, already knew it, or rejected it. */
48
+ export type AnchorBroadcaster = (anchor: Transaction) => Promise<AnchorBroadcastResult>;
8
49
  export interface ScanResult {
9
50
  ok: boolean;
10
51
  reason?: string;
11
52
  type?: TokenType;
12
53
  issuerPubKeyHex?: string;
54
+ /** The txs the event txs spend that are not themselves event txs (parents / funding), with whether each carries a BUMP.
55
+ * A `proven` source is NOT checked against a block header here: verify its merkle path with your ChainTracker.
56
+ * (Only an ANCHOR's merkle path is checked, against `isKnownBlockRoot`.) */
57
+ sources?: SourceTx[];
58
+ /** true when the batch holds a mint that no commit in it spends (the mint alone proves nothing about the issuer key). */
59
+ unauthenticated?: boolean;
13
60
  events?: {
14
61
  kind: EventKind;
15
62
  txids: string[];
16
63
  }[];
64
+ /** The anchors the batch stands on (see AnchorRef). `ok: true` from verifyEvents is only FINAL once the network has
65
+ * accepted (or already seen) every one of them: broadcast them, or call verifyAndBroadcast. */
66
+ anchors?: AnchorRef[];
67
+ /** VALUE CONSERVATION, reported not refused: the event txs whose outputs exceed their inputs. They are valid off
68
+ * chain (the scripts execute) but cannot be broadcast as built; fund them first. Absent when every event tx
69
+ * conserves value. An ANCHOR that creates value is refused instead: the network would never accept it. */
70
+ offChainOnly?: OffChainOnlyTx[];
17
71
  }
18
72
  export interface EventResult {
19
73
  ok: boolean;
20
74
  reason?: string;
21
75
  type?: TokenType;
22
76
  kind?: EventKind;
77
+ /** See ScanResult.sources. */
78
+ sources?: SourceTx[];
79
+ /** true when the event is a mint that no commit in it spends (see ScanResult.unauthenticated). */
80
+ unauthenticated?: boolean;
81
+ /** See ScanResult.anchors. */
82
+ anchors?: AnchorRef[];
83
+ /** See ScanResult.offChainOnly. */
84
+ offChainOnly?: OffChainOnlyTx[];
23
85
  }
86
+ /** An event tx: a Transaction, raw tx hex, or BEEF (hex / bytes: Atomic BEEF over BEEF V2) whose subject is the tx. */
87
+ export type TxInput = Transaction | string | Uint8Array;
24
88
  /**
25
- * Verify ONE token event — a mint, a commit->settle pair, or a melt. Categorises each tx by its
26
- * token's txoType action, fingerprints EVERY interface against the action's golden shape, and (for
27
- * a commit+settle pair) checks the settle links back to the commit via parentOutpoint.
89
+ * Verify ONE token event - a commit->settle pair or a melt (a mint is accepted only with the commit that spends
90
+ * it). Categorises each tx by its token's txoType action, fingerprints EVERY interface against the action's
91
+ * golden shape, checks the settle links back to the commit, then takes its verdict from the same scan as
92
+ * verifyEvents: the anchor step, pairing, sources and script execution all apply, and `anchors` names what the
93
+ * caller must broadcast. A lone commit or a lone settle is NOT an event.
28
94
  */
29
- export declare function verifyEvent(eventTxs: (Transaction | string)[], opts?: ScanOpts): EventResult;
95
+ export declare function verifyEvent(eventTxs: TxInput[], opts?: ScanOpts): EventResult;
30
96
  /**
31
97
  * Verify a BATCH of transactional events end to end. The multistep inspection: recognise the type,
32
98
  * pin the issuer across every token output in the batch, fingerprint every tx's interface
33
99
  * arrangement, then pair the events — every commit (txoType 21/23/25) must be matched by a settle
34
100
  * that links back via parentOutpoint, and every settle must link to a commit in the batch. A lone
35
- * mint (genesis) or melt (terminal) is a valid single-tx event.
101
+ * melt (terminal) is a valid single-tx event; a MINT must be spent by a commit in the batch, else the
102
+ * result is `unauthenticated: true` (a mint alone does not prove the sender holds the issuer key).
103
+ * The batch's ANCHORS (settle N-1 / the mint) are validated with it and named in `anchors`; this function is offline,
104
+ * so the caller still has to broadcast them (verifyAndBroadcast does both).
105
+ */
106
+ export declare function verifyEvents(txsIn: TxInput[], opts?: ScanOpts): ScanResult;
107
+ /**
108
+ * verifyEvents, then BROADCAST every anchor through the caller's broadcaster. The batch is accepted only when the
109
+ * offline verdict is ok AND the network accepted (or had already seen) each anchor: that shows the tx the batch
110
+ * stands on exists and that a node accepted its scripts and its ancestry. Nothing is broadcast when the offline
111
+ * verdict fails. A rejected anchor, a throwing broadcaster or an unknown status all fail closed.
36
112
  */
37
- export declare function verifyEvents(txsIn: (Transaction | string)[], opts?: ScanOpts): ScanResult;
113
+ export declare function verifyAndBroadcast(txsIn: TxInput[], broadcastAnchor: AnchorBroadcaster, opts?: ScanOpts & {
114
+ chainTracker?: HeaderSource;
115
+ }): Promise<ScanResult>;