@aibtc/mcp-server 1.70.1 → 1.72.0

package/dist/services/stacking.service.js

@@ -1,155 +1,448 @@
-import { uintCV, tupleCV, bufferCV, noneCV, someCV } from "@stacks/transactions";
+/**
+ * PoX-5 stacking.
+ *
+ * PoX-5 replaced pox-4 at reward cycle 141 on mainnet, and it is not a rename:
+ *
+ * - Every stake names a SIGNER MANAGER, a contract implementing pox-5's
+ *   `signer-manager-trait`. There is no pool delegation (`delegate-stx`) and no
+ *   PoX reward address on the stake itself; the manager's `validate-stake!`
+ *   decides who may join and reads any payout preferences out of
+ *   `signer-calldata`.
+ * - Rewards are paid in sBTC to the signer manager, not the staker. Getting a
+ *   staker paid takes the manager pulling its share out of pox-5
+ *   (`manager.claim-rewards`) and then paying the staker
+ *   (`manager.claim-staker-rewards`). Each manager implements that second step
+ *   its own way, and some pay out off-chain, so the claim path is read from the
+ *   manager's interface rather than assumed.
+ * - `stake`, `stake-update` and `unstake` are refused during the prepare phase
+ *   (the last `prepare-cycle-length` blocks of a cycle).
+ *
+ * Locking STX is not a transfer, so these calls carry pox-5's own post-condition
+ * types (a staking lock amount, or "performs PoX") rather than STX transfer
+ * conditions, and they are not metered against the spend limit.
+ */
+import { Pc, PostConditionMode, bufferCV, contractPrincipalCV, cvToJSON, hexToCV, listCV, noneCV, principalCV, serializeCV, someCV, tupleCV, uintCV, } from "@stacks/transactions";
 import { getHiroApi } from "./hiro-api.js";
 import { getContracts, parseContractId } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
-import { createStxPostCondition } from "../transactions/post-conditions.js";
 // ============================================================================
-// Stacking Service
+// Constants mirrored from pox-5
+// ============================================================================
+/** pox-5 `MAX_NUM_CYCLES`. */
+export const MAX_STAKE_CYCLES = 96;
+/** Hard stop when walking the signer-set linked list. */
+const MAX_SIGNERS_WALKED = 200;
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Decode a Clarity value to plain JS: tuples to objects, lists to arrays,
+ * optionals to value-or-null, responses to their inner value, uints to strings.
+ * (`cvToValue` only unwraps the outermost layer.)
+ */
+function plain(cv) {
+    const unwrap = (node) => {
+        if (node === null || typeof node !== "object")
+            return node;
+        if (Array.isArray(node))
+            return node.map(unwrap);
+        const n = node;
+        if (typeof n.type === "string" && "value" in n) {
+            if (n.type.startsWith("(optional") && n.value === null)
+                return null;
+            return unwrap(n.value);
+        }
+        return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, unwrap(v)]));
+    };
+    return unwrap(cvToJSON(cv));
+}
+function toNumber(v) {
+    return Number(v);
+}
+function toBigInt(v) {
+    return BigInt(v);
+}
+function assertContractId(id, label) {
+    if (!/^S[PMTN][0-9A-Z]{28,40}\.[a-zA-Z][a-zA-Z0-9-_]{0,39}$/.test(id)) {
+        throw new Error(`${label} must be a contract id like SP....name, got "${id}"`);
+    }
+}
+function contractCV(id) {
+    const { address, name } = parseContractId(id);
+    return contractPrincipalCV(address, name);
+}
+function calldataCV(calldata) {
+    if (!calldata)
+        return noneCV();
+    if (calldata.length > 500) {
+        throw new Error(`signer calldata is ${calldata.length} bytes; pox-5 accepts at most 500`);
+    }
+    return someCV(bufferCV(calldata));
+}
+/**
+ * Payout calldata in the shape reference signer managers decode:
+ * `{ pox-addr: { version, hashbytes }, max-fee }`. Managers derived from the
+ * pox-5 reference implementation use it to pay rewards to a Bitcoin address via
+ * an sBTC withdrawal, capped at `max-fee` sats of withdrawal fee. Whether a given
+ * manager accepts it is up to that manager's `validate-stake!`.
+ */
+export function buildPayoutCalldata(poxAddr, maxFeeSats) {
+    const serialized = serializeCV(tupleCV({
+        "pox-addr": tupleCV({
+            version: bufferCV(Uint8Array.from([poxAddr.version])),
+            hashbytes: bufferCV(Buffer.from(poxAddr.hashbytesHex, "hex")),
+        }),
+        "max-fee": uintCV(maxFeeSats),
+    }));
+    return typeof serialized === "string"
+        ? Uint8Array.from(Buffer.from(serialized, "hex"))
+        : serialized;
+}
+// ============================================================================
+// Service
 // ============================================================================
 export class StackingService {
     network;
     hiro;
-    contracts;
+    poxContract;
     constructor(network) {
         this.network = network;
         this.hiro = getHiroApi(network);
-        this.contracts = getContracts(network);
+        this.poxContract = getContracts(network).POX_5;
     }
-    /**
-     * Get current PoX (Proof of Transfer) info
-     */
-    async getPoxInfo() {
-        return this.hiro.getPoxInfo();
+    get contractId() {
+        return this.poxContract;
     }
-    /**
-     * Get stacking status for an address
-     * Note: Returns whether the address is stacking, but detailed amounts require proper CV parsing
-     */
-    async getStackingStatus(address) {
-        try {
-            const result = await this.hiro.callReadOnlyFunction(this.contracts.POX_4, "get-stacker-info", [{ type: "principal", value: address }], address);
-            if (result.okay && result.result) {
-                const isStacked = result.result.includes("some");
-                return {
-                    stacked: isStacked,
-                    amountMicroStx: "0", // Requires CV parsing
-                    amountStx: "0",
-                    firstRewardCycle: 0,
-                    lockPeriod: 0,
-                    unlockHeight: 0,
-                };
-            }
-        }
-        catch {
-            // Stacker info not found
+    async read(contractId, functionName, args = []) {
+        const sender = parseContractId(this.poxContract).address;
+        const result = await this.hiro.callReadOnlyFunction(contractId, functionName, args, sender);
+        if (!result.okay || !result.result) {
+            throw new Error(`${contractId}::${functionName} failed: ${result.cause ?? "no result"}`);
         }
+        return plain(hexToCV(result.result));
+    }
+    readPox(functionName, args = []) {
+        return this.read(this.poxContract, functionName, args);
+    }
+    // --------------------------------------------------------------------------
+    // Reads
+    // --------------------------------------------------------------------------
+    async getPoxState() {
+        const [info, core] = await Promise.all([
+            this.readPox("get-pox-info"),
+            this.hiro.getCoreApiInfo(),
+        ]);
+        const firstBurnHeight = toNumber(info["first-burnchain-block-height"]);
+        const rewardCycleLength = toNumber(info["reward-cycle-length"]);
+        const prepareCycleLength = toNumber(info["prepare-cycle-length"]);
+        const burnHeight = core.burn_block_height;
+        // Mirrors pox-5 burn-height-to-reward-cycle / reward-cycle-to-burn-height.
+        const rewardCycle = Math.floor((burnHeight - firstBurnHeight) / rewardCycleLength);
+        const nextCycleStartHeight = firstBurnHeight + (rewardCycle + 1) * rewardCycleLength;
+        const preparePhaseStartHeight = nextCycleStartHeight - prepareCycleLength;
         return {
-            stacked: false,
-            amountMicroStx: "0",
-            amountStx: "0",
-            firstRewardCycle: 0,
-            lockPeriod: 0,
-            unlockHeight: 0,
+            contractId: this.poxContract,
+            burnHeight,
+            rewardCycle,
+            firstBurnHeight,
+            rewardCycleLength,
+            prepareCycleLength,
+            nextCycleStartHeight,
+            preparePhaseStartHeight,
+            inPreparePhase: burnHeight >= preparePhaseStartHeight,
+            signerSetMinUstx: toBigInt(info["min-amount-ustx"]),
+            totalLiquidSupplyUstx: toBigInt(info["total-liquid-supply-ustx"]),
         };
     }
-    /**
-     * Stack STX tokens
-     */
-    async stack(account, amount, poxAddress, startBurnHeight, lockPeriod) {
-        const { address: contractAddress, name: contractName } = parseContractId(this.contracts.POX_4);
-        const functionArgs = [
-            uintCV(amount),
-            tupleCV({
-                version: bufferCV(Buffer.from([poxAddress.version])),
-                hashbytes: bufferCV(Buffer.from(poxAddress.hashbytes, "hex")),
-            }),
-            uintCV(startBurnHeight),
-            uintCV(lockPeriod),
-        ];
-        // Add post condition: sender must lock exactly `amount` of STX
-        const postCondition = createStxPostCondition(account.address, "eq", amount);
-        return callContract(account, {
-            contractAddress,
-            contractName,
-            functionName: "stack-stx",
-            functionArgs,
-            postConditions: [postCondition],
+    rewardCycleStartHeight(pox, cycle) {
+        return pox.firstBurnHeight + cycle * pox.rewardCycleLength;
+    }
+    async getStakerInfo(address, pox) {
+        const raw = (await this.readPox("get-staker-info", [principalCV(address)]));
+        if (!raw)
+            return null;
+        const state = pox ?? (await this.getPoxState());
+        const firstRewardCycle = toNumber(raw["first-reward-cycle"]);
+        const numCycles = toNumber(raw["num-cycles"]);
+        const unlockCycle = firstRewardCycle + numCycles;
+        return {
+            amountUstx: toBigInt(raw["amount-ustx"]),
+            firstRewardCycle,
+            numCycles,
+            unlockCycle,
+            unlockBurnHeight: this.rewardCycleStartHeight(state, unlockCycle),
+            signerManager: String(raw["signer"]),
+        };
+    }
+    async getBondMembership(address) {
+        const raw = (await this.readPox("get-bond-membership", [principalCV(address)]));
+        if (!raw)
+            return null;
+        return {
+            bondIndex: toNumber(raw["bond-index"]),
+            amountUstx: toBigInt(raw["amount-ustx"]),
+            amountSats: toBigInt(raw["amount-sats"]),
+            isL1Lock: Boolean(raw["is-l1-lock"]),
+            signerManager: String(raw["signer"]),
+        };
+    }
+    async getStakingStatus(address) {
+        const pox = await this.getPoxState();
+        const [staking, bond, balance] = await Promise.all([
+            this.getStakerInfo(address, pox),
+            this.getBondMembership(address),
+            this.hiro.getStxBalance(address),
+        ]);
+        const balanceUstx = BigInt(balance.balance);
+        const lockedUstx = BigInt(balance.locked);
+        return {
+            address,
+            pox,
+            staking,
+            bond,
+            account: {
+                balanceUstx,
+                lockedUstx,
+                unlockedUstx: balanceUstx - lockedUstx,
+                burnchainUnlockHeight: balance.burnchain_unlock_height,
+            },
+        };
+    }
+    /** Whether pox-5 has a signer key registered for this manager. */
+    async isRegisteredSigner(signerManager) {
+        const key = await this.readPox("get-signer-info", [contractCV(signerManager)]);
+        return key !== null;
+    }
+    /** Walk pox-5's signer-set linked list for a reward cycle. */
+    async getSignerSet(cycle) {
+        const entries = [];
+        let next = (await this.readPox("get-signer-set-first-item-for-cycle", [
+            uintCV(cycle),
+        ]));
+        while (next !== null && entries.length < MAX_SIGNERS_WALKED) {
+            const signer = next;
+            const delegated = await this.readPox("get-amount-delegated-for-signer", [
+                principalCV(signer),
+                uintCV(cycle),
+            ]);
+            entries.push({ signerManager: signer, delegatedUstx: toBigInt(delegated) });
+            next = (await this.readPox("get-signer-set-next-item-for-cycle", [
+                principalCV(signer),
+                uintCV(cycle),
+            ]));
+        }
+        return entries;
+    }
+    async getClaimStyle(signerManager) {
+        const iface = await this.hiro.getContractInterface(signerManager);
+        const fn = iface.functions.find((f) => f.name === "claim-staker-rewards" && f.access === "public");
+        if (!fn)
+            return "none";
+        const names = fn.args.map((a) => a.name);
+        if (names.length === 3 && names[0] === "staker" && names[1] === "reward-cycle") {
+            return "staker-arg";
+        }
+        if (names.length === 2 && names[0] === "reward-cycle") {
+            return "caller";
+        }
+        return "none";
+    }
+    /** sBTC the staker has earned from this signer for a cycle and not yet claimed (before manager fees). */
+    async getStakerUnclaimedRewards(signerManager, rewardCycle, staker) {
+        return toBigInt(await this.readPox("get-earned-staker-rewards", [
+            principalCV(signerManager),
+            uintCV(rewardCycle),
+            noneCV(),
+            principalCV(staker),
+        ]));
+    }
+    /** sBTC pox-5 still holds for the signer manager for a cycle (not yet pulled by the manager). */
+    async getSignerUnpulledRewards(signerManager, rewardCycle) {
+        return toBigInt(await this.readPox("get-earned", [principalCV(signerManager), uintCV(rewardCycle), noneCV()]));
+    }
+    // --------------------------------------------------------------------------
+    // Writes
+    // --------------------------------------------------------------------------
+    assertNotPreparePhase(pox, action) {
+        if (pox.inPreparePhase) {
+            throw new Error(`pox-5 refuses ${action} during the prepare phase. Burn height ${pox.burnHeight} is inside ` +
+                `the prepare phase that started at ${pox.preparePhaseStartHeight}; try again at or after ` +
+                `burn height ${pox.nextCycleStartHeight} (reward cycle ${pox.rewardCycle + 1}).`);
+        }
+    }
+    async stake(account, options) {
+        const { signerManager, amountUstx, numCycles, signerCalldata } = options;
+        assertContractId(signerManager, "signerManager");
+        if (amountUstx <= 0n)
+            throw new Error("amount must be greater than zero");
+        if (!Number.isInteger(numCycles) || numCycles < 1 || numCycles > MAX_STAKE_CYCLES) {
+            throw new Error(`numCycles must be an integer between 1 and ${MAX_STAKE_CYCLES}`);
+        }
+        const status = await this.getStakingStatus(account.address);
+        const { pox } = status;
+        this.assertNotPreparePhase(pox, "stake");
+        if (status.staking) {
+            throw new Error(`${account.address} is already staking ${status.staking.amountUstx} uSTX with ` +
+                `${status.staking.signerManager}. Use extend_stacking to extend, increase or switch signer.`);
+        }
+        // pox-5 counts locked + unlocked STX (a bond rolling over into a stake is still locked).
+        if (status.account.balanceUstx < amountUstx) {
+            throw new Error(`Insufficient STX: ${status.account.balanceUstx} uSTX total, ${amountUstx} uSTX requested.`);
+        }
+        if (!(await this.isRegisteredSigner(signerManager))) {
+            throw new Error(`${signerManager} is not a registered pox-5 signer manager. Use list_stacking_signers to pick one.`);
+        }
+        const { address, name } = parseContractId(this.poxContract);
+        const result = await callContract(account, {
+            contractAddress: address,
+            contractName: name,
+            functionName: "stake",
+            functionArgs: [
+                contractCV(signerManager),
+                uintCV(amountUstx),
+                uintCV(numCycles),
+                // Any height in the current cycle makes the next cycle the first reward cycle.
+                uintCV(pox.burnHeight),
+                calldataCV(signerCalldata),
+            ],
+            postConditionMode: PostConditionMode.Deny,
+            postConditions: [Pc.principal(account.address).willSendEq(amountUstx).ustxToLock()],
         });
+        const unlockCycle = pox.rewardCycle + 1 + numCycles;
+        return {
+            ...result,
+            pox,
+            unlockCycle,
+            unlockBurnHeight: this.rewardCycleStartHeight(pox, unlockCycle),
+        };
     }
-    /**
-     * Extend stacking period
-     */
-    async extendStacking(account, extendCount, poxAddress) {
-        const { address: contractAddress, name: contractName } = parseContractId(this.contracts.POX_4);
-        const functionArgs = [
-            uintCV(extendCount),
-            tupleCV({
-                version: bufferCV(Buffer.from([poxAddress.version])),
-                hashbytes: bufferCV(Buffer.from(poxAddress.hashbytes, "hex")),
-            }),
-        ];
-        // No assets moved from sender (extends existing lock period)
-        return callContract(account, {
-            contractAddress,
-            contractName,
-            functionName: "stack-extend",
-            functionArgs,
-            postConditions: [],
+    async updateStake(account, options) {
+        const { cyclesToExtend, amountIncreaseUstx, signerCalldata } = options;
+        if (!Number.isInteger(cyclesToExtend) || cyclesToExtend < 0) {
+            throw new Error("cyclesToExtend must be a non-negative integer");
+        }
+        if (amountIncreaseUstx < 0n)
+            throw new Error("amountIncrease must not be negative");
+        const status = await this.getStakingStatus(account.address);
+        const { pox } = status;
+        const current = status.staking;
+        if (!current) {
+            throw new Error(`${account.address} is not staking. Use stack_stx to start.`);
+        }
+        this.assertNotPreparePhase(pox, "stake-update");
+        const signerManager = options.signerManager ?? current.signerManager;
+        assertContractId(signerManager, "signerManager");
+        if (cyclesToExtend === 0 &&
+            amountIncreaseUstx === 0n &&
+            signerManager === current.signerManager &&
+            !signerCalldata) {
+            throw new Error("Nothing to update: pass cyclesToExtend, amountIncrease, a new signerManager or payout calldata.");
+        }
+        const unlockCycle = current.unlockCycle + cyclesToExtend;
+        // pox-5 recomputes num-cycles from the next cycle to the unlock cycle.
+        const numCycles = unlockCycle - pox.rewardCycle - 1;
+        if (numCycles < 1 || numCycles > MAX_STAKE_CYCLES) {
+            throw new Error(`The lock would run ${numCycles} cycles from the next cycle; pox-5 allows 1 to ${MAX_STAKE_CYCLES}.`);
+        }
+        if (status.account.unlockedUstx < amountIncreaseUstx) {
+            throw new Error(`Insufficient unlocked STX: ${status.account.unlockedUstx} uSTX unlocked, ${amountIncreaseUstx} uSTX requested.`);
+        }
+        if (signerManager !== current.signerManager && !(await this.isRegisteredSigner(signerManager))) {
+            throw new Error(`${signerManager} is not a registered pox-5 signer manager. Use list_stacking_signers to pick one.`);
+        }
+        const newAmountUstx = current.amountUstx + amountIncreaseUstx;
+        const { address, name } = parseContractId(this.poxContract);
+        const result = await callContract(account, {
+            contractAddress: address,
+            contractName: name,
+            functionName: "stake-update",
+            functionArgs: [
+                contractCV(signerManager),
+                contractCV(current.signerManager),
+                uintCV(cyclesToExtend),
+                uintCV(amountIncreaseUstx),
+                calldataCV(signerCalldata),
+            ],
+            postConditionMode: PostConditionMode.Deny,
+            // The staking condition is on the resulting total lock, not the increment.
+            postConditions: [Pc.principal(account.address).willSendEq(newAmountUstx).ustxToLock()],
         });
+        return {
+            ...result,
+            previous: current,
+            newAmountUstx,
+            signerManager,
+            unlockCycle,
+            unlockBurnHeight: this.rewardCycleStartHeight(pox, unlockCycle),
+        };
     }
-    /**
-     * Increase stacking amount
-     */
-    async increaseStacking(account, increaseAmount) {
-        const { address: contractAddress, name: contractName } = parseContractId(this.contracts.POX_4);
-        const functionArgs = [uintCV(increaseAmount)];
-        // Add post condition: sender must lock exactly `increaseAmount` of additional STX
-        const postCondition = createStxPostCondition(account.address, "eq", increaseAmount);
-        return callContract(account, {
-            contractAddress,
-            contractName,
-            functionName: "stack-increase",
-            functionArgs,
-            postConditions: [postCondition],
+    async unstake(account) {
+        const status = await this.getStakingStatus(account.address);
+        const { pox } = status;
+        const current = status.staking;
+        if (!current) {
+            throw new Error(`${account.address} is not staking.`);
+        }
+        this.assertNotPreparePhase(pox, "unstake");
+        if (current.unlockCycle <= pox.rewardCycle + 1) {
+            throw new Error(`This stake already unlocks at the start of cycle ${current.unlockCycle} ` +
+                `(burn height ${current.unlockBurnHeight}); unstaking would not unlock it sooner.`);
+        }
+        const { address, name } = parseContractId(this.poxContract);
+        const result = await callContract(account, {
+            contractAddress: address,
+            contractName: name,
+            functionName: "unstake",
+            functionArgs: [contractCV(current.signerManager)],
+            postConditionMode: PostConditionMode.Deny,
+            postConditions: [Pc.origin().willPerformPox()],
         });
+        const unlockCycle = pox.rewardCycle + 1;
+        return {
+            ...result,
+            previous: current,
+            unlockCycle,
+            unlockBurnHeight: this.rewardCycleStartHeight(pox, unlockCycle),
+        };
     }
     /**
-     * Delegate STX to a stacking pool
+     * Have the signer manager pull its STX-staking rewards for a cycle out of pox-5.
+     * Permissionless on reference managers. An empty bond-period list claims the
+     * STX-staker bucket only, which is all an STX staker's payout draws on.
      */
-    async delegateStx(account, amount, delegateTo, untilBurnHeight, poxAddress) {
-        const { address: contractAddress, name: contractName } = parseContractId(this.contracts.POX_4);
-        const functionArgs = [
-            uintCV(amount),
-            { type: "principal", value: delegateTo },
-            untilBurnHeight ? someCV(uintCV(untilBurnHeight)) : noneCV(),
-            poxAddress
-                ? someCV(tupleCV({
-                    version: bufferCV(Buffer.from([poxAddress.version])),
-                    hashbytes: bufferCV(Buffer.from(poxAddress.hashbytes, "hex")),
-                }))
-                : noneCV(),
-        ];
-        // No assets moved from sender (delegation is permission, not transfer)
+    async pullSignerRewards(account, signerManager, rewardCycle, unpulledSats) {
+        const { address, name } = parseContractId(signerManager);
+        const sbtc = getContracts(this.network).SBTC_TOKEN;
         return callContract(account, {
-            contractAddress,
-            contractName,
-            functionName: "delegate-stx",
-            functionArgs,
-            postConditions: [],
+            contractAddress: address,
+            contractName: name,
+            functionName: "claim-rewards",
+            functionArgs: [
+                listCV([]),
+                uintCV(rewardCycle),
+            ],
+            postConditionMode: PostConditionMode.Deny,
+            // pox-5 pays the manager; more may have accrued by the time this mines.
+            postConditions: [Pc.principal(this.poxContract).willSendGte(unpulledSats).ft(sbtc, "sbtc-token")],
         });
     }
-    /**
-     * Revoke delegation
-     */
-    async revokeDelegation(account) {
-        const { address: contractAddress, name: contractName } = parseContractId(this.contracts.POX_4);
-        // No assets moved from sender (revokes delegation permission)
+    /** Pay this staker their share of a cycle's rewards through the signer manager. */
+    async claimStakerRewards(account, signerManager, rewardCycle, style) {
+        const { address, name } = parseContractId(signerManager);
+        const sbtc = getContracts(this.network).SBTC_TOKEN;
+        const args = style === "staker-arg"
+            ? [principalCV(account.address), uintCV(rewardCycle), noneCV()]
+            : [uintCV(rewardCycle), noneCV()];
         return callContract(account, {
-            contractAddress,
-            contractName,
-            functionName: "revoke-delegate-stx",
-            functionArgs: [],
-            postConditions: [],
+            contractAddress: address,
+            contractName: name,
+            functionName: "claim-staker-rewards",
+            functionArgs: args,
+            postConditionMode: PostConditionMode.Deny,
+            // The manager sends sBTC to the staker (or into an sBTC withdrawal to their
+            // BTC address). Fees and earlier settled balances make the exact amount
+            // manager-specific; nothing may leave the caller.
+            postConditions: [Pc.principal(signerManager).willSendGte(1).ft(sbtc, "sbtc-token")],
         });
     }
 }

package/dist/services/x402-discovery.service.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Live x402 endpoint discovery.
+ *
+ * x402.aibtc.com and stx402.com publish an OpenAPI spec, and stx402.com runs a
+ * directory of x402 endpoints registered by third parties. Reading those at call
+ * time keeps `list_x402_endpoints` in step with what the hosts actually serve,
+ * instead of a hand-maintained list that goes stale when routes move.
+ *
+ * Results are cached briefly. A failed fetch is never cached and never replaced
+ * with stale or invented entries: the source is reported as unavailable.
+ */
+import { type Network } from "../config/networks.js";
+import type { X402Endpoint } from "../endpoints/registry.js";
+export interface OpenApiSource {
+    /** Label shown to the agent. */
+    source: string;
+    /** Base URL per network; a network without one is not served by this host. */
+    baseUrl: Partial<Record<Network, string>>;
+}
+export declare const OPENAPI_SOURCES: OpenApiSource[];
+export declare const DISCOVERY_CACHE_TTL_MS: number;
+/** An endpoint registered in the stx402.com directory by its owner. */
+export interface DirectoryEntry {
+    name: string;
+    url: string;
+    category: string;
+    status: string;
+    owner: string;
+}
+export interface UnavailableSource {
+    source: string;
+    error: string;
+}
+/** Test seam. */
+export declare function clearDiscoveryCache(): void;
+interface OpenApiParameter {
+    name: string;
+    in: string;
+    description?: string;
+}
+interface OpenApiOperation {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        content?: Record<string, {
+            schema?: {
+                properties?: Record<string, {
+                    description?: string;
+                }>;
+                required?: string[];
+            };
+        }>;
+    };
+}
+interface OpenApiSpec {
+    paths?: Record<string, Record<string, OpenApiOperation>>;
+}
+/**
+ * Summaries on these hosts lead with the pricing tier, e.g. "(paid, standard) Decode a
+ * transaction" or "(free) List models". Split that into a cost label and a description.
+ * The exact price is only known from the 402 challenge, so it is not guessed here.
+ */
+export declare function parseSummary(summary: string): {
+    cost: string;
+    description: string;
+};
+/** Map an OpenAPI spec to endpoint entries. Admin-only operations are left out. */
+export declare function endpointsFromOpenApi(spec: OpenApiSpec, source: string): X402Endpoint[];
+/** Fetch one host's endpoints from its OpenAPI spec. */
+export declare function fetchOpenApiEndpoints(source: OpenApiSource, network?: Network): Promise<X402Endpoint[]>;
+/** Fetch every entry in the stx402.com endpoint directory (mainnet only). */
+export declare function fetchDirectoryEntries(): Promise<DirectoryEntry[]>;
+/** Fetch every OpenAPI source in parallel, reporting failures per source. */
+export declare function discoverOpenApiEndpoints(sources?: OpenApiSource[], network?: Network): Promise<{
+    endpoints: X402Endpoint[];
+    unavailable: UnavailableSource[];
+}>;
+export {};
+//# sourceMappingURL=x402-discovery.service.d.ts.map