@neuraiproject/neurai-scripts 0.3.0 → 0.5.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/README.md CHANGED
@@ -292,9 +292,13 @@ custodial DEX, no off-chain matching, no second signature from the
292
292
  seller.
293
293
 
294
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
295
+ of every fill must carry the same AuthScript v1 commitment as the input
296
+ being spent (enforced on the fly by
297
+ `OP_OUTPUTAUTHCOMMITMENT == OP_TXFIELD 0x02`, NIP-023), so the covenant
298
+ self-replicates without hardcoding its own hash. Earlier drafts compared
299
+ full scriptPubKeys via `OP_OUTPUTSCRIPT`, but that is unsatisfiable on
300
+ asset-wrapped covenant UTXOs because the remainder's asset wrapper
301
+ encodes a different `amountRaw` than the spent UTXO's. The
298
302
  remaining asset quantity is read directly from the input via
299
303
  `OP_INPUTASSETFIELD` and the subtraction `inputAmount − N` is verified,
300
304
  so the same script works for any remainder as the lot drains. Asset
@@ -303,17 +307,24 @@ checked against the covenant's hardcoded parameters using
303
307
  `OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
304
308
  enforces every rule; there is no trusted off-chain layer.
305
309
 
306
- Two spending branches are selected by the top of the unlock stack:
310
+ Three spending branches are selected by the top of the unlock stack:
307
311
 
308
312
  - `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
309
313
  recovers the remainder. The legacy variant uses ECDSA
310
314
  (`OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG`); the PQ variant
311
315
  swaps this for `OP_CHECKSIGFROMSTACK` against an ML-DSA-44 signature
312
316
  (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
+ - `OP_ELSE OP_IF` (unlock pushed `1 0`) — **Full fill**. Any buyer
318
+ can drain the entire covenant in one transaction. The tx has two
319
+ constrained outputs (`vout[0]` pays the seller, `vout[1]` delivers
320
+ the asset to the buyer) and **no `vout[2]` continuation** — the
321
+ covenant is fully consumed. Required because consensus rejects
322
+ asset transfers with `amount == 0`, so a partial fill that would
323
+ drain the lot is structurally impossible.
324
+ - `OP_ELSE OP_ELSE` (unlock pushed `N 0 0`) — **Partial fill**. Any
325
+ buyer can take `N < total` by providing the fill amount; the
326
+ covenant's `vout[2]` re-locks the remainder (`total − N` units)
327
+ into an identical covenant UTXO. No seller signature is involved.
317
328
 
318
329
  This maps naturally onto Neurai's mempool: multiple buyers can submit
319
330
  their fill transactions in sequence, each one building on the previous
@@ -390,23 +401,34 @@ for (const utxo of candidateUtxos) {
390
401
  }
391
402
  ```
392
403
 
393
- #### Script layout (legacy)
404
+ #### Script layout (legacy, three-branch)
394
405
 
395
406
  ```
396
- OP_IF
397
- OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG // cancel branch
407
+ OP_IF // cancel branch
408
+ OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG
398
409
  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_IF // full-fill branch
411
+ # Stack entering: [ ] (scriptSig pushed <1> <0>)
412
+ <0> <0x02> OP_INPUTASSETFIELD // N = inputAmount
413
+ OP_DUP <unitPriceSats> OP_MUL
414
+ <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
415
+ <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
416
+ OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
417
+ <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
418
+ OP_DROP OP_1 // no vout[2] required
419
+ OP_ELSE // partial-fill branch
420
+ # Stack entering: [ N ] (scriptSig pushed <N> <0> <0>)
421
+ OP_DUP <unitPriceSats> OP_MUL
422
+ <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
423
+ <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
424
+ OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
425
+ <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
426
+ <2> OP_OUTPUTAUTHCOMMITMENT <0x02> OP_TXFIELD OP_EQUALVERIFY // continuity (NIP-023)
427
+ <2> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // remainder name
428
+ <2> <0x02> OP_OUTPUTASSETFIELD OP_OVER
429
+ <0> <0x02> OP_INPUTASSETFIELD OP_SWAP OP_SUB OP_EQUALVERIFY // remainder = in - N
430
+ OP_DROP OP_1
431
+ OP_ENDIF
410
432
  OP_ENDIF
411
433
  ```
412
434