ecash-agora 2.1.0 → 2.2.0

package/README.md

@@ -125,7 +125,7 @@ await chronik.broadcastTx(acceptTx.ser());
 ```
 mkdir build/
 cd build/
-cmake -GNinja .. -DBUILD_BITCOIN_CHRONIK=ON -DBUILD_BITCOIN_CHRONIK_PLUGINS=ON
+cmake -GNinja .. -DBUILD_CHRONIK=ON -DBUILD_CHRONIK_PLUGINS=ON
 ninja
 ```
 
@@ -199,3 +199,7 @@ Running from `bitcoin-abc/modules/ecash-agora` if your build dir is `bitcoin-abc
 ### 2.1.0
 
 -   Add support for "UNKNOWN" token protocol type in chronik-client [D18155](https://reviews.bitcoinabc.org/D18155)
+
+### 2.2.0
+
+-   Add `src/actions.ts` to support preparing payment Actions for `ecash-wallet`, and add `actions.test.ts` to show implementation [D18673](https://reviews.bitcoinabc.org/D18673)

package/dist/actions.d.ts

@@ -0,0 +1,25 @@
+import { payment, TokenType } from 'ecash-lib';
+import { AgoraOfferVariant } from './agora.js';
+/**
+ * Action to request a payment.Action that will
+ * create an Agora listing
+ */
+export interface ListAction {
+    /** The type of agora action, used to distinguish between different spec-enabled actions */
+    type: 'LIST';
+    /**
+     * While tokenType can be inferred from an agora partial,
+     * it cannot be inferred from an agora ONESHOT,
+     * so we need to specify it here
+     */
+    tokenType: TokenType;
+    /** The variant of the agora action to be listed */
+    variant: AgoraOfferVariant;
+}
+/**
+ * Supported agora actions that can be converted to a payment.Action
+ * for build and broadcast by ecash-wallet
+ */
+export type AgoraAction = ListAction;
+export declare const getAgoraPaymentAction: (action: ListAction, dustSats?: bigint) => payment.Action;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,EAEH,OAAO,EACP,SAAS,EAGZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB,mDAAmD;IACnD,OAAO,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC;AAErC,eAAO,MAAM,qBAAqB,WACtB,UAAU,wBAEnB,QAAQ,MAwEV,CAAC"}

package/dist/actions.js

@@ -0,0 +1,73 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgoraPaymentAction = void 0;
+const ecash_lib_1 = require("ecash-lib");
+const getAgoraPaymentAction = (action, dustSats = ecash_lib_1.DEFAULT_DUST_SATS) => {
+    const { type, tokenType, variant } = action;
+    switch (tokenType.protocol) {
+        case 'SLP': {
+            throw new Error('SLP is not currently supported.');
+        }
+        case 'ALP': {
+            switch (type) {
+                case 'LIST': {
+                    /**
+                     * Handle an ALP list action
+                     *
+                     * An ALP list action requires a data action and a send action
+                     * Unlike SLP list actions, it can be completed in a single tx
+                     */
+                    if (variant.type === 'ONESHOT') {
+                        throw new Error('ALP ONESHOT listings are not currently supported');
+                    }
+                    /**
+                     * We only support AgoraPartial listings for ALP
+                     *
+                     * An AgoraPartial listing requires
+                     * - A data tokenAction of agoraPartial.adPushdata() at the beginning of the EMPP OP_RETURN
+                     * - A SEND tokenAction to send the listed tokens to the p2sh output
+                     * - A blank OP_RETURN template output at index 0
+                     * - A p2sh output to hold the listed tokens
+                     *
+                     * ecash-wallet can handle token change and XEC change, so we do not need to build it here
+                     */
+                    return {
+                        outputs: [
+                            { sats: 0n },
+                            {
+                                sats: dustSats,
+                                script: ecash_lib_1.Script.p2sh((0, ecash_lib_1.shaRmd160)(variant.params.script().bytecode)),
+                                tokenId: variant.params.tokenId,
+                                atoms: variant.params.offeredAtoms(),
+                                isMintBaton: false,
+                            },
+                        ],
+                        tokenActions: [
+                            {
+                                type: 'DATA',
+                                data: variant.params.adPushdata(),
+                            },
+                            {
+                                type: 'SEND',
+                                tokenId: variant.params.tokenId,
+                                tokenType: tokenType,
+                            },
+                        ],
+                    };
+                }
+                default: {
+                    // Cannot get here with valid typed input
+                    throw new Error(`Unsupported agora action: ${type}`);
+                }
+            }
+        }
+        default: {
+            throw new Error(`Unsupported token protocol: ${tokenType.protocol}`);
+        }
+    }
+};
+exports.getAgoraPaymentAction = getAgoraPaymentAction;
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":";AAAA,4CAA4C;AAC5C,mEAAmE;AACnE,sEAAsE;;;AAEtE,yCAMmB;AA0BZ,MAAM,qBAAqB,GAAG,CACjC,MAAkB,EAClB,QAAQ,GAAG,6BAAiB,EACd,EAAE;IAChB,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE5C,QAAQ,SAAS,CAAC,QAAQ,EAAE,CAAC;QACzB,KAAK,KAAK,CAAC,CAAC,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvD,CAAC;QACD,KAAK,KAAK,CAAC,CAAC,CAAC;YACT,QAAQ,IAAI,EAAE,CAAC;gBACX,KAAK,MAAM,CAAC,CAAC,CAAC;oBACV;;;;;uBAKG;oBACH,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;wBAC7B,MAAM,IAAI,KAAK,CACX,kDAAkD,CACrD,CAAC;oBACN,CAAC;oBAED;;;;;;;;;;uBAUG;oBAEH,OAAO;wBACH,OAAO,EAAE;4BACL,EAAE,IAAI,EAAE,EAAE,EAAE;4BACZ;gCACI,IAAI,EAAE,QAAQ;gCACd,MAAM,EAAE,kBAAM,CAAC,IAAI,CACf,IAAA,qBAAS,EAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,CAC9C;gCACD,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;gCAC/B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE;gCACpC,WAAW,EAAE,KAAK;6BACrB;yBACJ;wBACD,YAAY,EAAE;4BACV;gCACI,IAAI,EAAE,MAAM;gCACZ,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE;6BACpC;4BACD;gCACI,IAAI,EAAE,MAAM;gCACZ,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;gCAC/B,SAAS,EAAE,SAAS;6BACvB;yBACJ;qBACJ,CAAC;gBACN,CAAC;gBACD,OAAO,CAAC,CAAC,CAAC;oBACN,yCAAyC;oBACzC,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAC;gBACzD,CAAC;YACL,CAAC;QACL,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACN,MAAM,IAAI,KAAK,CACX,+BAA+B,SAAS,CAAC,QAAQ,EAAE,CACtD,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC,CAAC;AA3EW,QAAA,qBAAqB,yBA2EhC"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './ad.js';
 export * from './agora.js';
+export * from './actions.js';
 export * from './consts.js';
 export * from './inputs.js';
 export * from './oneshot.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -19,6 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ad.js"), exports);
 __exportStar(require("./agora.js"), exports);
+__exportStar(require("./actions.js"), exports);
 __exportStar(require("./consts.js"), exports);
 __exportStar(require("./inputs.js"), exports);
 __exportStar(require("./oneshot.js"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4CAA4C;AAC5C,mEAAmE;AACnE,sEAAsE;;;;;;;;;;;;;;;;AAEtE,0CAAwB;AACxB,6CAA2B;AAC3B,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4CAA4C;AAC5C,mEAAmE;AACnE,sEAAsE;;;;;;;;;;;;;;;;AAEtE,0CAAwB;AACxB,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,+CAA6B"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ecash-agora",
-    "version": "2.1.0",
+    "version": "2.2.0",
     "description": "Library for interacting with the eCash Agora protocol",
     "main": "./dist/index.js",
     "scripts": {
@@ -34,6 +34,7 @@
         "@types/node": "^20.12.7",
         "chai": "^4.4.1",
         "chai-as-promised": "^7.1.1",
+        "ecash-wallet": "^2.0.1",
         "mocha": "^10.4.0",
         "mocha-junit-reporter": "^2.2.1",
         "nyc": "^15.1.0",
@@ -43,7 +44,7 @@
         "typescript": "^5.4.3"
     },
     "dependencies": {
-        "chronik-client": "^3.2.0",
-        "ecash-lib": "^3.2.0"
+        "chronik-client": "^3.4.0",
+        "ecash-lib": "^4.3.3"
     }
 }

package/tests/actions.test.ts

@@ -0,0 +1,281 @@
+// 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.
+
+/**
+ * actions.test.ts
+ *
+ * Show src/actions.ts can be used to create actions
+ * that lead to valid agora txs broadcast by ecash-wallet
+ */
+
+import { expect, use } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+import { ChronikClient } from 'chronik-client';
+import {
+    toHex,
+    fromHex,
+    payment,
+    SLP_TOKEN_TYPE_FUNGIBLE,
+    ALP_TOKEN_TYPE_STANDARD,
+    SLP_TOKEN_TYPE_MINT_VAULT,
+    SLP_TOKEN_TYPE_NFT1_GROUP,
+    SLP_TOKEN_TYPE_NFT1_CHILD,
+    slpSend,
+    Address,
+} from 'ecash-lib';
+import { TestRunner } from 'ecash-lib/dist/test/testRunner.js';
+import { Wallet } from 'ecash-wallet';
+import { Agora } from '../src/agora';
+import { AgoraOneshot } from '../src/oneshot';
+import { getAgoraPaymentAction } from '../src/actions';
+
+use(chaiAsPromised);
+
+// Configure available satoshis
+const NUM_COINS = 500;
+const COIN_VALUE = 1100000000n;
+
+describe('We can use ecash-wallet to create desired on-spec Agora txs', () => {
+    let runner: TestRunner;
+    let chronik: ChronikClient;
+
+    before(async () => {
+        // Setup using ecash-agora_base so we have agora plugin available
+        // ecash-wallet will support agora txs
+        runner = await TestRunner.setup('setup_scripts/ecash-agora_base');
+        chronik = runner.chronik;
+        await runner.setupCoins(NUM_COINS, COIN_VALUE);
+    });
+
+    after(() => {
+        runner.stop();
+    });
+    it('We can handle ALP ALP_TOKEN_TYPE_STANDARD agora actions', async () => {
+        // Init the wallet
+        const alpWallet = Wallet.fromSk(fromHex('14'.repeat(32)), chronik);
+
+        // Send 1M XEC to the wallet
+        const inputSats = 1_000_000_00n;
+        await runner.sendToScript(inputSats, alpWallet.script);
+
+        // Sync the wallet
+        await alpWallet.sync();
+
+        // We can GENESIS a fungible token with multiple mint quantities and multiple mint batons
+        const alpGenesisInfo = {
+            tokenTicker: 'ALP',
+            tokenName: 'ALP Test Token',
+            url: 'cashtab.com',
+            decimals: 0,
+            /** ALP allows arbitrary data in genesis */
+            data: 'deadbeef',
+            authPubkey: toHex(alpWallet.pk),
+        };
+
+        const genesisMintQtyAlpha = 1_000n;
+        const genesisMintQtyBeta = 2_000n;
+
+        // Construct the Action for this tx
+        const alpGenesisAction: payment.Action = {
+            outputs: [
+                /** Blank OP_RETURN at outIdx 0 */
+                { sats: 0n },
+                /** Misc XEC output at outIdx 1, there is no spec req in ALP for genesis qty at outIdx 1 */
+                { sats: 5_555n, script: alpWallet.script },
+                /** Mint qty at outIdx 2 for a token we do not have */
+                {
+                    sats: 546n,
+                    script: alpWallet.script,
+                    tokenId: payment.GENESIS_TOKEN_ID_PLACEHOLDER,
+                    atoms: genesisMintQtyAlpha,
+                },
+                /** Another misc XEC output at outIdx 2, to show we support non-consecutive mint quantities */
+                { sats: 3_333n, script: alpWallet.script },
+                /** Mint qty at outIdx 3 */
+                {
+                    sats: 546n,
+                    script: alpWallet.script,
+                    tokenId: payment.GENESIS_TOKEN_ID_PLACEHOLDER,
+                    atoms: genesisMintQtyBeta,
+                },
+                /**
+                 * Another misc XEC output at outIdx 4, to show
+                 * that mintBaton outIdx does not necessarily
+                 * immediately follow mint qty */
+                { sats: 5_555n, script: alpWallet.script },
+                /** Mint baton at outIdx 5 */
+                {
+                    sats: 546n,
+                    script: alpWallet.script,
+                    tokenId: payment.GENESIS_TOKEN_ID_PLACEHOLDER,
+                    isMintBaton: true,
+                    atoms: 0n,
+                },
+                /** Another mint baton at outIdx 6 */
+                {
+                    sats: 546n,
+                    script: alpWallet.script,
+                    tokenId: payment.GENESIS_TOKEN_ID_PLACEHOLDER,
+                    isMintBaton: true,
+                    atoms: 0n,
+                },
+            ],
+            tokenActions: [
+                {
+                    type: 'GENESIS',
+                    tokenType: {
+                        protocol: 'ALP',
+                        type: 'ALP_TOKEN_TYPE_STANDARD',
+                        number: 0,
+                    },
+                    genesisInfo: alpGenesisInfo,
+                },
+            ],
+        };
+
+        // Build and broadcast
+        const resp = await alpWallet
+            .action(alpGenesisAction)
+            .build()
+            .broadcast();
+
+        const alpGenesisTokenId = resp.broadcasted[0];
+
+        // We can list an ALP token with an agora partial
+        const agora = new Agora(chronik);
+
+        // Use selectParams to get an agora partial with the correct params
+        const alpAgoraPartial = await agora.selectParams({
+            offeredAtoms: genesisMintQtyAlpha,
+            priceNanoSatsPerAtom: 1_000_000_000n, // i.e. 1 sat per atom
+            makerPk: alpWallet.pk,
+            minAcceptedAtoms: 546n, // so, min accept is dust
+            tokenId: alpGenesisTokenId,
+            tokenType: ALP_TOKEN_TYPE_STANDARD.number,
+            tokenProtocol: 'ALP',
+        });
+
+        // Get the payment action
+        const alpListPaymentAction = getAgoraPaymentAction({
+            type: 'LIST',
+            tokenType: ALP_TOKEN_TYPE_STANDARD,
+            variant: { type: 'PARTIAL', params: alpAgoraPartial },
+        });
+
+        // Broadcast the agora LIST
+        await alpWallet.action(alpListPaymentAction).build().broadcast();
+
+        // Verify we can find the listing with Agora
+        const activeListingsByTokenId = await agora.activeOffersByTokenId(
+            alpGenesisTokenId,
+        );
+        expect(activeListingsByTokenId.length).to.equal(1);
+        expect(activeListingsByTokenId[0].token.tokenId).to.equal(
+            alpGenesisTokenId,
+        );
+    });
+    it('We cannot handle SLP SLP_TOKEN_TYPE_FUNGIBLE agora actions', async () => {
+        // Create a partial
+        // We can list an ALP token with an agora partial
+        const agora = new Agora(chronik);
+
+        // Use selectParams to get an agora partial with the correct params
+        const slpFungibleAgoraPartial = await agora.selectParams({
+            offeredAtoms: 5_000n,
+            priceNanoSatsPerAtom: 1_000_000_000n, // i.e. 1 sat per atom
+            makerPk: fromHex('04' + '13'.repeat(64)),
+            minAcceptedAtoms: 546n, // so, min accept is dust
+            tokenId: '11'.repeat(32),
+            tokenType: SLP_TOKEN_TYPE_FUNGIBLE.number,
+            tokenProtocol: 'SLP',
+        });
+
+        // We throw expected error if we try to LIST
+        expect(() =>
+            getAgoraPaymentAction({
+                type: 'LIST',
+                tokenType: SLP_TOKEN_TYPE_FUNGIBLE,
+                variant: { type: 'PARTIAL', params: slpFungibleAgoraPartial },
+            }),
+        ).to.throw('SLP is not currently supported.');
+    });
+    it('We cannot handle SLP SLP_TOKEN_TYPE_NFT1_GROUP token actions', async () => {
+        // Create a partial
+        // We can list an ALP token with an agora partial
+        const agora = new Agora(chronik);
+
+        // Use selectParams to get an agora partial with the correct params
+        const slpNft1GroupAgoraPartial = await agora.selectParams({
+            offeredAtoms: 1_000n,
+            priceNanoSatsPerAtom: 1_000_000_000n, // i.e. 1 sat per atom
+            makerPk: fromHex('04' + '13'.repeat(64)),
+            minAcceptedAtoms: 546n, // so, min accept is dust
+            tokenId: '11'.repeat(32),
+            tokenType: SLP_TOKEN_TYPE_NFT1_GROUP.number,
+            tokenProtocol: 'SLP',
+        });
+
+        // Expect error because we do not support minting SLP_TOKEN_TYPE_NFT1_GROUP tokens
+        expect(() =>
+            getAgoraPaymentAction({
+                type: 'LIST',
+                tokenType: SLP_TOKEN_TYPE_NFT1_GROUP,
+                variant: { type: 'PARTIAL', params: slpNft1GroupAgoraPartial },
+            }),
+        ).to.throw('SLP is not currently supported.');
+    });
+    it('We cannot handle SLP SLP_TOKEN_TYPE_NFT1_CHILD token actions', async () => {
+        // Create a ONESHOT offer for this NFT
+        const slpNft1GroupOneshot = new AgoraOneshot({
+            enforcedOutputs: [
+                {
+                    sats: 0n,
+                    script: slpSend(
+                        '11'.repeat(32),
+                        SLP_TOKEN_TYPE_NFT1_CHILD.number,
+                        [1n],
+                    ),
+                },
+                {
+                    sats: 10_000n,
+                    script: Address.p2pkh('11'.repeat(20)).toScript(),
+                },
+            ],
+            cancelPk: fromHex('04' + '13'.repeat(64)),
+        });
+
+        expect(() =>
+            getAgoraPaymentAction({
+                type: 'LIST',
+                tokenType: SLP_TOKEN_TYPE_NFT1_GROUP,
+                variant: { type: 'ONESHOT', params: slpNft1GroupOneshot },
+            }),
+        ).to.throw('SLP is not currently supported.');
+    });
+    it('We cannot handle SLP SLP_TOKEN_TYPE_MINT_VAULT agora actions', async () => {
+        // Create a partial
+        // We can list an ALP token with an agora partial
+        const agora = new Agora(chronik);
+
+        // Use selectParams to get an agora partial with the correct params
+        const slpMintVaultAgoraPartial = await agora.selectParams({
+            offeredAtoms: 1_000n,
+            priceNanoSatsPerAtom: 1_000_000_000n, // i.e. 1 sat per atom
+            makerPk: fromHex('04' + '13'.repeat(64)),
+            minAcceptedAtoms: 546n, // so, min accept is dust
+            tokenId: '11'.repeat(32),
+            tokenType: SLP_TOKEN_TYPE_MINT_VAULT.number,
+            tokenProtocol: 'SLP',
+        });
+
+        // Expect error because we do not support MINT for SLP_TOKEN_TYPE_MINT_VAULT tokens
+        expect(() =>
+            getAgoraPaymentAction({
+                type: 'LIST',
+                tokenType: SLP_TOKEN_TYPE_MINT_VAULT,
+                variant: { type: 'PARTIAL', params: slpMintVaultAgoraPartial },
+            }),
+        ).to.throw('SLP is not currently supported.');
+    });
+});