ecash-lib 1.2.2-rc9 → 1.4.0

package/src/token/alp.ts

@@ -0,0 +1,146 @@
+// Copyright (c) 2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { fromHex, fromHexRev } from '../io/hex.js';
+import { strToBytes } from '../io/str.js';
+import { Writer } from '../io/writer.js';
+import { WriterBytes } from '../io/writerbytes.js';
+import { WriterLength } from '../io/writerlength.js';
+import { Amount, BURN, GENESIS, GenesisInfo, MINT, SEND } from './common.js';
+
+/** LOKAD ID for ALP */
+export const ALP_LOKAD_ID = strToBytes('SLP2');
+
+/** ALP standard token type number */
+export const ALP_STANDARD = 0;
+
+/** Mint data specifying mint amounts and batons of a GENESIS/MINT tx */
+export interface MintData {
+    /**
+     * List of amounts to be minted by this tx, each having their own tx output.
+     */
+    amounts: Amount[];
+    /** Number of mint batons to create, each having their own tx output. */
+    numBatons: number;
+}
+
+/** Build an ALP GENESIS pushdata section, creating a new ALP token */
+export function alpGenesis(
+    tokenType: number,
+    genesisInfo: GenesisInfo,
+    mintData: MintData,
+): Uint8Array {
+    const writeSection = (writer: Writer) => {
+        writer.putBytes(ALP_LOKAD_ID);
+        writer.putU8(tokenType);
+        putVarBytes(GENESIS, writer);
+        putVarBytes(strToBytes(genesisInfo.tokenTicker ?? ''), writer);
+        putVarBytes(strToBytes(genesisInfo.tokenName ?? ''), writer);
+        putVarBytes(strToBytes(genesisInfo.url ?? ''), writer);
+        putVarBytes(fromHex(genesisInfo.data ?? ''), writer);
+        putVarBytes(fromHex(genesisInfo.authPubkey ?? ''), writer);
+        writer.putU8(genesisInfo.decimals ?? 0);
+        putMintData(mintData, writer);
+    };
+    const writerLength = new WriterLength();
+    writeSection(writerLength);
+    const writerBytes = new WriterBytes(writerLength.length);
+    writeSection(writerBytes);
+    return writerBytes.data;
+}
+
+/**
+ * Build an ALP MINT pushdata section, creating new ALP tokens and mint batons
+ * of the given token ID.
+ **/
+export function alpMint(
+    tokenId: string,
+    tokenType: number,
+    mintData: MintData,
+): Uint8Array {
+    const tokenIdBytes = fromHexRev(tokenId);
+    const writeSection = (writer: Writer) => {
+        writer.putBytes(ALP_LOKAD_ID);
+        writer.putU8(tokenType);
+        putVarBytes(MINT, writer);
+        writer.putBytes(tokenIdBytes);
+        putMintData(mintData, writer);
+    };
+    const writerLength = new WriterLength();
+    writeSection(writerLength);
+    const writerBytes = new WriterBytes(writerLength.length);
+    writeSection(writerBytes);
+    return writerBytes.data;
+}
+
+/**
+ * Build an ALP SEND pushdata section, moving ALP tokens to different outputs
+ **/
+export function alpSend(
+    tokenId: string,
+    tokenType: number,
+    sendAmounts: Amount[],
+): Uint8Array {
+    const tokenIdBytes = fromHexRev(tokenId);
+    const writeSection = (writer: Writer) => {
+        writer.putBytes(ALP_LOKAD_ID);
+        writer.putU8(tokenType);
+        writer.putU8(SEND.length);
+        writer.putBytes(SEND);
+        writer.putBytes(tokenIdBytes);
+        writer.putU8(sendAmounts.length);
+        for (const amount of sendAmounts) {
+            putAlpAmount(amount, writer);
+        }
+    };
+    const writerLength = new WriterLength();
+    writeSection(writerLength);
+    const writerBytes = new WriterBytes(writerLength.length);
+    writeSection(writerBytes);
+    return writerBytes.data;
+}
+
+/** Build an ALP BURN pushdata section, intentionally burning ALP tokens. */
+export function alpBurn(
+    tokenId: string,
+    tokenType: number,
+    burnAmount: Amount,
+): Uint8Array {
+    const tokenIdBytes = fromHexRev(tokenId);
+    const writeSection = (writer: Writer) => {
+        writer.putBytes(ALP_LOKAD_ID);
+        writer.putU8(tokenType);
+        writer.putU8(BURN.length);
+        writer.putBytes(BURN);
+        writer.putBytes(tokenIdBytes);
+        putAlpAmount(burnAmount, writer);
+    };
+    const writerLength = new WriterLength();
+    writeSection(writerLength);
+    const writerBytes = new WriterBytes(writerLength.length);
+    writeSection(writerBytes);
+    return writerBytes.data;
+}
+
+function putMintData(mintData: MintData, writer: Writer) {
+    writer.putU8(mintData.amounts.length);
+    for (const amount of mintData.amounts) {
+        putAlpAmount(amount, writer);
+    }
+    writer.putU8(mintData.numBatons);
+}
+
+function putAlpAmount(amount: Amount, writer: Writer) {
+    const amountN = BigInt(amount);
+    writer.putU32(amountN & 0xffffffffn);
+    writer.putU16(amountN >> 32n);
+}
+
+function putVarBytes(bytes: Uint8Array, writer: Writer) {
+    if (bytes.length > 127) {
+        throw new Error('Length of bytes must be between 0 and 127');
+    }
+    writer.putU8(bytes.length);
+    writer.putBytes(bytes);
+}

package/src/token/common.ts

@@ -0,0 +1,32 @@
+// Copyright (c) 2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { strToBytes } from '../io/str.js';
+
+export type Amount = bigint | number;
+
+export const GENESIS = strToBytes('GENESIS');
+export const MINT = strToBytes('MINT');
+export const SEND = strToBytes('SEND');
+export const BURN = strToBytes('BURN');
+
+/** Genesis info found in GENESIS txs of tokens */
+export interface GenesisInfo {
+    /** token_ticker of the token */
+    tokenTicker?: string;
+    /** token_name of the token */
+    tokenName?: string;
+    /** URL of the token */
+    url?: string;
+    /** token_document_hash of the token (only on SLP) */
+    hash?: string;
+    /** mint_vault_scripthash (only on SLP V2 Mint Vault) */
+    mintVaultScripthash?: string;
+    /** Arbitray payload data of the token (only on ALP) */
+    data?: string;
+    /** auth_pubkey of the token (only on ALP) */
+    authPubkey?: string;
+    /** decimals of the token, i.e. how many decimal places the token should be displayed with. */
+    decimals?: number;
+}

package/src/token/empp.ts

@@ -0,0 +1,29 @@
+// Copyright (c) 2024 The Bitcoin developers
+// 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_PUSHDATA1, OP_RESERVED, OP_RETURN } from '../opcode.js';
+import { Script } from '../script.js';
+
+/** Build an eMPP OP_RETURN script with the given pushdata */
+export function emppScript(pushdata: Uint8Array[]): Script {
+    if (pushdata.find(pushdata => pushdata.length == 0) !== undefined) {
+        throw new Error('Pushdata cannot be empty');
+    }
+    return Script.fromOps([
+        OP_RETURN,
+        OP_RESERVED,
+        ...pushdata.map(pushdataOpEmpp),
+    ]);
+}
+
+function pushdataOpEmpp(pushdata: Uint8Array): Op {
+    if (pushdata.length < OP_PUSHDATA1) {
+        return {
+            opcode: pushdata.length,
+            data: pushdata,
+        };
+    }
+    return pushBytesOp(pushdata);
+}

package/src/token/slp.ts

@@ -0,0 +1,212 @@
+// Copyright (c) 2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { fromHex } from '../io/hex.js';
+import { strToBytes } from '../io/str.js';
+import { Op, pushBytesOp } from '../op.js';
+import { OP_PUSHDATA1, OP_RETURN } from '../opcode.js';
+import { Script } from '../script.js';
+import { Amount, BURN, GENESIS, GenesisInfo, MINT, SEND } from './common.js';
+
+/** LOKAD ID for SLP */
+export const SLP_LOKAD_ID = strToBytes('SLP\0');
+
+/** SLP fungible token type number */
+export const SLP_FUNGIBLE = 1;
+/** SLP MINT Vault token type number */
+export const SLP_MINT_VAULT = 2;
+/** SLP NFT1 Child token type number */
+export const SLP_NFT1_CHILD = 0x41;
+/** SLP NFT1 Group token type number */
+export const SLP_NFT1_GROUP = 0x81;
+
+/** Build an SLP GENESIS OP_RETURN, creating a new SLP token */
+export function slpGenesis(
+    tokenType: number,
+    genesisInfo: GenesisInfo,
+    initialQuantity: Amount,
+    mintBatonOutIdx?: number,
+): Script {
+    verifyTokenType(tokenType);
+    const data: Uint8Array[] = [];
+    data.push(SLP_LOKAD_ID);
+    data.push(new Uint8Array([tokenType]));
+    data.push(GENESIS);
+    data.push(strToBytes(genesisInfo.tokenTicker ?? ''));
+    data.push(strToBytes(genesisInfo.tokenName ?? ''));
+    data.push(strToBytes(genesisInfo.url ?? ''));
+    data.push(genesisInfo.hash ? fromHex(genesisInfo.hash) : new Uint8Array());
+    data.push(new Uint8Array([genesisInfo.decimals ?? 0]));
+    if (tokenType == SLP_MINT_VAULT) {
+        if (genesisInfo.mintVaultScripthash === undefined) {
+            throw new Error('Must set mintVaultScripthash for MINT VAULT');
+        }
+        data.push(fromHex(genesisInfo.mintVaultScripthash));
+    } else {
+        if (mintBatonOutIdx !== undefined) {
+            if (mintBatonOutIdx < 2) {
+                throw new Error('mintBatonOutIdx must be >= 2');
+            }
+            data.push(new Uint8Array([mintBatonOutIdx]));
+        } else {
+            data.push(new Uint8Array());
+        }
+    }
+    data.push(slpAmount(initialQuantity));
+    return Script.fromOps([OP_RETURN as Op].concat(data.map(pushdataOpSlp)));
+}
+
+/**
+ * Build an SLP MINT pushdata section, creating new SLP tokens and mint batons
+ * of the given token ID.
+ **/
+export function slpMint(
+    tokenId: string,
+    tokenType: number,
+    additionalQuantity: Amount,
+    mintBatonOutIdx?: number,
+): Script {
+    verifyTokenType(tokenType);
+    verifyTokenId(tokenId);
+    return Script.fromOps([
+        OP_RETURN,
+        pushdataOpSlp(SLP_LOKAD_ID),
+        pushdataOpSlp(new Uint8Array([tokenType])),
+        pushdataOpSlp(MINT),
+        pushdataOpSlp(fromHex(tokenId)),
+        pushdataOpSlp(
+            new Uint8Array(
+                mintBatonOutIdx !== undefined ? [mintBatonOutIdx] : [],
+            ),
+        ),
+        pushdataOpSlp(slpAmount(additionalQuantity)),
+    ]);
+}
+
+/**
+ * Build an SLP MINT VAULT pushdata section, creating new SLP tokens and mint batons
+ * of the given token ID.
+ **/
+export function slpMintVault(
+    tokenId: string,
+    additionalQuantities: Amount[],
+): Script {
+    verifyTokenId(tokenId);
+    verifySendAmounts(additionalQuantities);
+    return Script.fromOps(
+        [
+            OP_RETURN,
+            pushdataOpSlp(SLP_LOKAD_ID),
+            pushdataOpSlp(new Uint8Array([SLP_MINT_VAULT])),
+            pushdataOpSlp(MINT),
+            pushdataOpSlp(fromHex(tokenId)),
+        ].concat(
+            additionalQuantities.map(qty => pushdataOpSlp(slpAmount(qty))),
+        ),
+    );
+}
+
+/**
+ * Build an SLP SEND pushdata section, moving SLP tokens to different outputs
+ **/
+export function slpSend(
+    tokenId: string,
+    tokenType: number,
+    sendAmounts: Amount[],
+): Script {
+    verifyTokenType(tokenType);
+    verifyTokenId(tokenId);
+    verifySendAmounts(sendAmounts);
+    return Script.fromOps(
+        [
+            OP_RETURN,
+            pushdataOpSlp(SLP_LOKAD_ID),
+            pushdataOpSlp(new Uint8Array([tokenType])),
+            pushdataOpSlp(SEND),
+            pushdataOpSlp(fromHex(tokenId)),
+        ].concat(sendAmounts.map(qty => pushdataOpSlp(slpAmount(qty)))),
+    );
+}
+
+/**
+ * Build an SLP BURN pushdata section, intentionally burning SLP tokens.
+ * See https://github.com/badger-cash/slp-self-mint-protocol/blob/master/token-type1-burn.md
+ **/
+export function slpBurn(
+    tokenId: string,
+    tokenType: number,
+    burnAmount: Amount,
+): Script {
+    verifyTokenType(tokenType);
+    verifyTokenId(tokenId);
+    return Script.fromOps([
+        OP_RETURN,
+        pushdataOpSlp(SLP_LOKAD_ID),
+        pushdataOpSlp(new Uint8Array([tokenType])),
+        pushdataOpSlp(BURN),
+        pushdataOpSlp(fromHex(tokenId)),
+        pushdataOpSlp(slpAmount(burnAmount)),
+    ]);
+}
+
+function verifyTokenType(tokenType: number) {
+    switch (tokenType) {
+        case SLP_FUNGIBLE:
+        case SLP_MINT_VAULT:
+        case SLP_NFT1_GROUP:
+        case SLP_NFT1_CHILD:
+            return;
+        default:
+            throw new Error(`Unknown token type ${tokenType}`);
+    }
+}
+
+function verifyTokenId(tokenId: string) {
+    if (tokenId.length != 64) {
+        throw new Error(
+            `Token ID must be 64 hex characters in length, but got ${tokenId.length}`,
+        );
+    }
+}
+
+function verifySendAmounts(sendAmounts: Amount[]) {
+    if (sendAmounts.length == 0) {
+        throw new Error('Send amount cannot be empty');
+    }
+    if (sendAmounts.length > 19) {
+        throw new Error(
+            `Cannot use more than 19 amounts, but got ${sendAmounts.length}`,
+        );
+    }
+}
+
+function pushdataOpSlp(pushdata: Uint8Array): Op {
+    if (pushdata.length == 0) {
+        return {
+            opcode: OP_PUSHDATA1,
+            data: pushdata,
+        };
+    }
+    if (pushdata.length < OP_PUSHDATA1) {
+        return {
+            opcode: pushdata.length,
+            data: pushdata,
+        };
+    }
+    return pushBytesOp(pushdata);
+}
+
+export function slpAmount(amount: Amount): Uint8Array {
+    if (amount < 0 || BigInt(amount) > 0xffffffffffffffffn) {
+        throw new Error(`Amount out of range: ${amount}`);
+    }
+    const amountBytes = new Uint8Array(8);
+    const view = new DataView(
+        amountBytes.buffer,
+        amountBytes.byteOffset,
+        amountBytes.byteLength,
+    );
+    view.setBigUint64(0, BigInt(amount), /*little endian=*/ false);
+    return amountBytes;
+}

package/src/tx.ts

@@ -0,0 +1,180 @@
+// Copyright (c) 2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { Bytes } from './io/bytes.js';
+import { fromHexRev } from './io/hex.js';
+import { writeVarSize } from './io/varsize.js';
+import { Writer } from './io/writer.js';
+import { WriterBytes } from './io/writerbytes.js';
+import { WriterLength } from './io/writerlength.js';
+import { Script } from './script.js';
+
+/**
+ * Default value for nSequence of inputs if left undefined; this opts out of
+ * BIP68 relative lock-time, and if all inputs have this value, nLockTime is
+ * disabled, too.
+ *
+ * This is chosen as the default as it's the default in the node too,
+ * see CTxIn in /src/primitives/transaction.h.
+ **/
+export const DEFAULT_SEQUENCE = 0xffffffff;
+
+/** Current tx version, see CTransaction in /stc/primitives/transaction.h */
+export const DEFAULT_TX_VERSION = 2;
+
+/** COutPoint, pointing to a coin being spent. */
+export interface OutPoint {
+    /**
+     * TxId of the output of the coin, either a big-endian hex encoded TxId
+     * or a little-endian bytearray.
+     **/
+    txid: string | Uint8Array;
+    /** Index in the outputs of the tx of the coin. */
+    outIdx: number;
+}
+
+/** CTxIn, spending an unspent output. */
+export interface TxInput {
+    /** Points to an output being spent. */
+    prevOut: OutPoint;
+    /** scriptSig unlocking the output, defaults to the empty Script. */
+    script?: Script;
+    /** nSequence, defaults to 0xffffffff if unspecified. */
+    sequence?: number;
+    /** Sign data required to sign an input */
+    signData?: SignData;
+}
+
+/** CTxOut, creating a new output. */
+export interface TxOutput {
+    /** Value in satoshis of the output (1 XEC = 100 satoshis) */
+    value: number | bigint;
+    /** Script locking the output */
+    script: Script;
+}
+
+/** All the data required to sign an input (using BIP143). */
+export interface SignData {
+    /** Value of the output being spent */
+    value: number | bigint;
+    /** Script of the output being spent (not for P2SH) */
+    outputScript?: Script;
+    /**
+     * For P2SH inputs, the preimage of the script hash locking the output being
+     * spent.
+     **/
+    redeemScript?: Script;
+}
+
+/** CTransaction, a Bitcoin transaction. */
+export class Tx {
+    /** nVersion of the tx */
+    public version: number;
+    /** vin, tx inputs spending outputs of other txs */
+    public inputs: TxInput[];
+    /** vout, tx outputs created in this tx */
+    public outputs: TxOutput[];
+    /** nLockTime of the tx, specifies when the tx can be mined earliest */
+    public locktime: number;
+
+    public constructor(params?: {
+        version?: number;
+        inputs?: TxInput[];
+        outputs?: TxOutput[];
+        locktime?: number;
+    }) {
+        this.version = params?.version ?? DEFAULT_TX_VERSION;
+        this.inputs = params?.inputs ?? [];
+        this.outputs = params?.outputs ?? [];
+        this.locktime = params?.locktime ?? 0;
+    }
+
+    /** Serialize the tx to a byte array */
+    public ser(): Uint8Array {
+        const writerBytes = new WriterBytes(this.serSize());
+        this.write(writerBytes);
+        return writerBytes.data;
+    }
+
+    /** Calculate the serialized size of the tx */
+    public serSize(): number {
+        const writerLength = new WriterLength();
+        this.write(writerLength);
+        return writerLength.length;
+    }
+
+    /** Write the tx to the given writer */
+    public write(writer: Writer) {
+        writer.putU32(this.version);
+        writeVarSize(this.inputs.length, writer);
+        for (const input of this.inputs) {
+            writeTxInput(input, writer);
+        }
+        writeVarSize(this.outputs.length, writer);
+        for (const output of this.outputs) {
+            writeTxOutput(output, writer);
+        }
+        writer.putU32(this.locktime);
+    }
+}
+
+export function readTxOutput(bytes: Bytes): TxOutput {
+    const value = bytes.readU64();
+    const script = Script.readWithSize(bytes);
+    return {
+        value,
+        script,
+    };
+}
+
+/** Write an outpoint to a Writer */
+export function writeOutPoint(outpoint: OutPoint, writer: Writer): void {
+    const txid =
+        typeof outpoint.txid === 'string'
+            ? fromHexRev(outpoint.txid)
+            : outpoint.txid;
+    writer.putBytes(txid);
+    writer.putU32(outpoint.outIdx);
+}
+
+/** Write a TxInput to a Writer */
+export function writeTxInput(input: TxInput, writer: Writer): void {
+    writeOutPoint(input.prevOut, writer);
+    (input.script ?? new Script()).writeWithSize(writer);
+    writer.putU32(input.sequence ?? DEFAULT_SEQUENCE);
+}
+
+/** Write a TxOutput to a Writer */
+export function writeTxOutput(output: TxOutput, writer: Writer): void {
+    writer.putU64(output.value);
+    output.script.writeWithSize(writer);
+}
+
+/** Create a deep copy of the TxInput */
+export function copyTxInput(input: TxInput): TxInput {
+    return {
+        prevOut: {
+            txid:
+                typeof input.prevOut.txid === 'string'
+                    ? input.prevOut.txid
+                    : new Uint8Array(input.prevOut.txid),
+            outIdx: input.prevOut.outIdx,
+        },
+        script: input.script?.copy(),
+        sequence: input.sequence,
+        signData: input.signData && {
+            value: input.signData.value,
+            outputScript: input.signData.outputScript?.copy(),
+            redeemScript: input.signData.redeemScript?.copy(),
+        },
+    };
+}
+
+/** Create a deep copy of the TxOutput */
+export function copyTxOutput(output: TxOutput): TxOutput {
+    return {
+        value: output.value,
+        script: output.script.copy(),
+    };
+}