@neuraiproject/neurai-scripts 0.4.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
@@ -307,17 +307,24 @@ checked against the covenant's hardcoded parameters using
307
307
  `OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
308
308
  enforces every rule; there is no trusted off-chain layer.
309
309
 
310
- 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:
311
311
 
312
312
  - `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
313
313
  recovers the remainder. The legacy variant uses ECDSA
314
314
  (`OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG`); the PQ variant
315
315
  swaps this for `OP_CHECKSIGFROMSTACK` against an ML-DSA-44 signature
316
316
  (see *PQ variant* below).
317
- - `OP_ELSE` (unlock pushed `N` then `0`) — **Public partial fill**. Any
318
- buyer can spend the UTXO by providing the fill amount `N`; consensus
319
- validates the whole transaction layout against the embedded price,
320
- 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.
321
328
 
322
329
  This maps naturally onto Neurai's mempool: multiple buyers can submit
323
330
  their fill transactions in sequence, each one building on the previous
@@ -394,23 +401,34 @@ for (const utxo of candidateUtxos) {
394
401
  }
395
402
  ```
396
403
 
397
- #### Script layout (legacy)
404
+ #### Script layout (legacy, three-branch)
398
405
 
399
406
  ```
400
- OP_IF
401
- 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
402
409
  OP_ELSE
403
- # Stack entering ELSE: [ N ]
404
- OP_DUP <unitPriceSats> OP_MUL
405
- <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
406
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
407
- OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
408
- <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name == tokenId
409
- <2> OP_OUTPUTAUTHCOMMITMENT <0x02> OP_TXFIELD OP_EQUALVERIFY // continuity (NIP-023)
410
- <2> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // remainder name
411
- <2> <0x02> OP_OUTPUTASSETFIELD OP_OVER
412
- <0> <0x02> OP_INPUTASSETFIELD OP_SWAP OP_SUB OP_EQUALVERIFY // remainder = in - N
413
- 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
414
432
  OP_ENDIF
415
433
  ```
416
434