@neuraiproject/neurai-scripts 0.1.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/LICENSE +21 -0
- package/README.md +546 -0
- package/dist/address.d.ts +31 -0
- package/dist/core/bytes.d.ts +10 -0
- package/dist/core/index.d.ts +5 -0
- package/dist/core/opcodes.d.ts +145 -0
- package/dist/core/script-builder.d.ts +46 -0
- package/dist/core/script-parser.d.ts +35 -0
- package/dist/covenants/index.d.ts +1 -0
- package/dist/covenants/partial-fill/index.d.ts +6 -0
- package/dist/covenants/partial-fill/parse-pq.d.ts +14 -0
- package/dist/covenants/partial-fill/parse.d.ts +15 -0
- package/dist/covenants/partial-fill/script-pq.d.ts +31 -0
- package/dist/covenants/partial-fill/script.d.ts +37 -0
- package/dist/covenants/partial-fill/spend-pq.d.ts +23 -0
- package/dist/covenants/partial-fill/spend.d.ts +40 -0
- package/dist/entries/browser.d.ts +1 -0
- package/dist/entries/global.d.ts +2 -0
- package/dist/entries/index.d.ts +1 -0
- package/dist/index.d.ts +9 -0
- package/dist/standard/authscript.d.ts +88 -0
- package/dist/standard/index.d.ts +9 -0
- package/dist/standard/multisig.d.ts +26 -0
- package/dist/standard/nulldata.d.ts +15 -0
- package/dist/standard/p2pkh.d.ts +5 -0
- package/dist/standard/p2wpkh.d.ts +8 -0
- package/dist/standard/p2wsh.d.ts +9 -0
- package/dist/types.d.ts +122 -0
- package/package.json +69 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 NeuraiProject
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,546 @@
|
|
|
1
|
+
# @neuraiproject/neurai-scripts
|
|
2
|
+
|
|
3
|
+
Script-assembly library for Neurai. Provides:
|
|
4
|
+
|
|
5
|
+
- **Core primitives** — opcode constants, `ScriptBuilder`, byte/hex helpers.
|
|
6
|
+
- **Standard scripts** — P2PKH, P2WPKH, P2WSH, AuthScript (+ witness
|
|
7
|
+
builders for legacy ECDSA / PQ ML-DSA-44 / NoAuth / NIP-015 ref spends),
|
|
8
|
+
OP_RETURN null-data, classic m-of-n multisig + P2SH wrapper.
|
|
9
|
+
- **Covenants** — partial-fill sell-order covenant (legacy and PQ variants)
|
|
10
|
+
targeting the **DePIN-Test** opcode set (`OP_OUTPUTSCRIPT`,
|
|
11
|
+
`OP_OUTPUTVALUE`, `OP_OUTPUTASSETFIELD`, `OP_INPUTASSETFIELD`,
|
|
12
|
+
`OP_TXFIELD`, `OP_CHECKTEMPLATEVERIFY`, `OP_CHECKSIGFROMSTACK`, 64-bit
|
|
13
|
+
`OP_MUL`/`OP_SUB`, …).
|
|
14
|
+
|
|
15
|
+
This is the canonical place to add new Neurai script builders; callers
|
|
16
|
+
compose transactions with
|
|
17
|
+
[`@neuraiproject/neurai-create-transaction`](https://www.npmjs.com/package/@neuraiproject/neurai-create-transaction)
|
|
18
|
+
and sign with
|
|
19
|
+
[`@neuraiproject/neurai-sign-transaction`](https://www.npmjs.com/package/@neuraiproject/neurai-sign-transaction).
|
|
20
|
+
|
|
21
|
+
> ⚠️ DePIN-Test opcodes, `OP_CHECKSIGFROMSTACK`, `OP_TXHASH`, and `vrefin`
|
|
22
|
+
> are gated by consensus flags active in **testnet / regtest** today.
|
|
23
|
+
> Mainnet activation follows the fork process described in the NIPs. The
|
|
24
|
+
> library accepts both `xna-test` and `xna` networks so the same call sites
|
|
25
|
+
> work once mainnet activates.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install @neuraiproject/neurai-scripts
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Build from source:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install
|
|
39
|
+
npm run build
|
|
40
|
+
npm test
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Three bundles are produced under `dist/`:
|
|
44
|
+
|
|
45
|
+
| File | Target |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `dist/index.js` / `index.cjs` | Node (ESM / CJS) |
|
|
48
|
+
| `dist/browser.js` | Browser ESM |
|
|
49
|
+
| `dist/NeuraiScripts.global.js` | IIFE global (`window.NeuraiScripts`) |
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Module layout
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
src/
|
|
57
|
+
├── core/ Low-level primitives
|
|
58
|
+
│ ├── opcodes.ts Opcode bytes + TXFIELD / TXHASH / ASSETFIELD selectors
|
|
59
|
+
│ ├── script-builder.ts CScriptNum encoding, pushBytes/Int/Hex, ScriptBuilder
|
|
60
|
+
│ ├── bytes.ts Hex ↔ Uint8Array helpers (ensureHex, hexToBytes, …)
|
|
61
|
+
│ └── index.ts Barrel
|
|
62
|
+
├── standard/ Standard scripts
|
|
63
|
+
│ ├── p2pkh.ts encodeP2PKHScriptPubKey
|
|
64
|
+
│ ├── p2wpkh.ts encodeP2WPKHScriptPubKey
|
|
65
|
+
│ ├── p2wsh.ts encodeP2WSHScriptPubKey
|
|
66
|
+
│ ├── authscript.ts encodeAuthScriptScriptPubKey + witness builders
|
|
67
|
+
│ ├── nulldata.ts encodeNullDataScript (OP_RETURN)
|
|
68
|
+
│ ├── multisig.ts encodeMultisigRedeemScript / encodeP2SHScriptPubKey
|
|
69
|
+
│ └── index.ts Barrel
|
|
70
|
+
├── covenants/ Covenant scripts
|
|
71
|
+
│ ├── partial-fill/ Legacy (ECDSA cancel) + PQ (ML-DSA-44 via CSFS)
|
|
72
|
+
│ └── index.ts Barrel
|
|
73
|
+
├── address.ts encodeSellerScriptPubKey (bech32m / base58check → spk)
|
|
74
|
+
├── types.ts Public types
|
|
75
|
+
├── entries/ Rollup entry points (node / browser / IIFE)
|
|
76
|
+
└── index.ts Public API
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
All exports are available from the top-level entry:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import { ScriptBuilder, opcodes, encodeP2WPKHScriptPubKey, buildPartialFillScriptHex }
|
|
83
|
+
from '@neuraiproject/neurai-scripts';
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Core primitives
|
|
89
|
+
|
|
90
|
+
### Opcode constants (`./core/opcodes.ts`)
|
|
91
|
+
|
|
92
|
+
Complete coverage of the classic Script opcodes (push values, control,
|
|
93
|
+
stack, arithmetic, bitwise, crypto) plus every DePIN-Test addition
|
|
94
|
+
(`OP_CHECKTEMPLATEVERIFY`, `OP_CHECKSIGFROMSTACK`, `OP_TXHASH`,
|
|
95
|
+
`OP_TXFIELD`, `OP_TXLOCKTIME`, `OP_OUTPUTVALUE`, `OP_OUTPUTSCRIPT`,
|
|
96
|
+
`OP_INPUTCOUNT`/`OP_OUTPUTCOUNT`, `OP_OUTPUTASSETFIELD`,
|
|
97
|
+
`OP_INPUTASSETFIELD`, `OP_REFINPUTCOUNT`/`OP_REFINPUTFIELD`/
|
|
98
|
+
`OP_REFINPUTASSETFIELD`, `OP_CAT`, `OP_SPLIT`, `OP_REVERSEBYTES`, 64-bit
|
|
99
|
+
`OP_MUL`/`OP_DIV`/`OP_MOD`).
|
|
100
|
+
|
|
101
|
+
Also exports selector tables:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
// For OP_TXFIELD and OP_REFINPUTFIELD
|
|
105
|
+
opcodes.TXFIELD_VALUE // 0x01
|
|
106
|
+
opcodes.TXFIELD_AUTHSCRIPT_COMMITMENT // 0x02
|
|
107
|
+
opcodes.TXFIELD_SCRIPTPUBKEY // 0x03
|
|
108
|
+
|
|
109
|
+
// For OP_OUTPUTASSETFIELD / OP_INPUTASSETFIELD / OP_REFINPUTASSETFIELD
|
|
110
|
+
opcodes.ASSETFIELD_NAME // 0x01
|
|
111
|
+
opcodes.ASSETFIELD_AMOUNT // 0x02
|
|
112
|
+
opcodes.ASSETFIELD_UNITS // 0x03
|
|
113
|
+
opcodes.ASSETFIELD_REISSUABLE // 0x04
|
|
114
|
+
opcodes.ASSETFIELD_HAS_IPFS // 0x05
|
|
115
|
+
opcodes.ASSETFIELD_IPFS_HASH // 0x06
|
|
116
|
+
opcodes.ASSETFIELD_TYPE // 0x07
|
|
117
|
+
|
|
118
|
+
// Bitmask selectors for OP_TXHASH (any non-zero combination is valid)
|
|
119
|
+
opcodes.TXHASH_VERSION // 0x01
|
|
120
|
+
opcodes.TXHASH_LOCKTIME // 0x02
|
|
121
|
+
opcodes.TXHASH_INPUT_PREVOUTS // 0x04
|
|
122
|
+
opcodes.TXHASH_INPUT_SEQUENCES // 0x08
|
|
123
|
+
opcodes.TXHASH_OUTPUTS // 0x10
|
|
124
|
+
opcodes.TXHASH_CURRENT_PREVOUT // 0x20
|
|
125
|
+
opcodes.TXHASH_CURRENT_SEQUENCE // 0x40
|
|
126
|
+
opcodes.TXHASH_CURRENT_INDEX // 0x80
|
|
127
|
+
opcodes.TXHASH_ALL // 0xff
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### `ScriptBuilder` (`./core/script-builder.ts`)
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
import { ScriptBuilder, opcodes } from '@neuraiproject/neurai-scripts';
|
|
134
|
+
|
|
135
|
+
const script = new ScriptBuilder()
|
|
136
|
+
.op(opcodes.OP_DUP, opcodes.OP_HASH160)
|
|
137
|
+
.pushBytes(pkh20)
|
|
138
|
+
.op(opcodes.OP_EQUALVERIFY, opcodes.OP_CHECKSIG)
|
|
139
|
+
.build(); // Uint8Array
|
|
140
|
+
// or .buildHex() → string
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Also exported atomically: `pushBytes(data)`, `pushInt(value)`,
|
|
144
|
+
`pushHex(hex)`, `encodeScriptNum(value)`.
|
|
145
|
+
|
|
146
|
+
Push elements up to **3072 bytes** (NIP-18 cap when `CSFS` is active).
|
|
147
|
+
Larger pushes throw; legacy scripts should stay under 520 bytes per push.
|
|
148
|
+
|
|
149
|
+
### Byte helpers (`./core/bytes.ts`)
|
|
150
|
+
|
|
151
|
+
`ensureHex`, `hexToBytes`, `bytesToHex`, `concatBytes`, `bytesEqual`.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Standard scripts
|
|
156
|
+
|
|
157
|
+
All encoders return raw `Uint8Array` bytes. Caller supplies the pre-hashed
|
|
158
|
+
inputs where applicable (we don't bake a crypto dep into this library).
|
|
159
|
+
|
|
160
|
+
### P2PKH — `encodeP2PKHScriptPubKey(pkh20)`
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
import { encodeP2PKHScriptPubKey } from '@neuraiproject/neurai-scripts';
|
|
164
|
+
// OP_DUP OP_HASH160 0x14 <pkh> OP_EQUALVERIFY OP_CHECKSIG (25 bytes)
|
|
165
|
+
const spk = encodeP2PKHScriptPubKey(pubKeyHash20);
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### P2WPKH — `encodeP2WPKHScriptPubKey(pkh20)`
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
// OP_0 0x14 <pkh> (22 bytes)
|
|
172
|
+
const spk = encodeP2WPKHScriptPubKey(pubKeyHash20);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### P2WSH — `encodeP2WSHScriptPubKey(witnessScriptSha256)`
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
// OP_0 0x20 <SHA256(witnessScript)> (34 bytes)
|
|
179
|
+
// Compute SHA256 via your crypto stack (not bundled here).
|
|
180
|
+
const spk = encodeP2WSHScriptPubKey(sha256(witnessScript));
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### AuthScript — `encodeAuthScriptScriptPubKey(program32)` + witness builders
|
|
184
|
+
|
|
185
|
+
`scriptPubKey` layout: `OP_1 0x20 <32-byte program>`.
|
|
186
|
+
|
|
187
|
+
Four spend modes, selected by a 1-byte `auth_type` in the witness stack:
|
|
188
|
+
|
|
189
|
+
| Constant | Value | Meaning |
|
|
190
|
+
|---|---|---|
|
|
191
|
+
| `AUTHSCRIPT_NOAUTH` | `0x00` | No signature — gated by witnessScript alone |
|
|
192
|
+
| `AUTHSCRIPT_PQ` | `0x01` | ML-DSA-44 (post-quantum) |
|
|
193
|
+
| `AUTHSCRIPT_LEGACY` | `0x02` | secp256k1 ECDSA |
|
|
194
|
+
| `AUTHSCRIPT_REF` | `0x03` | NIP-015 reference-script spend (future) |
|
|
195
|
+
|
|
196
|
+
Witness-stack builders return `Uint8Array[]` — the array of raw stack
|
|
197
|
+
elements. Serialization into the transaction witness (compact-size +
|
|
198
|
+
length-prefixes) is done at tx-assembly time by
|
|
199
|
+
`neurai-create-transaction`.
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
import {
|
|
203
|
+
encodeAuthScriptScriptPubKey,
|
|
204
|
+
buildAuthScriptWitnessLegacy,
|
|
205
|
+
buildAuthScriptWitnessPQ,
|
|
206
|
+
buildAuthScriptWitnessNoAuth,
|
|
207
|
+
buildAuthScriptWitnessRef
|
|
208
|
+
} from '@neuraiproject/neurai-scripts';
|
|
209
|
+
|
|
210
|
+
// Output spk
|
|
211
|
+
const spk = encodeAuthScriptScriptPubKey(program32);
|
|
212
|
+
|
|
213
|
+
// Legacy spend: [0x02, sig, pubkey, ...args, witnessScript]
|
|
214
|
+
const stackLegacy = buildAuthScriptWitnessLegacy({
|
|
215
|
+
signature: derSigWithSighash,
|
|
216
|
+
pubKey: compressedSecp256k1,
|
|
217
|
+
args: [],
|
|
218
|
+
witnessScript
|
|
219
|
+
});
|
|
220
|
+
|
|
221
|
+
// PQ spend (requires NIP-18): [0x01, sig(~2421 B), pubkey(~1313 B), ...args, witnessScript]
|
|
222
|
+
const stackPQ = buildAuthScriptWitnessPQ({
|
|
223
|
+
signature: mlDsa44SigWithSighash,
|
|
224
|
+
pubKey: versionedPqPubKey,
|
|
225
|
+
args: [],
|
|
226
|
+
witnessScript
|
|
227
|
+
});
|
|
228
|
+
|
|
229
|
+
// NoAuth (pure covenant): [0x00, ...args, witnessScript]
|
|
230
|
+
const stackNoAuth = buildAuthScriptWitnessNoAuth({ args, witnessScript });
|
|
231
|
+
|
|
232
|
+
// NIP-015 reference-script spend: [0x03, ...args, uint32LE(refIndex)]
|
|
233
|
+
const stackRef = buildAuthScriptWitnessRef({ refIndex: 2, args });
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Null-data (OP_RETURN) — `encodeNullDataScript(payload, options?)`
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
import { encodeNullDataScript } from '@neuraiproject/neurai-scripts';
|
|
240
|
+
|
|
241
|
+
// OP_RETURN <push>
|
|
242
|
+
const spk = encodeNullDataScript(someBytes);
|
|
243
|
+
|
|
244
|
+
// Multi-push payload
|
|
245
|
+
const spk2 = encodeNullDataScript([tagBytes, messageBytes]);
|
|
246
|
+
|
|
247
|
+
// Oversize (> 80 B) needs an explicit opt-in
|
|
248
|
+
const big = encodeNullDataScript(huge, { allowNonStandard: true });
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
`NULLDATA_STANDARD_MAX_SIZE = 80` (Neurai's mempool-relay cap inherited
|
|
252
|
+
from Bitcoin Core). Outputs over that are consensus-valid but not relayed
|
|
253
|
+
unless nodes run with `-acceptnonstdtxn=1`.
|
|
254
|
+
|
|
255
|
+
### Multisig — `encodeMultisigRedeemScript` + `encodeP2SHScriptPubKey`
|
|
256
|
+
|
|
257
|
+
Classic bare multisig is consensus-valid but non-standard for relay in
|
|
258
|
+
Neurai today. Typical usage wraps the redeem script in P2SH.
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
import {
|
|
262
|
+
encodeMultisigRedeemScript,
|
|
263
|
+
encodeP2SHScriptPubKey,
|
|
264
|
+
MULTISIG_MAX_PUBKEYS // 20
|
|
265
|
+
} from '@neuraiproject/neurai-scripts';
|
|
266
|
+
|
|
267
|
+
const redeemScript = encodeMultisigRedeemScript({
|
|
268
|
+
m: 2,
|
|
269
|
+
pubKeys: [pk1, pk2, pk3] // each 33 or 65 bytes
|
|
270
|
+
});
|
|
271
|
+
// <2> <pk1> <pk2> <pk3> <3> OP_CHECKMULTISIG
|
|
272
|
+
|
|
273
|
+
// Wrap in P2SH (callers compute HASH160 externally):
|
|
274
|
+
const scriptPubKey = encodeP2SHScriptPubKey(hash160(redeemScript));
|
|
275
|
+
// OP_HASH160 0x14 <h160> OP_EQUAL
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## Covenants
|
|
281
|
+
|
|
282
|
+
### Partial-Fill Sell Order
|
|
283
|
+
|
|
284
|
+
A partial-fill sell order lets a seller publish a lot of tokens at a
|
|
285
|
+
fixed price and lets any number of buyers take arbitrary fractions of
|
|
286
|
+
that lot without the seller having to come back online for each sale.
|
|
287
|
+
The covenant that guards the seller's output is the only rulebook: the
|
|
288
|
+
spending transaction is valid only if it pays the seller the correct XNA
|
|
289
|
+
amount, delivers the right asset quantity to the buyer, and forwards the
|
|
290
|
+
remainder into a new UTXO carrying the same covenant script. No
|
|
291
|
+
custodial DEX, no off-chain matching, no second signature from the
|
|
292
|
+
seller.
|
|
293
|
+
|
|
294
|
+
The covenant is **stateful via UTXO continuity**. The output at `vout[2]`
|
|
295
|
+
of every fill must carry the same `scriptPubKey` as the input being
|
|
296
|
+
spent (enforced on the fly by `OP_OUTPUTSCRIPT == OP_TXFIELD 0x03`), so
|
|
297
|
+
the covenant self-replicates without hardcoding its own hash. The
|
|
298
|
+
remaining asset quantity is read directly from the input via
|
|
299
|
+
`OP_INPUTASSETFIELD` and the subtraction `inputAmount − N` is verified,
|
|
300
|
+
so the same script works for any remainder as the lot drains. Asset
|
|
301
|
+
name, buyer amount, payment destination script and payment value are all
|
|
302
|
+
checked against the covenant's hardcoded parameters using
|
|
303
|
+
`OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
|
|
304
|
+
enforces every rule; there is no trusted off-chain layer.
|
|
305
|
+
|
|
306
|
+
Two spending branches are selected by the top of the unlock stack:
|
|
307
|
+
|
|
308
|
+
- `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
|
|
309
|
+
recovers the remainder. The legacy variant uses ECDSA
|
|
310
|
+
(`OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG`); the PQ variant
|
|
311
|
+
swaps this for `OP_CHECKSIGFROMSTACK` against an ML-DSA-44 signature
|
|
312
|
+
(see *PQ variant* below).
|
|
313
|
+
- `OP_ELSE` (unlock pushed `N` then `0`) — **Public partial fill**. Any
|
|
314
|
+
buyer can spend the UTXO by providing the fill amount `N`; consensus
|
|
315
|
+
validates the whole transaction layout against the embedded price,
|
|
316
|
+
token id, and seller destination. No seller signature is involved.
|
|
317
|
+
|
|
318
|
+
This maps naturally onto Neurai's mempool: multiple buyers can submit
|
|
319
|
+
their fill transactions in sequence, each one building on the previous
|
|
320
|
+
fill's `vout[2]` before confirmation. Neurai's default descendant limit
|
|
321
|
+
of 500 allows long chains of pending fills against a single published
|
|
322
|
+
order, and the whole chain confirms together when the next block is
|
|
323
|
+
mined. If the seller wants to stop the order at any point, she spends
|
|
324
|
+
the current live UTXO via the cancel branch.
|
|
325
|
+
|
|
326
|
+
#### Alice / Bob / Carol flow
|
|
327
|
+
|
|
328
|
+
1. **Alice** locks 100 CAT in a covenant UTXO (`buildPartialFillScript`).
|
|
329
|
+
Price 1 XNA / CAT, P2PKH as payment destination.
|
|
330
|
+
2. **Bob** spends the covenant pushing `<5> <0>` as `scriptSig` and his
|
|
331
|
+
XNA input. The script enforces:
|
|
332
|
+
- `output[0]` pays Alice ≥ `5 * unitPriceSats` XNA
|
|
333
|
+
- `output[1]` is a transfer of 5 CAT to Bob
|
|
334
|
+
- `output[2]` is a new covenant UTXO with **the same** scriptPubKey
|
|
335
|
+
and 95 CAT
|
|
336
|
+
3. **Carol** does the same on the new UTXO, leaving 90 CAT behind.
|
|
337
|
+
4. **Alice** signs the cancel branch on the latest UTXO and recovers her
|
|
338
|
+
remaining 90 CAT. She has already received 10 XNA across Bob's and
|
|
339
|
+
Carol's fills.
|
|
340
|
+
|
|
341
|
+
No second signature from Alice, no custodial server: the covenant script
|
|
342
|
+
is the rulebook.
|
|
343
|
+
|
|
344
|
+
#### Usage (legacy ECDSA cancel)
|
|
345
|
+
|
|
346
|
+
```ts
|
|
347
|
+
import {
|
|
348
|
+
buildPartialFillScriptHex,
|
|
349
|
+
buildFillScriptSigHex,
|
|
350
|
+
buildCancelScriptSigHex,
|
|
351
|
+
parsePartialFillScript
|
|
352
|
+
} from '@neuraiproject/neurai-scripts';
|
|
353
|
+
|
|
354
|
+
// 1) Alice publishes an order for 100 CAT at 1 XNA per CAT.
|
|
355
|
+
const scriptPubKeyHex = buildPartialFillScriptHex({
|
|
356
|
+
sellerAddress: aliceP2PKHAddress, // "t..." on testnet / "N..." on mainnet
|
|
357
|
+
tokenId: 'CAT',
|
|
358
|
+
unitPriceSats: 100_000_000n // 1 XNA = 1e8 sats per indivisible unit
|
|
359
|
+
});
|
|
360
|
+
// Throws if the address is not a legacy P2PKH — the legacy covenant uses
|
|
361
|
+
// OP_HASH160 + OP_CHECKSIG on the cancel branch and cannot commit to an
|
|
362
|
+
// AuthScript program. Use `buildPartialFillScriptPQ` for bech32m / PQ
|
|
363
|
+
// destinations.
|
|
364
|
+
|
|
365
|
+
// 2) Bob spends 5 CAT from the covenant.
|
|
366
|
+
const bobScriptSigHex = buildFillScriptSigHex(5n);
|
|
367
|
+
// Fill-tx layout (built with neurai-create-transaction):
|
|
368
|
+
// vin[0] = covenant UTXO, scriptSig = bobScriptSigHex
|
|
369
|
+
// vin[1+] = buyer's XNA inputs (standard P2PKH, SIGHASH_ALL)
|
|
370
|
+
// vout[0] = unitPriceSats * 5 XNA to Alice
|
|
371
|
+
// vout[1] = 5 CAT to Bob
|
|
372
|
+
// vout[2] = 95 CAT back to the SAME covenant scriptPubKey
|
|
373
|
+
// vout[3+] = buyer change (optional)
|
|
374
|
+
|
|
375
|
+
// 3) Alice cancels on the latest remainder UTXO.
|
|
376
|
+
const aliceCancelSig = /* produced by neurai-sign-transaction, SIGHASH_ALL */;
|
|
377
|
+
const cancelScriptSigHex = buildCancelScriptSigHex(aliceCancelSig, alicePubKey);
|
|
378
|
+
|
|
379
|
+
// 4) The DEX backend indexes active orders by parsing scriptPubKeys.
|
|
380
|
+
for (const utxo of candidateUtxos) {
|
|
381
|
+
try {
|
|
382
|
+
const order = parsePartialFillScript(utxo.scriptPubKeyHex, 'xna-test');
|
|
383
|
+
// order.tokenId, order.unitPriceSats, order.sellerPubKeyHash, order.network
|
|
384
|
+
// The parser returns the 20-byte PKH; base58check-encode with the
|
|
385
|
+
// network's legacy prefix (0x35 mainnet / 0x7f testnet) if you need
|
|
386
|
+
// to display the seller's address.
|
|
387
|
+
} catch {
|
|
388
|
+
// not a partial-fill covenant, skip
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
#### Script layout (legacy)
|
|
394
|
+
|
|
395
|
+
```
|
|
396
|
+
OP_IF
|
|
397
|
+
OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG // cancel branch
|
|
398
|
+
OP_ELSE
|
|
399
|
+
# Stack entering ELSE: [ N ]
|
|
400
|
+
OP_DUP <unitPriceSats> OP_MUL
|
|
401
|
+
<0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
|
|
402
|
+
<0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
|
|
403
|
+
OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
|
|
404
|
+
<1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name == tokenId
|
|
405
|
+
<2> OP_OUTPUTSCRIPT <0x03> OP_TXFIELD OP_EQUALVERIFY // continuity
|
|
406
|
+
<2> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // remainder name
|
|
407
|
+
<2> <0x02> OP_OUTPUTASSETFIELD OP_OVER
|
|
408
|
+
<0> <0x02> OP_INPUTASSETFIELD OP_SWAP OP_SUB OP_EQUALVERIFY // remainder = in - N
|
|
409
|
+
OP_DROP OP_1
|
|
410
|
+
OP_ENDIF
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
#### Limitations of v0.1
|
|
414
|
+
|
|
415
|
+
- **Payment only in XNA.** A `PaymentAsset` selector is planned for v0.2.
|
|
416
|
+
- **No `MinFill` / `MaxFill` / `Expiry`.** Planned for v0.2.
|
|
417
|
+
- **Fixed output layout** (`vout[0..2]`). The covenant rejects
|
|
418
|
+
reorderings. Buyer change must go to `vout[3+]`.
|
|
419
|
+
- **AMM is out of scope.** Covered by a later phase of the NIP roadmap.
|
|
420
|
+
|
|
421
|
+
### Partial-Fill PQ variant (post-quantum seller, NIP-18)
|
|
422
|
+
|
|
423
|
+
With `OP_CHECKSIGFROMSTACK` (`CSFS`) and `OP_TXHASH` active, the cancel
|
|
424
|
+
branch can validate an **ML-DSA-44** signature in place of the classic
|
|
425
|
+
ECDSA `OP_CHECKSIG`. NIP-18 raises the per-element push cap to 3072 B so
|
|
426
|
+
the ~2421 B signature and ~1313 B pubkey fit as stack items. All three
|
|
427
|
+
are active on DePIN-Test testnet.
|
|
428
|
+
|
|
429
|
+
| | Legacy | PQ |
|
|
430
|
+
|---|---|---|
|
|
431
|
+
| Cancel sig scheme | ECDSA secp256k1 | ML-DSA-44 (~2421 B sig, ~1313 B pubkey) |
|
|
432
|
+
| Cancel verifier | `OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG` | `OP_DUP OP_SHA256 <commitment> OP_EQUALVERIFY <selector> OP_TXHASH OP_SWAP OP_CHECKSIGFROMSTACK` |
|
|
433
|
+
| What Alice signs | tx sighash (standard) | `SHA256(OP_TXHASH(selector))` — CSFS single-SHA256s the message |
|
|
434
|
+
| Payment destination | P2PKH only | P2PKH **or** AuthScript bech32m (scriptPubKey bytes hardcoded) |
|
|
435
|
+
|
|
436
|
+
```ts
|
|
437
|
+
import {
|
|
438
|
+
buildPartialFillScriptPQHex,
|
|
439
|
+
buildCancelScriptSigPQHex,
|
|
440
|
+
parsePartialFillScriptPQ,
|
|
441
|
+
isPartialFillScriptPQ,
|
|
442
|
+
DEFAULT_PQ_TXHASH_SELECTOR
|
|
443
|
+
} from '@neuraiproject/neurai-scripts';
|
|
444
|
+
|
|
445
|
+
const scriptPubKeyHex = buildPartialFillScriptPQHex({
|
|
446
|
+
network: 'xna-test',
|
|
447
|
+
paymentAddress: 'tnq1...', // AuthScript bech32m, or legacy "t..." P2PKH
|
|
448
|
+
pubKeyCommitment: sha256(alicePQPubKey), // 32 bytes
|
|
449
|
+
tokenId: 'CAT',
|
|
450
|
+
unitPriceSats: 100_000_000n,
|
|
451
|
+
txHashSelector: DEFAULT_PQ_TXHASH_SELECTOR // 0xff = all eight tx fields
|
|
452
|
+
});
|
|
453
|
+
|
|
454
|
+
const cancelScriptSigHex = buildCancelScriptSigPQHex(mlDsa44SigWithSighash, alicePQPubKey);
|
|
455
|
+
|
|
456
|
+
// Indexers can tell variants apart:
|
|
457
|
+
if (isPartialFillScriptPQ(utxo.scriptPubKeyHex)) {
|
|
458
|
+
const order = parsePartialFillScriptPQ(utxo.scriptPubKeyHex);
|
|
459
|
+
}
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
#### PQ cancel-branch layout
|
|
463
|
+
|
|
464
|
+
```
|
|
465
|
+
OP_IF // scriptSig pushed <sig> <pubKey> OP_1
|
|
466
|
+
OP_DUP OP_SHA256
|
|
467
|
+
<pubKeyCommitment 32B>
|
|
468
|
+
OP_EQUALVERIFY
|
|
469
|
+
<txHashSelector 1B>
|
|
470
|
+
OP_TXHASH // msg = dSHA256(selected_tx_fields)
|
|
471
|
+
OP_SWAP
|
|
472
|
+
OP_CHECKSIGFROMSTACK // verifies sig over SHA256(msg) for pubKey
|
|
473
|
+
OP_ELSE
|
|
474
|
+
... partial-fill branch (identical to legacy) ...
|
|
475
|
+
OP_ENDIF
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
---
|
|
479
|
+
|
|
480
|
+
## Network handling
|
|
481
|
+
|
|
482
|
+
Builders take address strings (whose prefix already encodes the network:
|
|
483
|
+
`t.../N...` for P2PKH, `tnq1.../nq1...` for AuthScript bech32m) and
|
|
484
|
+
validate them via `decodeAddress` from `neurai-create-transaction`. No
|
|
485
|
+
builder accepts a separate `network` parameter — it would be redundant
|
|
486
|
+
with the address and invite silent mismatches.
|
|
487
|
+
|
|
488
|
+
Parsers, on the other hand, do take a `network` argument (default
|
|
489
|
+
`'xna-test'`). The covenant *script bytes themselves do not encode
|
|
490
|
+
network*: a legacy covenant is opcodes plus a 20-byte PKH, a PQ covenant
|
|
491
|
+
is opcodes plus a 32-byte commitment and raw payment-scriptPubKey bytes,
|
|
492
|
+
and neither payload differs between mainnet and testnet. The parser
|
|
493
|
+
receives `network` purely so the caller can later base58-encode
|
|
494
|
+
`sellerPubKeyHash` against the right version byte, or interpret
|
|
495
|
+
`paymentScriptPubKey` in the correct bech32m/base58 context.
|
|
496
|
+
|
|
497
|
+
Keep this split intact when adding new covenants: builders reject a
|
|
498
|
+
`network` field, parsers echo it through.
|
|
499
|
+
|
|
500
|
+
---
|
|
501
|
+
|
|
502
|
+
## Consensus / policy notes
|
|
503
|
+
|
|
504
|
+
- **DePIN-Test opcodes are consensus-gated.** Each one is behind an
|
|
505
|
+
individual flag (`nCTVEnabled`, `nCSFSEnabled`, `nTXHASHEnabled`,
|
|
506
|
+
`nTXFIELDEnabled`, `nOUTPUTVALUEEnabled`, `nOUTPUTSCRIPTEnabled`,
|
|
507
|
+
`nOUTPUTASSETFIELDEnabled`, `nINPUTASSETFIELDEnabled`,
|
|
508
|
+
`nINPUTOUTPUTCOUNTEnabled`, `nREFINPUTSEnabled`, `nCATEnabled`,
|
|
509
|
+
`nSPLITEnabled`, `nREVERSEBYTESEnabled`, `n64BitIntegersEnabled`,
|
|
510
|
+
`nTXLOCKTIMEEnabled`, `nPQWitnessEnabled`). All are **true** on testnet
|
|
511
|
+
and regtest, **false** on mainnet until each NIP's fork process lands.
|
|
512
|
+
- **NIP-18 per-element cap (3072 B) is also a mempool-policy win.**
|
|
513
|
+
Neurai's `MAX_CSFS_STANDARD_P2WSH_STACK_ITEM_SIZE` equals the consensus
|
|
514
|
+
cap whenever CSFS is active, so PQ witness items are standard on the
|
|
515
|
+
testnet today — no `-acceptnonstdtxn=1` required. The legacy 80 B cap
|
|
516
|
+
only applies when CSFS is off.
|
|
517
|
+
- **Commitment choice (PQ).** The PQ covenant commits to
|
|
518
|
+
`SHA256(pubKey)`, not the witness-v1 bech32m program. That keeps the
|
|
519
|
+
covenant decoupled from AuthScript address derivation and lets the
|
|
520
|
+
caller use any PQ key whose SHA256 they can compute.
|
|
521
|
+
|
|
522
|
+
---
|
|
523
|
+
|
|
524
|
+
## Adding new scripts to this library
|
|
525
|
+
|
|
526
|
+
The layout under `src/standard/` and `src/covenants/` is designed for
|
|
527
|
+
expansion. When adding a new primitive:
|
|
528
|
+
|
|
529
|
+
- **Standard scripts** (P2*, OP_RETURN, new address formats, …) go under
|
|
530
|
+
`src/standard/`. Keep one file per scheme and export from
|
|
531
|
+
`src/standard/index.ts`.
|
|
532
|
+
- **Covenants** (batch-fill, shared-claim, HTLC, vaults, AMM, …) go under
|
|
533
|
+
`src/covenants/<name>/` with the same `script.ts` / `spend.ts` /
|
|
534
|
+
`parse.ts` split the partial-fill module uses. Re-export from
|
|
535
|
+
`src/covenants/index.ts`.
|
|
536
|
+
- **Reference-script carriers / NIP-015 helpers** will land in a future
|
|
537
|
+
`src/reference-scripts/` directory when the NIP activates.
|
|
538
|
+
|
|
539
|
+
The top-level `src/index.ts` barrel should re-export everything publicly
|
|
540
|
+
consumable; callers import directly from the package root.
|
|
541
|
+
|
|
542
|
+
---
|
|
543
|
+
|
|
544
|
+
## License
|
|
545
|
+
|
|
546
|
+
MIT — same terms as the rest of the `@neuraiproject/*` libraries.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Address helpers. Wraps `decodeAddress` from
|
|
3
|
+
* `@neuraiproject/neurai-create-transaction` to produce the exact
|
|
4
|
+
* scriptPubKey bytes a covenant needs to hardcode. The actual
|
|
5
|
+
* scriptPubKey encoders live in `./standard/*`; this module delegates.
|
|
6
|
+
*
|
|
7
|
+
* Two destination types are supported for the payment output (output[0]):
|
|
8
|
+
* - Legacy P2PKH (base58check)
|
|
9
|
+
* - AuthScript witness v1 (bech32m)
|
|
10
|
+
*/
|
|
11
|
+
import { encodeP2PKHScriptPubKey } from './standard/p2pkh.js';
|
|
12
|
+
import { encodeAuthScriptScriptPubKey } from './standard/authscript.js';
|
|
13
|
+
export type SellerAddressKind = 'p2pkh' | 'authscript';
|
|
14
|
+
export interface SellerScriptPubKey {
|
|
15
|
+
kind: SellerAddressKind;
|
|
16
|
+
/** Raw scriptPubKey bytes that output[0] of a fill tx must equal. */
|
|
17
|
+
bytes: Uint8Array;
|
|
18
|
+
/**
|
|
19
|
+
* Address-specific hash: 20-byte PKH for P2PKH, 32-byte program for
|
|
20
|
+
* AuthScript. Used by the cancel branch (either as the HASH160 target or
|
|
21
|
+
* as the SHA256(pubKey) commitment).
|
|
22
|
+
*/
|
|
23
|
+
hash: Uint8Array;
|
|
24
|
+
}
|
|
25
|
+
export { encodeP2PKHScriptPubKey, encodeAuthScriptScriptPubKey };
|
|
26
|
+
/**
|
|
27
|
+
* Resolve any accepted seller address string into its scriptPubKey.
|
|
28
|
+
* The returned bytes are what the covenant will hardcode and later verify
|
|
29
|
+
* via `OP_OUTPUTSCRIPT == <bytes>`.
|
|
30
|
+
*/
|
|
31
|
+
export declare function encodeSellerScriptPubKey(address: string): SellerScriptPubKey;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Minimal byte helpers. A subset of what `neurai-create-transaction` exposes,
|
|
3
|
+
* duplicated here to keep this package free of runtime coupling beyond its
|
|
4
|
+
* declared `dependencies` field. All sizes are little-endian, per Neurai.
|
|
5
|
+
*/
|
|
6
|
+
export declare function ensureHex(hex: string, label?: string): string;
|
|
7
|
+
export declare function hexToBytes(hex: string): Uint8Array;
|
|
8
|
+
export declare function bytesToHex(bytes: Uint8Array): string;
|
|
9
|
+
export declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
|
|
10
|
+
export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { ensureHex, hexToBytes, bytesToHex, concatBytes, bytesEqual } from './bytes.js';
|
|
2
|
+
export { ScriptBuilder, encodeScriptNum, pushBytes, pushInt, pushHex } from './script-builder.js';
|
|
3
|
+
export * as opcodes from './opcodes.js';
|
|
4
|
+
export { makeCursor, expectByte, assertTrailing, readPush, readPushPositiveInt, decodeScriptNum } from './script-parser.js';
|
|
5
|
+
export type { Cursor } from './script-parser.js';
|