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.
- package/CHANGELOG.md +568 -39
- package/LICENSE.txt +56 -56
- package/README.md +310 -206
- package/dist/index.d.ts +15 -7
- package/dist/index.js +14 -5
- package/dist/lib/boltLib.d.ts +29 -3
- package/dist/lib/boltLib.js +60 -12
- package/dist/lib/genesis.d.ts +20 -0
- package/dist/lib/genesis.js +45 -0
- package/dist/lib/multi/multiBoltLib.d.ts +22 -2
- package/dist/lib/multi/multiBoltLib.js +114 -129
- package/dist/lib/scanner/beef.d.ts +11 -0
- package/dist/lib/scanner/beef.js +63 -0
- package/dist/lib/scanner/fingerprints.d.ts +12 -2
- package/dist/lib/scanner/fingerprints.js +45 -12
- package/dist/lib/scanner/verifyEvents.d.ts +84 -6
- package/dist/lib/scanner/verifyEvents.js +520 -45
- package/dist/lib/single/singleAncestor.d.ts +27 -3
- package/dist/lib/single/singleAncestor.js +49 -18
- package/dist/lib/single/singleSpend.d.ts +12 -3
- package/dist/lib/single/singleSpend.js +48 -16
- package/dist/tokens/BOLT.d.ts +6 -5
- package/dist/tokens/GenesisMultiBOLT.d.ts +29 -0
- package/dist/tokens/GenesisMultiBOLT.js +48 -0
- package/dist/tokens/MultiBOLT.d.ts +17 -12
- package/dist/tokens/MultiBOLT.js +82 -74
- package/dist/tokens/templates/AuthBolt.sx.template.d.ts +35 -0
- package/dist/tokens/templates/AuthBolt.sx.template.js +82 -0
- package/dist/tokens/templates/FixedMulti.sx.template.d.ts +13 -0
- package/dist/tokens/templates/FixedMulti.sx.template.js +23 -0
- package/dist/tokens/templates/MinSimple.sx.template.d.ts +10 -1
- package/dist/tokens/templates/MinSimple.sx.template.js +15 -1
- package/dist/tokens/templates/OpenMulti.sx.template.d.ts +13 -0
- package/dist/tokens/templates/OpenMulti.sx.template.js +23 -0
- package/dist/tokens/templates/SerialBolt.sx.template.d.ts +23 -0
- package/dist/tokens/templates/SerialBolt.sx.template.js +61 -0
- package/dist/tokens/templates/SimpleMulti.sx.template.d.ts +12 -6
- package/dist/tokens/templates/SimpleMulti.sx.template.js +33 -25
- package/dist/tokens/templates/pay2Proof.d.ts +2 -1
- package/dist/tokens/templates/pay2Proof.js +1 -1
- package/package.json +64 -58
- package/dist/tokens/templates/MinSimpleBalance.sx.template.d.ts +0 -24
- package/dist/tokens/templates/MinSimpleBalance.sx.template.js +0 -59
- package/dist/tokens/templates/MinSimpleDiscount.sx.template.d.ts +0 -23
- 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
|
|
26
|
-
* token's txoType action, fingerprints EVERY interface against the action's
|
|
27
|
-
*
|
|
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:
|
|
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
|
-
*
|
|
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
|
|
113
|
+
export declare function verifyAndBroadcast(txsIn: TxInput[], broadcastAnchor: AnchorBroadcaster, opts?: ScanOpts & {
|
|
114
|
+
chainTracker?: HeaderSource;
|
|
115
|
+
}): Promise<ScanResult>;
|