@1sat/wallet-toolbox 0.0.9 → 0.0.10

package/dist/api/ordinals/index.js

@@ -1,36 +1,28 @@
 /**
  * Ordinals Module
  *
- * Functions for managing ordinals/inscriptions.
+ * Skills for managing ordinals/inscriptions.
  * Returns WalletOutput[] directly from the SDK - no custom mapping needed.
  */
 import { BigNumber, Hash, LockingScript, OP, P2PKH, PublicKey, Script, Transaction, TransactionSignature, UnlockingScript, Utils, } from "@bsv/sdk";
 import { OrdLock } from "@bopen-io/templates";
 import { ORDINALS_BASKET, ORDLOCK_PREFIX, ORDLOCK_SUFFIX } from "../constants";
-// Protocol for ordinal listing key derivation (security level 1 = low, self-only)
+// ============================================================================
+// Constants
+// ============================================================================
+const ORDINAL_PROTOCOL = [1, "ordinal"];
 const ORDINAL_LISTING_PROTOCOL = [1, "ordinal listing"];
-/**
- * Check if address is a paymail.
- */
-function isPaymail(address) {
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address);
-}
-/**
- * Derive a cancel address for an ordinal listing.
- * Uses the outpoint as keyID with security level 1 (self-only).
- */
-export async function deriveCancelAddress(cwi, outpoint) {
-    const result = await cwi.getPublicKey({
+// ============================================================================
+// Internal helpers
+// ============================================================================
+async function deriveCancelAddressInternal(ctx, outpoint) {
+    const result = await ctx.wallet.getPublicKey({
         protocolID: ORDINAL_LISTING_PROTOCOL,
         keyID: outpoint,
         forSelf: true,
     });
-    const publicKey = PublicKey.fromString(result.publicKey);
-    return publicKey.toAddress();
+    return PublicKey.fromString(result.publicKey).toAddress();
 }
-/**
- * Build OrdLock script for listing an ordinal.
- */
 function buildOrdLockScript(ordAddress, payAddress, price) {
     const cancelPkh = Utils.fromBase58Check(ordAddress).data;
     const payPkh = Utils.fromBase58Check(payAddress).data;
@@ -46,31 +38,79 @@ function buildOrdLockScript(ordAddress, payAddress, price) {
         .writeBin(payoutOutput)
         .writeScript(Script.fromHex(ORDLOCK_SUFFIX));
 }
-/**
- * List ordinals from the 1sat basket.
- * Returns WalletOutput[] directly - use tags for metadata (origin:, type:, name:, own:, list:).
- */
-export async function listOrdinals(cwi, options = {}) {
-    const result = await cwi.listOutputs({
-        basket: ORDINALS_BASKET,
-        includeTags: true,
-        includeCustomInstructions: true,
-        limit: options.limit ?? 100,
-        offset: options.offset ?? 0,
-        ...options,
+function buildSerializedOutput(satoshis, script) {
+    const writer = new Utils.Writer();
+    writer.writeUInt64LEBn(new BigNumber(satoshis));
+    writer.writeVarIntNum(script.length);
+    writer.write(script);
+    return writer.toArray();
+}
+async function buildPurchaseUnlockingScript(tx, inputIndex, sourceSatoshis, lockingScript) {
+    if (tx.outputs.length < 2) {
+        throw new Error("Malformed transaction: requires at least 2 outputs");
+    }
+    const script = new UnlockingScript().writeBin(buildSerializedOutput(tx.outputs[0].satoshis ?? 0, tx.outputs[0].lockingScript.toBinary()));
+    if (tx.outputs.length > 2) {
+        const writer = new Utils.Writer();
+        for (const output of tx.outputs.slice(2)) {
+            writer.write(buildSerializedOutput(output.satoshis ?? 0, output.lockingScript.toBinary()));
+        }
+        script.writeBin(writer.toArray());
+    }
+    else {
+        script.writeOpCode(OP.OP_0);
+    }
+    const input = tx.inputs[inputIndex];
+    const sourceTXID = input.sourceTXID ?? input.sourceTransaction?.id("hex");
+    if (!sourceTXID) {
+        throw new Error("sourceTXID is required");
+    }
+    const preimage = TransactionSignature.format({
+        sourceTXID,
+        sourceOutputIndex: input.sourceOutputIndex,
+        sourceSatoshis,
+        transactionVersion: tx.version,
+        otherInputs: [],
+        inputIndex,
+        outputs: tx.outputs,
+        inputSequence: input.sequence ?? 0xffffffff,
+        subscript: lockingScript,
+        lockTime: tx.lockTime,
+        scope: TransactionSignature.SIGHASH_ALL |
+            TransactionSignature.SIGHASH_ANYONECANPAY |
+            TransactionSignature.SIGHASH_FORKID,
     });
-    return result.outputs;
+    return script.writeBin(preimage).writeOpCode(OP.OP_0);
 }
+// ============================================================================
+// Builder functions (utilities for advanced use)
+// ============================================================================
 /**
  * Build CreateActionArgs for transferring an ordinal.
  * Does NOT execute - returns params for createAction.
  */
-export async function buildTransferOrdinal(cwi, request) {
-    const { outpoint, destination } = request;
-    if (isPaymail(destination)) {
+export async function buildTransferOrdinal(ctx, request) {
+    const { outpoint, counterparty, address, paymail } = request;
+    if (!counterparty && !address && !paymail) {
+        return { error: "must-provide-counterparty-address-or-paymail" };
+    }
+    let recipientAddress;
+    if (counterparty) {
+        const { publicKey } = await ctx.wallet.getPublicKey({
+            protocolID: ORDINAL_PROTOCOL,
+            keyID: outpoint,
+            counterparty,
+            forSelf: false,
+        });
+        recipientAddress = PublicKey.fromString(publicKey).toAddress();
+    }
+    else if (paymail) {
         return { error: "paymail-not-yet-implemented" };
     }
-    const result = await cwi.listOutputs({
+    else {
+        recipientAddress = address;
+    }
+    const result = await ctx.wallet.listOutputs({
         basket: ORDINALS_BASKET,
         include: "locking scripts",
         limit: 10000,
@@ -81,366 +121,446 @@ export async function buildTransferOrdinal(cwi, request) {
     return {
         description: "Transfer ordinal",
         inputs: [{ outpoint, inputDescription: "Ordinal to transfer" }],
-        outputs: [{
-                lockingScript: new P2PKH().lock(destination).toHex(),
+        outputs: [
+            {
+                lockingScript: new P2PKH().lock(recipientAddress).toHex(),
                 satoshis: 1,
                 outputDescription: "Ordinal transfer",
-            }],
+            },
+        ],
     };
 }
 /**
  * Build CreateActionArgs for listing an ordinal for sale.
  * Does NOT execute - returns params for createAction.
- * If cancelAddress is not provided, it will be derived from the CWI.
  */
-export async function buildListOrdinal(cwi, request) {
+export async function buildListOrdinal(ctx, request) {
     const { outpoint, price, payAddress } = request;
     if (!payAddress)
         return { error: "missing-pay-address" };
     if (price <= 0)
         return { error: "invalid-price" };
-    const result = await cwi.listOutputs({
+    const result = await ctx.wallet.listOutputs({
         basket: ORDINALS_BASKET,
+        includeTags: true,
         include: "locking scripts",
         limit: 10000,
     });
-    if (!result.outputs.find((o) => o.outpoint === outpoint)) {
+    const sourceOutput = result.outputs.find((o) => o.outpoint === outpoint);
+    if (!sourceOutput) {
         return { error: "ordinal-not-found" };
     }
-    // Derive cancel address if not provided
-    const cancelAddress = request.cancelAddress ?? await deriveCancelAddress(cwi, outpoint);
+    const typeTag = sourceOutput.tags?.find((t) => t.startsWith("type:"));
+    const originTag = sourceOutput.tags?.find((t) => t.startsWith("origin:"));
+    const originOutpoint = originTag ? originTag.slice(7) : outpoint;
+    const cancelAddress = await deriveCancelAddressInternal(ctx, outpoint);
     const lockingScript = buildOrdLockScript(cancelAddress, payAddress, price);
+    const tags = ["ordlock", `origin:${originOutpoint}`, `price:${price}`];
+    if (typeTag)
+        tags.push(typeTag);
     return {
         description: `List ordinal for ${price} sats`,
         inputs: [{ outpoint, inputDescription: "Ordinal to list" }],
-        outputs: [{
+        outputs: [
+            {
                 lockingScript: lockingScript.toHex(),
                 satoshis: 1,
                 outputDescription: `List ordinal for ${price} sats`,
                 basket: ORDINALS_BASKET,
-                tags: [`origin:${outpoint}`, `price:${price}`],
-            }],
+                tags,
+                customInstructions: JSON.stringify({
+                    protocolID: ORDINAL_LISTING_PROTOCOL,
+                    keyID: outpoint,
+                }),
+            },
+        ],
     };
 }
 /**
- * Transfer an ordinal to a new address.
+ * List ordinals from the wallet.
+ */
+export const listOrdinals = {
+    meta: {
+        name: "listOrdinals",
+        description: "List ordinals/inscriptions from the wallet",
+        category: "ordinals",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "integer", description: "Max number of ordinals to return (default: 100)" },
+                offset: { type: "integer", description: "Offset for pagination (default: 0)" },
+            },
+        },
+    },
+    async execute(ctx, input) {
+        const result = await ctx.wallet.listOutputs({
+            basket: ORDINALS_BASKET,
+            includeTags: true,
+            includeCustomInstructions: true,
+            limit: input.limit ?? 100,
+            offset: input.offset ?? 0,
+        });
+        return result.outputs;
+    },
+};
+/**
+ * Derive a cancel address for an ordinal listing.
+ */
+export const deriveCancelAddress = {
+    meta: {
+        name: "deriveCancelAddress",
+        description: "Derive the cancel address for an ordinal listing",
+        category: "ordinals",
+        inputSchema: {
+            type: "object",
+            properties: {
+                outpoint: { type: "string", description: "Outpoint of the ordinal listing" },
+            },
+            required: ["outpoint"],
+        },
+    },
+    async execute(ctx, input) {
+        return deriveCancelAddressInternal(ctx, input.outpoint);
+    },
+};
+/**
+ * Transfer an ordinal to a new owner.
  */
-export async function transferOrdinal(cwi, request) {
-    try {
-        const params = await buildTransferOrdinal(cwi, request);
-        if ("error" in params) {
-            return params;
+export const transferOrdinal = {
+    meta: {
+        name: "transferOrdinal",
+        description: "Transfer an ordinal to a new owner via counterparty pubkey, address, or paymail",
+        category: "ordinals",
+        inputSchema: {
+            type: "object",
+            properties: {
+                outpoint: { type: "string", description: "Outpoint of the ordinal (txid_vout format)" },
+                counterparty: { type: "string", description: "Recipient identity public key (hex)" },
+                address: { type: "string", description: "Recipient P2PKH address" },
+                paymail: { type: "string", description: "Recipient paymail address" },
+            },
+            required: ["outpoint"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const params = await buildTransferOrdinal(ctx, input);
+            if ("error" in params) {
+                return params;
+            }
+            const result = await ctx.wallet.createAction(params);
+            if (!result.txid) {
+                return { error: "no-txid-returned" };
+            }
+            return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
         }
-        const result = await cwi.createAction(params);
-        if (!result.txid) {
-            return { error: "no-txid-returned" };
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
         }
-        return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : "unknown-error" };
-    }
-}
+    },
+};
 /**
  * List an ordinal for sale on the global orderbook.
  */
-export async function listOrdinal(cwi, request) {
-    try {
-        const params = await buildListOrdinal(cwi, request);
-        if ("error" in params) {
-            return params;
+export const listOrdinal = {
+    meta: {
+        name: "listOrdinal",
+        description: "List an ordinal for sale on the global orderbook",
+        category: "ordinals",
+        inputSchema: {
+            type: "object",
+            properties: {
+                outpoint: { type: "string", description: "Outpoint of the ordinal to list" },
+                price: { type: "integer", description: "Price in satoshis" },
+                payAddress: { type: "string", description: "Address to receive payment on purchase" },
+            },
+            required: ["outpoint", "price", "payAddress"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const params = await buildListOrdinal(ctx, input);
+            if ("error" in params) {
+                return params;
+            }
+            const result = await ctx.wallet.createAction(params);
+            if (!result.txid) {
+                return { error: "no-txid-returned" };
+            }
+            return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
         }
-        const result = await cwi.createAction(params);
-        if (!result.txid) {
-            return { error: "no-txid-returned" };
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
         }
-        return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : "unknown-error" };
-    }
-}
+    },
+};
 /**
  * Cancel an ordinal listing.
- * Uses the origin tag to recover the keyID for signing.
- * Cancel unlock script: <sig> <pubkey> OP_1
  */
-export async function cancelListing(cwi, outpoint) {
-    try {
-        // Find the listing in our wallet
-        const result = await cwi.listOutputs({
-            basket: ORDINALS_BASKET,
-            includeTags: true,
-            include: "locking scripts",
-            limit: 10000,
-        });
-        const listing = result.outputs.find((o) => o.outpoint === outpoint);
-        if (!listing) {
-            return { error: "listing-not-found" };
-        }
-        // Get the origin tag to recover the keyID
-        const originTag = listing.tags?.find((t) => t.startsWith("origin:"));
-        if (!originTag) {
-            return { error: "missing-origin-tag" };
-        }
-        const originOutpoint = originTag.slice(7); // Remove "origin:" prefix
-        // Derive the cancel address to get output destination
-        const cancelAddress = await deriveCancelAddress(cwi, originOutpoint);
-        // Create transaction with signAndProcess: false
-        const createResult = await cwi.createAction({
-            description: "Cancel ordinal listing",
-            inputs: [{
-                    outpoint,
-                    inputDescription: "Listed ordinal",
-                    unlockingScriptLength: 108, // sig (73) + pubkey (34) + OP_1 (1)
-                }],
-            outputs: [{
-                    lockingScript: new P2PKH().lock(cancelAddress).toHex(),
-                    satoshis: 1,
-                    outputDescription: "Cancelled listing",
-                    basket: ORDINALS_BASKET,
-                }],
-            options: { signAndProcess: false },
-        });
-        if ("error" in createResult && createResult.error) {
-            return { error: String(createResult.error) };
-        }
-        if (!createResult.signableTransaction) {
-            return { error: "no-signable-transaction" };
-        }
-        // Parse transaction for signing
-        const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
-        const input = tx.inputs[0];
-        const lockingScript = Script.fromHex(listing.lockingScript);
-        // Build preimage for signature
-        const sourceTXID = input.sourceTXID ?? input.sourceTransaction?.id("hex");
-        if (!sourceTXID) {
-            return { error: "missing-source-txid" };
-        }
-        const preimage = TransactionSignature.format({
-            sourceTXID,
-            sourceOutputIndex: input.sourceOutputIndex,
-            sourceSatoshis: listing.satoshis,
-            transactionVersion: tx.version,
-            otherInputs: [],
-            inputIndex: 0,
-            outputs: tx.outputs,
-            inputSequence: input.sequence ?? 0xffffffff,
-            subscript: lockingScript,
-            lockTime: tx.lockTime,
-            scope: TransactionSignature.SIGHASH_ALL |
-                TransactionSignature.SIGHASH_ANYONECANPAY |
-                TransactionSignature.SIGHASH_FORKID,
-        });
-        // Hash preimage for signing
-        const sighash = Hash.sha256(Hash.sha256(preimage));
-        // Get signature via createSignature using origin outpoint as keyID
-        const { signature } = await cwi.createSignature({
-            protocolID: ORDINAL_LISTING_PROTOCOL,
-            keyID: originOutpoint,
-            counterparty: "self",
-            hashToDirectlySign: Array.from(sighash),
-        });
-        // Get public key
-        const { publicKey } = await cwi.getPublicKey({
-            protocolID: ORDINAL_LISTING_PROTOCOL,
-            keyID: originOutpoint,
-            forSelf: true,
-        });
-        // Build cancel unlocking script: <sig> <pubkey> OP_1
-        const unlockingScript = new UnlockingScript()
-            .writeBin(signature)
-            .writeBin(Utils.toArray(publicKey, "hex"))
-            .writeOpCode(OP.OP_1);
-        // Sign and broadcast
-        const signResult = await cwi.signAction({
-            reference: createResult.signableTransaction.reference,
-            spends: {
-                0: { unlockingScript: unlockingScript.toHex() },
+export const cancelListing = {
+    meta: {
+        name: "cancelListing",
+        description: "Cancel an ordinal listing and return the ordinal to the wallet",
+        category: "ordinals",
+        inputSchema: {
+            type: "object",
+            properties: {
+                outpoint: { type: "string", description: "Outpoint of the listing to cancel" },
             },
-        });
-        if ("error" in signResult) {
-            return { error: String(signResult.error) };
+            required: ["outpoint"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const { outpoint } = input;
+            const result = await ctx.wallet.listOutputs({
+                basket: ORDINALS_BASKET,
+                includeTags: true,
+                includeCustomInstructions: true,
+                include: "locking scripts",
+                limit: 10000,
+            });
+            const listing = result.outputs.find((o) => o.outpoint === outpoint);
+            if (!listing) {
+                return { error: "listing-not-found" };
+            }
+            if (!listing.customInstructions) {
+                return { error: "missing-custom-instructions" };
+            }
+            const { protocolID, keyID } = JSON.parse(listing.customInstructions);
+            const typeTag = listing.tags?.find((t) => t.startsWith("type:"));
+            const originTag = listing.tags?.find((t) => t.startsWith("origin:"));
+            const cancelAddress = await deriveCancelAddressInternal(ctx, keyID);
+            const tags = [];
+            if (typeTag)
+                tags.push(typeTag);
+            if (originTag)
+                tags.push(originTag);
+            const createResult = await ctx.wallet.createAction({
+                description: "Cancel ordinal listing",
+                inputs: [
+                    {
+                        outpoint,
+                        inputDescription: "Listed ordinal",
+                        unlockingScriptLength: 108,
+                    },
+                ],
+                outputs: [
+                    {
+                        lockingScript: new P2PKH().lock(cancelAddress).toHex(),
+                        satoshis: 1,
+                        outputDescription: "Cancelled listing",
+                        basket: ORDINALS_BASKET,
+                        tags,
+                        customInstructions: JSON.stringify({ protocolID, keyID }),
+                    },
+                ],
+                options: { signAndProcess: false },
+            });
+            if ("error" in createResult && createResult.error) {
+                return { error: String(createResult.error) };
+            }
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
+            }
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            const txInput = tx.inputs[0];
+            const lockingScript = Script.fromHex(listing.lockingScript);
+            const sourceTXID = txInput.sourceTXID ?? txInput.sourceTransaction?.id("hex");
+            if (!sourceTXID) {
+                return { error: "missing-source-txid" };
+            }
+            const preimage = TransactionSignature.format({
+                sourceTXID,
+                sourceOutputIndex: txInput.sourceOutputIndex,
+                sourceSatoshis: listing.satoshis,
+                transactionVersion: tx.version,
+                otherInputs: [],
+                inputIndex: 0,
+                outputs: tx.outputs,
+                inputSequence: txInput.sequence ?? 0xffffffff,
+                subscript: lockingScript,
+                lockTime: tx.lockTime,
+                scope: TransactionSignature.SIGHASH_ALL |
+                    TransactionSignature.SIGHASH_ANYONECANPAY |
+                    TransactionSignature.SIGHASH_FORKID,
+            });
+            const sighash = Hash.sha256(Hash.sha256(preimage));
+            const { signature } = await ctx.wallet.createSignature({
+                protocolID,
+                keyID,
+                counterparty: "self",
+                hashToDirectlySign: Array.from(sighash),
+            });
+            const { publicKey } = await ctx.wallet.getPublicKey({
+                protocolID,
+                keyID,
+                forSelf: true,
+            });
+            const unlockingScript = new UnlockingScript()
+                .writeBin(signature)
+                .writeBin(Utils.toArray(publicKey, "hex"))
+                .writeOpCode(OP.OP_1);
+            const signResult = await ctx.wallet.signAction({
+                reference: createResult.signableTransaction.reference,
+                spends: {
+                    0: { unlockingScript: unlockingScript.toHex() },
+                },
+            });
+            if ("error" in signResult) {
+                return { error: String(signResult.error) };
+            }
+            return {
+                txid: signResult.txid,
+                rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
+            };
         }
-        return {
-            txid: signResult.txid,
-            rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
-        };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : "unknown-error" };
-    }
-}
-/**
- * Build serialized transaction output (satoshis + script) for OrdLock unlock.
- */
-function buildSerializedOutput(satoshis, script) {
-    const writer = new Utils.Writer();
-    writer.writeUInt64LEBn(new BigNumber(satoshis));
-    writer.writeVarIntNum(script.length);
-    writer.write(script);
-    return writer.toArray();
-}
-/**
- * Build OrdLock purchase unlocking script.
- * The purchase path requires no signature - just preimage and output data.
- */
-async function buildPurchaseUnlockingScript(tx, inputIndex, sourceSatoshis, lockingScript) {
-    if (tx.outputs.length < 2) {
-        throw new Error("Malformed transaction: requires at least 2 outputs");
-    }
-    const script = new UnlockingScript()
-        .writeBin(buildSerializedOutput(tx.outputs[0].satoshis ?? 0, tx.outputs[0].lockingScript.toBinary()));
-    if (tx.outputs.length > 2) {
-        const writer = new Utils.Writer();
-        for (const output of tx.outputs.slice(2)) {
-            writer.write(buildSerializedOutput(output.satoshis ?? 0, output.lockingScript.toBinary()));
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
         }
-        script.writeBin(writer.toArray());
-    }
-    else {
-        script.writeOpCode(OP.OP_0);
-    }
-    const input = tx.inputs[inputIndex];
-    const sourceTXID = input.sourceTXID ?? input.sourceTransaction?.id("hex");
-    if (!sourceTXID) {
-        throw new Error("sourceTXID is required");
-    }
-    const preimage = TransactionSignature.format({
-        sourceTXID,
-        sourceOutputIndex: input.sourceOutputIndex,
-        sourceSatoshis,
-        transactionVersion: tx.version,
-        otherInputs: [],
-        inputIndex,
-        outputs: tx.outputs,
-        inputSequence: input.sequence ?? 0xffffffff,
-        subscript: lockingScript,
-        lockTime: tx.lockTime,
-        scope: TransactionSignature.SIGHASH_ALL |
-            TransactionSignature.SIGHASH_ANYONECANPAY |
-            TransactionSignature.SIGHASH_FORKID
-    });
-    return script.writeBin(preimage).writeOpCode(OP.OP_0);
-}
+    },
+};
 /**
  * Purchase an ordinal from the global orderbook.
- *
- * Flow:
- * 1. Fetch listing BEEF to get the locking script
- * 2. Decode OrdLock to get price and payout
- * 3. Build P2PKH output for buyer
- * 4. Build payment output for seller
- * 5. Build custom OrdLock purchase unlock (preimage only, no signature)
  */
-export async function purchaseOrdinal(cwi, request, services) {
-    try {
-        const { outpoint, marketplaceAddress, marketplaceRate } = request;
-        if (!services) {
-            return { error: "services-required-for-purchase" };
-        }
-        // Parse outpoint
-        const parts = outpoint.split("_");
-        if (parts.length !== 2) {
-            return { error: "invalid-outpoint-format" };
-        }
-        const [txid, voutStr] = parts;
-        const vout = parseInt(voutStr, 10);
-        // Fetch listing BEEF to get the locking script
-        const beef = await services.getBeefForTxid(txid);
-        const listingBeefTx = beef.findTxid(txid);
-        if (!listingBeefTx?.tx) {
-            return { error: "listing-transaction-not-found" };
-        }
-        const listingOutput = listingBeefTx.tx.outputs[vout];
-        if (!listingOutput) {
-            return { error: "listing-output-not-found" };
-        }
-        // Decode OrdLock from listing script
-        const ordLockData = OrdLock.decode(listingOutput.lockingScript);
-        if (!ordLockData) {
-            return { error: "not-an-ordlock-listing" };
-        }
-        // Derive our ordinal receive address
-        const { publicKey } = await cwi.getPublicKey({
-            protocolID: [1, "ordinals"],
-            keyID: outpoint,
-            counterparty: "self",
-            forSelf: true,
-        });
-        const ourOrdAddress = PublicKey.fromString(publicKey).toAddress();
-        // Build outputs
-        const outputs = [];
-        // Output 0: Ordinal to buyer (P2PKH)
-        const p2pkh = new P2PKH();
-        outputs.push({
-            lockingScript: p2pkh.lock(ourOrdAddress).toHex(),
-            satoshis: 1,
-            outputDescription: "Purchased ordinal",
-            basket: ORDINALS_BASKET,
-        });
-        // Output 1: Payment to seller (from payout in OrdLock)
-        // Parse payout: 8-byte LE satoshis + varint script length + script
-        const payoutReader = new Utils.Reader(ordLockData.payout);
-        const payoutSatoshis = payoutReader.readUInt64LEBn().toNumber();
-        const payoutScriptLen = payoutReader.readVarIntNum();
-        const payoutScriptBin = payoutReader.read(payoutScriptLen);
-        const payoutLockingScript = LockingScript.fromBinary(payoutScriptBin);
-        outputs.push({
-            lockingScript: payoutLockingScript.toHex(),
-            satoshis: payoutSatoshis,
-            outputDescription: "Payment to seller",
-        });
-        // Output 2+ (optional): Marketplace fee
-        if (marketplaceAddress && marketplaceRate && marketplaceRate > 0) {
-            const marketFee = Math.ceil(payoutSatoshis * marketplaceRate);
-            if (marketFee > 0) {
-                outputs.push({
-                    lockingScript: p2pkh.lock(marketplaceAddress).toHex(),
-                    satoshis: marketFee,
-                    outputDescription: "Marketplace fee",
-                });
+export const purchaseOrdinal = {
+    meta: {
+        name: "purchaseOrdinal",
+        description: "Purchase an ordinal from the global orderbook",
+        category: "ordinals",
+        requiresServices: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                outpoint: { type: "string", description: "Outpoint of the listing to purchase" },
+                marketplaceAddress: { type: "string", description: "Marketplace address for fees" },
+                marketplaceRate: { type: "number", description: "Marketplace fee rate (0-1)" },
+                contentType: { type: "string", description: "Content type (auto-detected if not provided)" },
+                origin: { type: "string", description: "Origin outpoint (auto-detected if not provided)" },
+            },
+            required: ["outpoint"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const { outpoint, marketplaceAddress, marketplaceRate } = input;
+            if (!ctx.services) {
+                return { error: "services-required-for-purchase" };
             }
+            const parts = outpoint.split("_");
+            if (parts.length !== 2) {
+                return { error: "invalid-outpoint-format" };
+            }
+            const [txid, voutStr] = parts;
+            const vout = Number.parseInt(voutStr, 10);
+            let { contentType, origin } = input;
+            if (!contentType || !origin) {
+                const metadata = await ctx.services.ordfs.getMetadata(outpoint);
+                contentType = contentType ?? metadata.contentType;
+                origin = origin ?? metadata.origin ?? outpoint;
+            }
+            const beef = await ctx.services.getBeefForTxid(txid);
+            const listingBeefTx = beef.findTxid(txid);
+            if (!listingBeefTx?.tx) {
+                return { error: "listing-transaction-not-found" };
+            }
+            const listingOutput = listingBeefTx.tx.outputs[vout];
+            if (!listingOutput) {
+                return { error: "listing-output-not-found" };
+            }
+            const ordLockData = OrdLock.decode(listingOutput.lockingScript);
+            if (!ordLockData) {
+                return { error: "not-an-ordlock-listing" };
+            }
+            const { publicKey } = await ctx.wallet.getPublicKey({
+                protocolID: ORDINAL_PROTOCOL,
+                keyID: outpoint,
+                counterparty: "self",
+                forSelf: true,
+            });
+            const ourOrdAddress = PublicKey.fromString(publicKey).toAddress();
+            const outputs = [];
+            const p2pkh = new P2PKH();
+            outputs.push({
+                lockingScript: p2pkh.lock(ourOrdAddress).toHex(),
+                satoshis: 1,
+                outputDescription: "Purchased ordinal",
+                basket: ORDINALS_BASKET,
+                tags: [`type:${contentType}`, `origin:${origin}`],
+                customInstructions: JSON.stringify({
+                    protocolID: ORDINAL_PROTOCOL,
+                    keyID: outpoint,
+                }),
+            });
+            const payoutReader = new Utils.Reader(ordLockData.payout);
+            const payoutSatoshis = payoutReader.readUInt64LEBn().toNumber();
+            const payoutScriptLen = payoutReader.readVarIntNum();
+            const payoutScriptBin = payoutReader.read(payoutScriptLen);
+            const payoutLockingScript = LockingScript.fromBinary(payoutScriptBin);
+            outputs.push({
+                lockingScript: payoutLockingScript.toHex(),
+                satoshis: payoutSatoshis,
+                outputDescription: "Payment to seller",
+            });
+            if (marketplaceAddress && marketplaceRate && marketplaceRate > 0) {
+                const marketFee = Math.ceil(payoutSatoshis * marketplaceRate);
+                if (marketFee > 0) {
+                    outputs.push({
+                        lockingScript: p2pkh.lock(marketplaceAddress).toHex(),
+                        satoshis: marketFee,
+                        outputDescription: "Marketplace fee",
+                    });
+                }
+            }
+            const createResult = await ctx.wallet.createAction({
+                description: `Purchase ordinal for ${payoutSatoshis} sats`,
+                inputBEEF: beef.toBinary(),
+                inputs: [
+                    {
+                        outpoint,
+                        inputDescription: "Listed ordinal",
+                        unlockingScriptLength: 500,
+                    },
+                ],
+                outputs,
+                options: { signAndProcess: false },
+            });
+            if ("error" in createResult && createResult.error) {
+                return { error: String(createResult.error) };
+            }
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
+            }
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            const unlockingScript = await buildPurchaseUnlockingScript(tx, 0, listingOutput.satoshis ?? 1, listingOutput.lockingScript);
+            const signResult = await ctx.wallet.signAction({
+                reference: createResult.signableTransaction.reference,
+                spends: {
+                    0: { unlockingScript: unlockingScript.toHex() },
+                },
+            });
+            if ("error" in signResult) {
+                return { error: String(signResult.error) };
+            }
+            return {
+                txid: signResult.txid,
+                rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
+            };
         }
-        // Create the transaction with signAndProcess: false
-        // The listing input needs custom unlocking script
-        const createResult = await cwi.createAction({
-            description: `Purchase ordinal for ${payoutSatoshis} sats`,
-            inputBEEF: beef.toBinary(),
-            inputs: [{
-                    outpoint,
-                    inputDescription: "Listed ordinal",
-                    unlockingScriptLength: 500, // Estimate for purchase unlock (preimage + outputs)
-                }],
-            outputs,
-            options: { signAndProcess: false },
-        });
-        if ("error" in createResult && createResult.error) {
-            return { error: String(createResult.error) };
-        }
-        if (!createResult.signableTransaction) {
-            return { error: "no-signable-transaction" };
-        }
-        // Parse the transaction to build purchase unlock
-        const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
-        // Build purchase unlocking script
-        const unlockingScript = await buildPurchaseUnlockingScript(tx, 0, listingOutput.satoshis ?? 1, listingOutput.lockingScript);
-        // Sign and broadcast
-        const signResult = await cwi.signAction({
-            reference: createResult.signableTransaction.reference,
-            spends: {
-                0: { unlockingScript: unlockingScript.toHex() },
-            },
-        });
-        if ("error" in signResult) {
-            return { error: String(signResult.error) };
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
         }
-        return {
-            txid: signResult.txid,
-            rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
-        };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : "unknown-error" };
-    }
-}
+    },
+};
+// ============================================================================
+// Module exports
+// ============================================================================
+/** All ordinals skills for registry */
+export const ordinalsSkills = [
+    listOrdinals,
+    deriveCancelAddress,
+    transferOrdinal,
+    listOrdinal,
+    cancelListing,
+    purchaseOrdinal,
+];