ecash-lib 3.0.0 → 3.2.0

package/src/token/alp.parse.ts

@@ -0,0 +1,258 @@
+// Copyright (c) 2025 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { toHex, toHexRev } from '../io/hex.js';
+import { bytesToStr } from '../io/str.js';
+import { Bytes } from '../io/bytes.js';
+import {
+    ALP_LOKAD_ID,
+    ALP_MAX_SIZE,
+    ALP_STANDARD,
+    AlpTokenType,
+    MintData,
+} from './alp.js';
+import {
+    BURN_STR,
+    GENESIS_STR,
+    GenesisInfo,
+    MINT_STR,
+    SEND_STR,
+    TOKEN_ID_NUM_BYTES,
+    UNKNOWN_STR,
+} from './common.js';
+
+/**
+ * Parsed ALP GENESIS pushdata.
+ * Note: This must always be the first eMPP pushdata.
+ **/
+export interface AlpGenesis {
+    /** "GENESIS" */
+    txType: typeof GENESIS_STR;
+    /** Token type of the token to create */
+    tokenType: AlpTokenType;
+    /** Info about the token */
+    genesisInfo: GenesisInfo;
+    /** Which tokens/mint baton to create initially */
+    mintData: MintData;
+}
+
+/** Parsed ALP MINT pushdata. */
+export interface AlpMint {
+    /** "MINT" */
+    txType: typeof MINT_STR;
+    /** Token type of the token to mint */
+    tokenType: AlpTokenType;
+    /** Token ID of the token to mint */
+    tokenId: string;
+    /** Which tokens/mint baton to create  */
+    mintData: MintData;
+}
+
+/** Parsed ALP SEND pushdata. */
+export interface AlpSend {
+    /** "SEND" */
+    txType: typeof SEND_STR;
+    /** Token type of the token to send */
+    tokenType: AlpTokenType;
+    /** Token ID of the token to send */
+    tokenId: string;
+    /** Array of the number of token atoms to send to the outputs at 1 to N */
+    sendAtomsArray: bigint[];
+}
+
+/** Parsed ALP BURN pushdata */
+export interface AlpBurn {
+    /** "BURN" */
+    txType: typeof BURN_STR;
+    /** Token type of the token to burn */
+    tokenId: string;
+    /** Token ID of the token to burn */
+    tokenType: AlpTokenType;
+    /** How many tokens should be burned */
+    burnAtoms: bigint;
+}
+
+/** New unknown ALP token type */
+export interface AlpUnknown {
+    /** Placeholder for unknown token type or tx type */
+    txType: typeof UNKNOWN_STR;
+    /** Token type number */
+    tokenType: number;
+}
+
+/** Parsed ALP pushdata */
+export type AlpData = AlpGenesis | AlpMint | AlpSend | AlpBurn | AlpUnknown;
+
+/**
+ * Parse the given ALP pushdata. eMPP allows multiple pushdata per OP_RETURN.
+ *
+ * For data that's clearly not ALP (i.e. doesn't start with LOKAD ID "SLP2"),
+ * it will return `undefined`.
+ *
+ * For an unknown token type, it'll return AlpUnknown.
+ *
+ * For a known token type, it'll parse the remaining data, or throw an error if
+ * the format is invalid or if there's an unknown tx type.
+ *
+ * This behavior mirrors that of Chronik for consistency.
+ **/
+export function parseAlp(pushdata: Uint8Array): AlpData | undefined {
+    // Must have at least 4 bytes for the LOKAD ID
+    if (pushdata.length < ALP_LOKAD_ID.length) {
+        return undefined;
+    }
+
+    const bytes = new Bytes(pushdata);
+
+    // If the pushdata doesn't start with "SLP2" (ALP's LOKAD ID), return undefined
+    const lokadId = bytesToStr(bytes.readBytes(ALP_LOKAD_ID.length));
+    if (lokadId != bytesToStr(ALP_LOKAD_ID)) {
+        return undefined;
+    }
+
+    // Return UNKNOWN for unknown token types (only "STANDARD" known so far)
+    const tokenType = readU8(bytes, 'tokenType');
+    if (tokenType != ALP_STANDARD) {
+        return {
+            txType: 'UNKNOWN',
+            tokenType,
+        };
+    }
+
+    // Parse tx type (GENESIS, MINT, SEND, BURN)
+    const txType = bytesToStr(readVarBytes(bytes, 'txType'));
+
+    // Handle tx type specific parsing
+    switch (txType) {
+        case GENESIS_STR:
+            return readGenesis(bytes, tokenType);
+        case MINT_STR:
+            return readMint(bytes, tokenType);
+        case SEND_STR:
+            return readSend(bytes, tokenType);
+        case BURN_STR:
+            return readBurn(bytes, tokenType);
+        default:
+            throw new Error('Unknown txType');
+    }
+}
+
+function readGenesis(bytes: Bytes, tokenType: AlpTokenType): AlpGenesis {
+    const tokenTicker = bytesToStr(readVarBytes(bytes, 'tokenTicker'));
+    const tokenName = bytesToStr(readVarBytes(bytes, 'tokenName'));
+    const url = bytesToStr(readVarBytes(bytes, 'url'));
+    const data = readVarBytes(bytes, 'data');
+    const authPubkey = readVarBytes(bytes, 'authPubkey');
+    const decimals = readU8(bytes, 'decimals');
+    const mintData = readMintData(bytes);
+    ensureEnd(bytes, 'GENESIS');
+    return {
+        txType: GENESIS_STR,
+        tokenType,
+        genesisInfo: {
+            tokenTicker,
+            tokenName,
+            url,
+            data: toHex(data),
+            authPubkey: toHex(authPubkey),
+            decimals,
+        },
+        mintData,
+    };
+}
+
+function readMint(bytes: Bytes, tokenType: AlpTokenType): AlpMint {
+    const tokenId = readTokenId(bytes);
+    const mintData = readMintData(bytes);
+    ensureEnd(bytes, 'MINT');
+    return {
+        txType: MINT_STR,
+        tokenType,
+        tokenId,
+        mintData,
+    };
+}
+
+function readSend(bytes: Bytes, tokenType: AlpTokenType): AlpSend {
+    const tokenId = readTokenId(bytes);
+    const sendAtomsArray = readAtomsArray(bytes, 'sendAtomsArray');
+    ensureEnd(bytes, 'SEND');
+    return {
+        txType: SEND_STR,
+        tokenType,
+        tokenId,
+        sendAtomsArray,
+    };
+}
+
+function readBurn(bytes: Bytes, tokenType: AlpTokenType): AlpBurn {
+    const tokenId = readTokenId(bytes);
+    const burnAtoms = readU48(bytes, 'burnAtoms');
+    ensureEnd(bytes, 'BURN');
+    return {
+        txType: BURN_STR,
+        tokenType,
+        tokenId,
+        burnAtoms,
+    };
+}
+
+function readU8(bytes: Bytes, name: string): number {
+    if (bytes.idx >= bytes.data.length) {
+        throw new Error(`Missing ${name}`);
+    }
+    return bytes.readU8();
+}
+
+function readU48(bytes: Bytes, name: string): bigint {
+    if (bytes.idx >= bytes.data.length) {
+        throw new Error(`Missing ${name}`);
+    }
+    return bytes.readU48();
+}
+
+function readTokenId(bytes: Bytes): string {
+    // Note: ALP token ID endianness is little-endian (like in prevOut)
+    return toHexRev(bytes.readBytes(TOKEN_ID_NUM_BYTES));
+}
+
+function readSize(bytes: Bytes, name: string): number {
+    const size = readU8(bytes, name);
+    if (size > ALP_MAX_SIZE) {
+        throw new Error(`Size must be between 0 and ${ALP_MAX_SIZE}`);
+    }
+    return size;
+}
+
+function readVarBytes(bytes: Bytes, name: string): Uint8Array {
+    const numBytes = readSize(bytes, name);
+    return bytes.readBytes(numBytes);
+}
+
+function readAtomsArray(bytes: Bytes, name: string): bigint[] {
+    const numAtoms = readSize(bytes, name);
+    const atomsArray = [];
+    for (let i = 0; i < numAtoms; ++i) {
+        atomsArray.push(bytes.readU48());
+    }
+    return atomsArray;
+}
+
+function readMintData(bytes: Bytes): MintData {
+    const atomsArray = readAtomsArray(bytes, 'atomsArray');
+    const numBatons = readU8(bytes, 'numBatons');
+    if (numBatons > ALP_MAX_SIZE) {
+        throw new Error(`numBatons must be between 0 and ${ALP_MAX_SIZE}`);
+    }
+    return {
+        atomsArray,
+        numBatons,
+    };
+}
+
+function ensureEnd(bytes: Bytes, txType: string) {
+    if (bytes.idx < bytes.data.length) {
+        throw new Error(`Superfluous ${txType} bytes`);
+    }
+}

package/src/token/alp.ts

@@ -9,12 +9,21 @@ import { WriterBytes } from '../io/writerbytes.js';
 import { WriterLength } from '../io/writerlength.js';
 import { BURN, GENESIS, GenesisInfo, MINT, SEND } from './common.js';
 
+/** LOKAD ID for ALP as string */
+export const ALP_LOKAD_ID_STR = 'SLP2';
+
 /** LOKAD ID for ALP */
-export const ALP_LOKAD_ID = strToBytes('SLP2');
+export const ALP_LOKAD_ID = strToBytes(ALP_LOKAD_ID_STR);
 
 /** ALP standard token type number */
 export const ALP_STANDARD = 0;
 
+/** Supported ALP token types */
+export type AlpTokenType = typeof ALP_STANDARD;
+
+/** ALP limits lengths/sizes to this number, e.g. the number of outputs */
+export const ALP_MAX_SIZE = 127;
+
 /** Mint data specifying mint amounts (in atoms) and batons of a GENESIS/MINT tx */
 export interface MintData {
     /**

package/src/token/common.ts

@@ -4,10 +4,34 @@
 
 import { strToBytes } from '../io/str.js';
 
-export const GENESIS = strToBytes('GENESIS');
-export const MINT = strToBytes('MINT');
-export const SEND = strToBytes('SEND');
-export const BURN = strToBytes('BURN');
+/** GENESIS tx type: Creates a new token ID */
+export const GENESIS_STR = 'GENESIS';
+export const GENESIS = strToBytes(GENESIS_STR);
+
+/** MINT tx type: Mints more of a token ID */
+export const MINT_STR = 'MINT';
+export const MINT = strToBytes(MINT_STR);
+
+/** SEND tx type: Moves existing tokens to different outputs */
+export const SEND_STR = 'SEND';
+export const SEND = strToBytes(SEND_STR);
+
+/** BURN tx type: Destroys existing tokens */
+export const BURN_STR = 'BURN';
+export const BURN = strToBytes(BURN_STR);
+
+/**
+ * UNKNOWN: Placeholder for unknown token types.
+ * Note: These may hold valuable tokens, but which aren't recognized.
+ * They should be excluded from UTXO selection.
+ **/
+export const UNKNOWN_STR = 'UNKNOWN';
+
+/** Number of bytes in a token ID */
+export const TOKEN_ID_NUM_BYTES = 32;
+
+/** How many decimals a token can have at most (SLP/ALP) */
+export const MAX_DECIMALS = 9;
 
 /** Genesis info found in GENESIS txs of tokens */
 export interface GenesisInfo {

package/src/token/empp.ts

@@ -2,7 +2,7 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-import { Op, pushBytesOp } from '../op.js';
+import { Op, isPushOp, pushBytesOp } from '../op.js';
 import { OP_PUSHDATA1, OP_RESERVED, OP_RETURN } from '../opcode.js';
 import { Script } from '../script.js';
 
@@ -27,3 +27,44 @@ function pushdataOpEmpp(pushdata: Uint8Array): Op {
     }
     return pushBytesOp(pushdata);
 }
+
+/**
+ * Parse a script for EMPP push(es)
+ *
+ * EMPP may encode multiple pushdatas in a single OP_RETURN script
+ *
+ * input script is a valid EMPP OP_RETURN    => returns an array of EMPP pushdata(s)
+ * input script is not an EMPP OP_RETURN     => returns undefined
+ * input script is an invalid EMPP OP_RETURN => throws
+ */
+export function parseEmppScript(script: Script): Uint8Array[] | undefined {
+    const ops = script.ops();
+    const opreturnOp = ops.next();
+    if (
+        opreturnOp === undefined ||
+        isPushOp(opreturnOp) ||
+        opreturnOp !== OP_RETURN
+    ) {
+        return undefined;
+    }
+    const opreservedOp = ops.next();
+    if (
+        opreservedOp === undefined ||
+        isPushOp(opreservedOp) ||
+        opreservedOp !== OP_RESERVED
+    ) {
+        return undefined;
+    }
+    const pushdata: Uint8Array[] = [];
+    let op: Op | undefined = undefined;
+    while ((op = ops.next()) !== undefined) {
+        if (!isPushOp(op)) {
+            throw new Error('eMPP allows only push ops');
+        }
+        if (op.data.length === 0) {
+            throw new Error("eMPP doesn't allow empty pushdata");
+        }
+        pushdata.push(op.data);
+    }
+    return pushdata;
+}