perfect! that should cover everything + is easy to use (I suspect)

we should export these types

this should be inferable from outputs

oh we also need this, otherwise we can't build the OP_RETURN

and this (modelled after ChronikClient.ts):

export interface TokenType {
  protocol: 'SLP' | 'ALP';
  number: number;
}

(also, move this before MintAction. Canonical order is GENESIS, MINT, SEND, BURN)

same here, MintData can be inferred, that's why we have isGenesis

need an extra function for tokens, so better make it clear already

you actually need to derive the OP_RETURN from the outputs somewhere.

the process would look like this (steps might be melded):

1. Collect all used token IDs from the outputs (plus one for genesis, if there's one. For this calculation, it's probably best to assign a dummy token ID for GENESIS)
2. Determine the last output index for each token ID, including for genesis.
   1. So if token A sends to output 1, 2, 7, this is 7, and token B sends to 3, 4, this is 4
   2. If there's any mint batons, the last output index will be the index of the first mint baton - 1 (so if the token sends tokens to 1, 2, 7 and a mint baton to 9 and 10, the last output index will be 8).
   3. Also, count the mint batons of a token ID (and ensure they are consecutive (i.e. 9, 10, 11 is ok, but 9, 10, 12 is not). This is because mint batons are assigned by a single number ("numBatons"), and they come after the send amounts).
   4. At the end we have two numbers for each token ID: last output index, and number of mint batons.
3. Allocate zero'd bigint[] arrays for each token ID ("atomsArray") with the number of items equal to the last output index from step 2.
4. Go through each of the action's outputs again, and for output N, if it has any atoms, assign atomsArray[N] of the corresponding token ID the atoms of the output
5. Now we can build all the ALP/SLP pushdata.
   1. For ALP, for each token ID (including genesis), we create a MINT if there's a MintAction in tokenActions, or a GENESIS if there's a GenesisAction, with the atomsArray and numBatons derived before. Otherwise, if there's at least 1 atom in the outputs, create a SEND. Independent of this, if there's a BurnAction, add a BURN (so (SEND|MINT) and BURN can co-exist).
   2. For SLP, this will be similar, but a GENESIS and MINT is more limited, also there can only be either a GENESIS, SEND, MINT or BURN, but not multiple.
6. And then we add this in an OP_RETURN at the beginning of the tx's outputs (if there's any ALP or SLP data)

generally the terms we use in the node are "policy" (for mempool acceptance rules) and "consensus" (for rules enforced on blocks), so let's use that here too :)

shouldn't this be optional too?

for NonTokenOutput only: leftover XEC change
for TokenOutput: picks the DUST_LIMIT value by default

shouldn't it be this for consistency?

If I understand correctly, when using tokens, the user is always expected to use an OpReturnOutput, and set script to undefined—I like that, but I think it should be made a bit clearer in the comment that it has to be specified and left empty for tokens.

Can you clarify what happens when using tokens (which will occupy the OP_RETURN) and a non-undefined script in OpReturnOutput? Will there be an error?

I think what you're proposing is a clean solution to have this as an "opaque OP_RETURN", for exceptional stuff that we can't/don't want to have special handling for in our system, and fail if the user tries to use a manual OP_RETURN and SLP/ALP simultaneously.

this is how OP_RETURN outputs are identified, right? the user sets sats to 0n?

Maybe add a clarifying comment that we know an output is OP_RETURN if its sats are 0n

I think this more clearly distinguishes the isMintBaton and isMinted variant

Note an alternative to this field that I suggest below; I think we should prefer this over the approach here

with my GENESIS_TOKEN_ID_PLACEHOLDER suggestion, I think it might be simpler to just have tokenId == 'GENESIS_TOKEN_ID_PLACEHOLDER' instead.

This way, we don't force people to see the isGenesis always. Not a big difference but I think it's a bit cleaner and simpler, and we do away with GenesisOutput

I suggest we have a generic list of token actions here (did we do this in a previous diff already and I lamented it? If not, I hope you don't go full Martin Luther with claiming contradictory councils, I'm not an infallible authority on code reviews)

I'm not sure if you're going to like this suggestion, but I think it solves a lot of problems simultaneously:

• How to specify which token ID is a GENESIS, MINT, BURN, SEND
• Allows us to add extra config data in the future for specific tx types (e.g. prevent a SEND (or MINT) to be split into multiple txs)
• The order of the generated eMPP pushdata (maybe the BURN should be first, then the SEND, or vice versa)
• Adding arbitrary eMPP pushdata in the middle

(comments below are part of the review, not suggested code comments)

type TokenAction = GenesisAction | BurnAction | MintAction | SendAction | DataAction;

// Naturally, the genesis action must be first, but this way we cleanly encode
// the empp pushdata in a list exactly in the order of how it's going
// to look like in the OP_RETURN
interface GenesisAction {
    type: 'GENESIS'; // to distinguish actions e.g. in a `switch (tokenAction.type)`
    tokenType: TokenType;
    genesisInfo: GenesisInfo;
}

interface BurnAction {
    type: 'BURN';
    tokenId: string;
    burnAtoms: bigint;
}

interface MintAction {
    type: 'MINT';
    tokenId: string;
}

interface SendAction {
    type: 'SEND';
    tokenId: string;
}
// in the future, can add more actions, e.g. to blacklist UTXOs (if the crown requires us)

// attaches an arbitrary eMPP pushdata
interface DataAction {
    type: 'DATA';
    data: Uint8Array; // or hex string...
}

an action then could look like this:

wallet.action({
  outputs: [
    { sats: 0n }, // OP_RETURN, filled in for us
    { sats: 10000n, script: Script.p2kh(...) },
    { tokenId: GENESIS_TOKEN_ID_PLACEHOLDER, atoms: 20n, script: ... },
    { tokenId: tokenId1, atoms: 1000n, script: ... },
    { tokenId: tokenId2, atoms: 300000n, script: ... },
    { tokenId: tokenId1, isMintBaton: true, script: ... },
    { script: ... }, // change output
  ],
  tokenActions: [
    { type: 'GENESIS', tokenType: ALP_STANDARD, genesisInfo: { ... } }, // must be first
    { type: 'MINT', tokenId: tokenId1 },
    { type: 'SEND', tokenId: tokenId2 },
    { type: 'DATA', data: fromHex("12345678") },
    { type: 'BURN', tokenId: tokenId2, burnAtoms: 12n },
  ],
})

SENDs and MINTs also have the special property that they can be split into multiple transactions (but we can implement this later)

BTW—we might want to consistently use this placeholder instead of of isGenesis, then we don't need a separate GenesisOutput; and TokenOutput is enough.

The user would have to set { tokenId: GENESIS_TOKEN_ID_PLACEHOLDER } for outputs coming from the GENESIS. Tbh it's a little makeshift and maybe confusing to newcomers, but worst-case we just provide a helper shorthand function to genesis a new token in a more "dumb" way.

Yes, I ended up adding this because I ran into issues with slp spec requiring certain outputs to be at certain outIdx values. Because of this requirement, and because we are offering the user the granularity of setting exact outputs -- imo we need to make sure the outputs set by the user appear at the outIdx set by the user.

So, this leaves us with a bit of a weird externality in that the user must specify a blank OP_RETURN at outIdx 0. But the error msgs and typescript clarify the requirement.

Can you clarify what happens when using tokens (which will occupy the OP_RETURN) and a non-undefined script in OpReturnOutput? Will there be an error?

Looks like this test case was missed. Added. We get this error (from finalizeOutputs):

A token tx cannot specify any manual OP_RETURN outputs. Token txs can only include a blank OP_RETURN output (i.e. { sats: 0n} at index 0.

it's only the special case of a "to-be-defined OP_RETURN" that looks exactly like {sats:0n} where this is true

If the user is manually specifying an OP_RETURN, it would be identified by the script

For now, we have error handling so that any OP_RETURN must also include 0n at the sats: key (i.e. ecash-wallet will not support XEC burns in OP_RETURN outputs).

we might want to consistently use this placeholder instead of of isGenesis

... this is probably better yeah. a bit weird but we could handle it with the other weirdness of token specs, throwing an error if not implemented correctly. can take a look at this in isolation.