Build and validate an unsigned single-token ALP SEND (EMPP
OP_RETURN + colored outs + optional XEC outs) with atom conservation,
dust, fee exactness, and ALP_POLICY_MAX_OUTPUTS. No signing, Chronik,
coordinator, or chained rounds.
Details
- Reviewers
Fabien - Group Reviewers
Restricted Project - Commits
- rABC5cd3e7536d4a: [alp-fusion] Add offline fused ALP SEND tx assembly
- cd apps/alp-fusion && pnpm test
- Confirm assembleAlpSend happy path parses as EMPP SEND and rejects burn, inflation, >29 outs, mixed tokenIds, and dust/fee errors
Diff Detail
- Repository
- rABC Bitcoin ABC
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) Security by obscurity? I'm about to become very 'unobscure'.
────────────────────────────────────────────────────────────────────────
major [Maintainability & Code Quality]
→ ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:181apps/alp-fusion/src/tx/assemble.ts:181-192]8;;
Duplicate conservation/push computation between validateAlpSendAssembly
and assembleAlpSend.
Both functions independently build the ALP push/EMPP script (Lines 181-186
vs 218-219) and independently sum
inputAtoms/outputAtoms/inputSats/outputSats (Lines 119-160 vs
239-244). Today the results agree, but if either summation loop is
extended later (e.g., a new input/output category) without updating both,
assembleAlpSend could silently return incorrect metadata on an
AssembledAlpSend result even though validation still passes — a real
risk for a token-conservation-critical path.
Consider having validateAlpSendAssembly return the computed aggregates
(or extracting a shared private helper) so assembleAlpSend reuses them
instead of recomputing.
♻️ Sketch of a shared helper
-export function validateAlpSendAssembly(params: AssembleAlpSendParams): void {
+interface AlpSendPlan {
+ inputAtoms: bigint;
+ outputAtoms: bigint;
+ inputSats: bigint;
+ outputSats: bigint;
+ alpPush: Script;
+}
+
+function planAlpSendAssembly(params: AssembleAlpSendParams): AlpSendPlan {
...
- const push = alpSend(
- params.tokenId,
- ALP_STANDARD,
- tokenOutputs.map(o => o.atoms),
- );
- const opreturn = emppScript([push]);
+ const push = alpSend(
+ params.tokenId,
+ ALP_STANDARD,
+ tokenOutputs.map(o => o.atoms),
+ );
+ const opreturn = emppScript([push]);
if (opreturn.bytecode.length > OP_RETURN_MAX_BYTES) {
throw new Error(...);
}
+ return { inputAtoms, outputAtoms, inputSats, outputSats, alpPush: push };
+}
+
+export function validateAlpSendAssembly(params: AssembleAlpSendParams): void {
+ planAlpSendAssembly(params);
}
Also applies to: 216-244────────────────────────────────────────
Review complete
1 finding ✔
Major 1
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) The only good bug is a dead bug.
────────────────────────────────────────────────────────────────────────
minor [Functional Correctness]
→ ]8;;vscode://file//work/apps/alp-fusion/test/tx/assemble.test.ts:146apps/alp-fusion/test/tx/assemble.test.ts:146-148]8;;
Assert scripts to prove XEC output ordering.
Line 147 checks only sats; both outputs are dust-valued, so an
implementation that places the XEC output before the token output still
passes.
Proposed test strengthening
expect(assembled.tx.outputs.length).to.equal(3);
+ expect(assembled.tx.outputs[1].script.bytecode).to.deep.equal(
+ tokenOutputs[0].script.bytecode,
+ );
expect(assembled.tx.outputs[2].sats).to.equal(xecSats);
+ expect(assembled.tx.outputs[2].script.bytecode).to.deep.equal(
+ p2pkh(0xee).bytecode,
+ );────────────────────────────────────────────────────────────────────────
minor [Functional Correctness]
→ ]8;;vscode://file//work/apps/alp-fusion/test/tx/assemble.test.ts:175apps/alp-fusion/test/tx/assemble.test.ts:175-179]8;;
Decode the maximum-sized SEND payload.
These assertions prove output count and OP_RETURN size, but not that the
boundary encoding retains every SEND amount. Parse the EMPP payload and
compare its atom array to tokenOutputs.
Proposed test strengthening
expect(assembled.tx.outputs[0].script.bytecode.length).to.be.at.most(
OP_RETURN_MAX_BYTES,
);
+ const pushes = parseEmppScript(assembled.tx.outputs[0].script);
+ expect(pushes).to.not.equal(undefined);
+ const alp = parseAlp(pushes![0]);
+ expect(alp?.txType).to.equal(SEND_STR);
+ expect(alp?.sendAtomsArray).to.deep.equal(
+ tokenOutputs.map(output => output.atoms),
+ );────────────────────────────────────────────────────────────────────────
major [Maintainability & Code Quality]
→ ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:150apps/alp-fusion/src/tx/assemble.ts:150]8;;
Duplicate ALP push / dust-default logic between validate and assemble.
The EMPP push (alpSend + emppScript) is built once in
validateAlpSendAssembly (Line 181-186) purely to size-check it, and
rebuilt independently in assembleAlpSend (Line 218-219). Likewise, the
out.sats ?? dustSats default is applied separately in both places (Line
150 and Line 222). If either copy is edited without the other, the size
check would silently stop matching the script actually embedded in the
transaction.
♻️ Suggested refactor: compute once, share between validate and assemble
+function buildAlpPush(
+ tokenId: string,
+ atomsArray: bigint[],
+): { push: ReturnType<typeof alpSend>; opreturn: ReturnType<typeof emppScript> } {
+ const push = alpSend(tokenId, ALP_STANDARD, atomsArray);
+ return { push, opreturn: emppScript([push]) };
+}
+
export function validateAlpSendAssembly(params: AssembleAlpSendParams): void {
...
- const push = alpSend(
- params.tokenId,
- ALP_STANDARD,
- tokenOutputs.map(o => o.atoms),
- );
- const opreturn = emppScript([push]);
+ const { opreturn } = buildAlpPush(params.tokenId, tokenOutputs.map(o => o.atoms));
if (opreturn.bytecode.length > OP_RETURN_MAX_BYTES) { ... }
}
export function assembleAlpSend(params: AssembleAlpSendParams): AssembledAlpSend {
validateAlpSendAssembly(params);
...
- const alpPush = alpSend(params.tokenId, ALP_STANDARD, sendAtomsArray);
- const outputs: TxOutput[] = [{ sats: 0n, script: emppScript([alpPush]) }];
+ const { opreturn } = buildAlpPush(params.tokenId, sendAtomsArray);
+ const outputs: TxOutput[] = [{ sats: 0n, script: opreturn }];
Also applies to: 181-186, 218-222────────────────────────────────────────────────────────────────────────
major [Functional Correctness] → ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:254apps/alp-fusion/src/tx/assemble.ts:254-256]8;; Use a signed-size estimate here tx.serSize() is measuring a transaction with empty input scripts, so estimatedFeeSats will be below the final fee once the inputs are signed. ecash-lib’s fee estimation path goes through TxBuilder/signatories for this reason.
────────────────────────────────────────
Review complete
4 findings ✔
Major 2
Minor 2
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Address CodeRabbit: share planAlpSendAssembly (aggregates + EMPP once); strengthen XEC ordering and max-SEND atom decode tests.
Tail of the build log:
/work /work/abc-ci-builds/ai-review Connecting to CodeRabbit... 0s elapsed Preparing review... 1s elapsed ✗ Review limit reached Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. You're only billed for reviews past your plan's rate limits ($0.25/file). You can wait 17 minutes for the limit to reset. https://app.coderabbit.ai/settings/billing?tab=usage&orgId=79839cd4-7849-4bd5-8d6d-5ecaf453356e Build ai-review failed with exit code 1
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) Goodbye, code review angst.
────────────────────────────────────────────────────────────────────────
minor [Functional Correctness]
→ ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:149apps/alp-fusion/src/tx/assemble.ts:149-157]8;;
Inconsistent zero-sats handling: fuelInputs reject sats === 0n,
tokenInputs don't.
Line 152-155 explicitly forbids sats === 0n for fuel inputs, but the
tokenInputs loop (Line 144) only calls assertNonNegSats, permitting
sats === 0n. A real on-chain UTXO backing a token input can't have 0
sats, so this asymmetry is a validation gap for the same class of input.
🛡️ Proposed fix
assertPositiveAtoms(inp.atoms, `tokenInputs[${i}]`);
assertNonNegSats(inp.sats, `tokenInputs[${i}]`);
+ if (inp.sats === 0n) {
+ throw new Error(`tokenInputs[${i}] sats must be > 0`);
+ }
inputAtoms += inp.atoms;────────────────────────────────────────
Review complete
1 finding ✔
Minor 1
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) Separate views from models. Gain flexibility at low cost by designing your application in terms of models and views.
────────────────────────────────────────
Review complete
No findings ✔
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Not really requesting change but I'd like the question to be answered because it impacts the following diffs
| apps/alp-fusion/src/tx/types.ts | ||
|---|---|---|
| 52 ↗ | (On Diff #60611) | This is a weird interface, the usual solution is to use a feeRate (e.g. sats/byte) instead. What is the reason for using a fee value directly ? If you use a Schnorr signature the size is deterministic |
Address review: switch AssembleAlpSendParams from exact feeSats to feePerKb (sats/kB).
Required fee is calcTxFee(signedSerSize, feePerKb) with deterministic Schnorr
P2PKH scriptSig size (65-byte flagged sig + 33-byte compressed pubkey), matching
CashFusion-style component feerate. Callers size fuel so inputSats - outputSats
equals that fee; estimateAlpSendFeeSats helps before funding. Dropped the
misleading unsigned estimatedFeeSats field.
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) Winning the war on bugs, one line at a time.
────────────────────────────────────────────────────────────────────────
minor [Functional Correctness]
→ ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:105apps/alp-fusion/src/tx/assemble.ts:105-127]8;;
Reject non-P2PKH input scripts, or the fee estimate can be too low.
estimateSignedSerSize replaces every input script with a P2PKH Schnorr
placeholder. If a caller passes a P2SH or multisig input, the real signed
size is larger. The required fee is then too low and the network can
reject the fused tx. Validation currently accepts any script.
Add an explicit input-script check in planAlpSendAssembly, so the P2PKH
assumption fails loudly.
🛡️ Proposed guard
+function assertP2pkhScript(script: Script, label: string): void {
+ if (!script.isP2pkh()) {
+ throw new Error(
+ `${label} script must be P2PKH (signed-size estimate assumption)`,
+ );
+ }
+}
Call it for each token input and fuel input in planAlpSendAssembly.
Verify the exact predicate name available on Script in the installed
ecash-lib version.────────────────────────────────────────────────────────────────────────
minor [Functional Correctness]
→ ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:291apps/alp-fusion/src/tx/assemble.ts:291-300]8;;
Bound the estimated signed size against a max transaction size.
The layer validates the OP_RETURN size only. signedSerSize is computed
and returned, but never checked against a policy maximum. A fused SEND can
carry many inputs. The result is a valid-looking assembly that no node
relays.
Add a size bound after line 299.
📏 Proposed size check
const unsignedTx = buildUnsignedTx(params, partial);
const signedSerSize = estimateSignedSerSize(unsignedTx);
+ if (signedSerSize > MAX_TX_SIZE_BYTES) {
+ throw new Error(
+ `estimated signed size ${signedSerSize} exceeds MAX_TX_SIZE_BYTES (${MAX_TX_SIZE_BYTES})`,
+ );
+ }
const feeSats = calcTxFee(signedSerSize, feePerKb);
Use the policy constant from ecash-lib if it exports one.────────────────────────────────────────────────────────────────────────
minor [Functional Correctness]
→ ]8;;vscode://file//work/apps/alp-fusion/test/tx/assemble.test.ts:287apps/alp-fusion/test/tx/assemble.test.ts:287-293]8;;
Build the duplicate-outpoint params without the funding helper.
baseParams calls estimateAlpSendFeeSats, which runs the same
validation. The duplicate error comes from the helper during setup, not
from validateAlpSendAssembly. The assertion therefore passes even if the
duplicate check is removed from the function under test.
Construct the params inline.
💚 Proposed test change
expect(() =>
- validateAlpSendAssembly(
- baseParams({
- tokenInputs: [tokenInput(0, 50n), tokenInput(0, 50n)],
- }),
- ),
+ validateAlpSendAssembly({
+ tokenId: TOKEN_ID,
+ tokenInputs: [tokenInput(0, 50n), tokenInput(0, 50n)],
+ tokenOutputs: [tokenOutput(100n)],
+ fuelInputs: [fuelInput(1000n)],
+ }),
).to.throw(/duplicate outpoint/);────────────────────────────────────────
Review complete
3 findings ✔
Minor 3
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Address CodeRabbit: require P2PKH input scripts for fee estimate; reject signedSerSize > MAX_TX_SERSIZE; fix duplicate-outpoint test to not use funding helper.
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) X marks the bug.
────────────────────────────────────────────────────────────────────────
major [Data Integrity & Integration] → ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:76apps/alp-fusion/src/tx/assemble.ts:76-82]8;; Canonicalize txid before building the duplicate key. OutPoint.txid accepts big-endian hex strings and little-endian Uint8Array values. Mixed representations of the same outpoint therefore produce different keys, so remember can miss a duplicate spend. Convert string values to raw bytes in little-endian order before calling toHex (or use fromHexRev) for one canonical key.
────────────────────────────────────────
Review complete
1 finding ✔
Major 1
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Address CodeRabbit: canonicalize outpointKey with toHexRev so BE hex string and LE Uint8Array txids collide for duplicate detection.
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) In software, we rarely have meaningful requirements. Even if we do, the only measure of success that matters is whether our solution solves the customer's shifting idea of what their problem is. - Jeff Atwood
────────────────────────────────────────────────────────────────────────
minor [Maintainability & Code Quality] → ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:368apps/alp-fusion/src/tx/assemble.ts:368-384]8;; Correct the doc comment about sizing fuel after estimation. The comment states that callers can size fuel after estimating. signedSerSize depends on the input count, so adding a fuel input after estimation increases the size by roughly 148 bytes and raises the required fee. The estimate is valid only for the exact input and output shape passed in. Rewrite the comment to state that the caller must include every intended input and output, with placeholder sats, before calling this function.
────────────────────────────────────────────────────────────────────────
major [Data Integrity & Integration] → ]8;;vscode://file//work/apps/alp-fusion/src/tx/assemble.ts:271apps/alp-fusion/src/tx/assemble.ts:271-280]8;; Reject token UTXOs at the fuel selection boundary. FusionFuelInput contains no atom metadata. The assembler serializes every fuel input but excludes it from inputAtoms. If a token UTXO enters fuelInputs, its atoms can be burned without detection. Enforce isTokenUtxo === false when selecting fuel inputs, or add token metadata and reject nonzero atoms in this loop. Add a regression test.
────────────────────────────────────────
Review complete
2 findings ✔
Major 1
Minor 1
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Address CodeRabbit: reject fuelInputs with nonzero atoms (token-as-fuel burn); clarify estimateAlpSendFeeSats docs (shape must include fuel inputs).
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) Let's pair program: you type, I judge lovingly.
────────────────────────────────────────────────────────────────────────
major [Data Integrity & Integration]
→ ]8;;vscode://file//work/apps/alp-fusion/src/tx/types.ts:26apps/alp-fusion/src/tx/types.ts:26-31]8;;
Require an explicit atom count for fuel inputs.
Line 31 permits callers to omit atoms. An omitted value is
indistinguishable from a confirmed zero-atom UTXO. A token UTXO can then
enter fuelInputs without triggering the nonzero-atom validation and its
tokens can be burned.
Require atoms on every FusionFuelInput. Keep the runtime `atoms !==
0n` check.
Proposed fix
export interface FusionFuelInput {
prevOut: OutPoint;
sats: bigint;
script: Script;
- /** Must be 0 / omitted. Nonzero rejects (token UTXO used as fuel). */
- atoms?: bigint;
+ /** Must be 0. Nonzero rejects a token UTXO used as fuel. */
+ atoms: bigint;
}────────────────────────────────────────
Review complete
1 finding ✔
Major 1
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
Print all AI prompts: coderabbit review --show-prompts
Address CodeRabbit: require explicit atoms: 0n on FusionFuelInput (omit was indistinguishable from confirmed zero).
Build Bitcoin ABC Diffs / Diff Testing (ai-review) passed.
CodeRabbit Review
Diff : committed changes only
Compare : HEAD → master
Directory : work
────────────────────────────────────────
(\(\
(• .•) Colonel Panic is my arch-nemesis.
────────────────────────────────────────
Review complete
No findings ✔
4 files reviewed:
- apps/alp-fusion/README.md
- apps/alp-fusion/src/tx/assemble.ts
- apps/alp-fusion/src/tx/types.ts
- apps/alp-fusion/test/tx/assemble.test.ts
────────────────────────────────────────
| apps/alp-fusion/src/tx/assemble.ts | ||
|---|---|---|
| 170 ↗ | (On Diff #60696) | Can't you use ecash-lib or ecash-wallet inspect() method ? this seems to be quite redundant with what is done in our existing libs |
| apps/alp-fusion/src/tx/assemble.ts | ||
|---|---|---|
| 170 ↗ | (On Diff #60696) | Not really. We are (kind of) using ecash-lib here, in that we are using the Tx type and inputs and outputs. But in this case we need it to be unsigned and to use specific inputs and outputs. Selection is determined by fusion rules and not by the usual ecash-wallet stuff (normal UTXO selection and fees). We could optionally extend ecash-wallet or ecash-lib to help out here. But in this case, I think it would be a strange shim...would only be for this specific fusion case. So I think it makes sense for it to live in alp-fusion. Maybe when we have this in a working state, there will be a more clear way to modularize the fusion logic, or keep it contained in ecash-lib. |