@aibtc/mcp-server 1.70.0 → 1.71.0

package/dist/services/stacking.service.d.ts

@@ -1,58 +1,157 @@
-import { PoxInfo } from "./hiro-api.js";
+/**
+ * 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 { type Network } from "../config/index.js";
 import { type Account, type TransferResult } from "../transactions/builder.js";
-export interface StackingStatus {
-    stacked: boolean;
-    amountMicroStx: string;
-    amountStx: string;
+/** pox-5 `MAX_NUM_CYCLES`. */
+export declare const MAX_STAKE_CYCLES = 96;
+export interface PoxState {
+    contractId: string;
+    burnHeight: number;
+    rewardCycle: number;
+    firstBurnHeight: number;
+    rewardCycleLength: number;
+    prepareCycleLength: number;
+    /** Burn height where the next reward cycle begins. */
+    nextCycleStartHeight: number;
+    /** Burn height where this cycle's prepare phase begins. */
+    preparePhaseStartHeight: number;
+    inPreparePhase: boolean;
+    /** Minimum a signer needs delegated to join the signer set (not a per-staker minimum). */
+    signerSetMinUstx: bigint;
+    totalLiquidSupplyUstx: bigint;
+}
+export interface StakerInfo {
+    amountUstx: bigint;
     firstRewardCycle: number;
-    lockPeriod: number;
-    unlockHeight: number;
-    poxAddress?: string;
+    numCycles: number;
+    /** First cycle in which the STX is unlocked. */
+    unlockCycle: number;
+    unlockBurnHeight: number;
+    signerManager: string;
+}
+export interface BondMembership {
+    bondIndex: number;
+    amountUstx: bigint;
+    amountSats: bigint;
+    isL1Lock: boolean;
+    signerManager: string;
+}
+export interface StakingStatus {
+    address: string;
+    pox: PoxState;
+    staking: StakerInfo | null;
+    bond: BondMembership | null;
+    account: {
+        balanceUstx: bigint;
+        lockedUstx: bigint;
+        unlockedUstx: bigint;
+        burnchainUnlockHeight: number;
+    };
+}
+export interface SignerSetEntry {
+    signerManager: string;
+    delegatedUstx: bigint;
+}
+/**
+ * How a signer manager pays its stakers, read from its public interface.
+ * - `staker-arg`: `claim-staker-rewards(staker, reward-cycle, bond-index)`, callable by anyone
+ * - `caller`:     `claim-staker-rewards(reward-cycle, bond-index)`, pays the caller
+ * - `none`:       no on-chain staker claim (the manager pays off-chain, or not at all)
+ */
+export type ClaimStyle = "staker-arg" | "caller" | "none";
+export interface StakeOptions {
+    signerManager: string;
+    amountUstx: bigint;
+    numCycles: number;
+    signerCalldata?: Uint8Array;
 }
+export interface UpdateStakeOptions {
+    /** New signer manager; defaults to the current one. */
+    signerManager?: string;
+    cyclesToExtend: number;
+    amountIncreaseUstx: bigint;
+    signerCalldata?: Uint8Array;
+}
+/**
+ * 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 declare function buildPayoutCalldata(poxAddr: {
+    version: number;
+    hashbytesHex: string;
+}, maxFeeSats: bigint): Uint8Array;
 export declare class StackingService {
     private network;
     private hiro;
-    private contracts;
+    private poxContract;
     constructor(network: Network);
+    get contractId(): string;
+    private read;
+    private readPox;
+    getPoxState(): Promise<PoxState>;
+    private rewardCycleStartHeight;
+    getStakerInfo(address: string, pox?: PoxState): Promise<StakerInfo | null>;
+    getBondMembership(address: string): Promise<BondMembership | null>;
+    getStakingStatus(address: string): Promise<StakingStatus>;
+    /** Whether pox-5 has a signer key registered for this manager. */
+    isRegisteredSigner(signerManager: string): Promise<boolean>;
+    /** Walk pox-5's signer-set linked list for a reward cycle. */
+    getSignerSet(cycle: number): Promise<SignerSetEntry[]>;
+    getClaimStyle(signerManager: string): Promise<ClaimStyle>;
+    /** sBTC the staker has earned from this signer for a cycle and not yet claimed (before manager fees). */
+    getStakerUnclaimedRewards(signerManager: string, rewardCycle: number, staker: string): Promise<bigint>;
+    /** sBTC pox-5 still holds for the signer manager for a cycle (not yet pulled by the manager). */
+    getSignerUnpulledRewards(signerManager: string, rewardCycle: number): Promise<bigint>;
+    private assertNotPreparePhase;
+    stake(account: Account, options: StakeOptions): Promise<TransferResult & {
+        pox: PoxState;
+        unlockCycle: number;
+        unlockBurnHeight: number;
+    }>;
+    updateStake(account: Account, options: UpdateStakeOptions): Promise<TransferResult & {
+        previous: StakerInfo;
+        newAmountUstx: bigint;
+        signerManager: string;
+        unlockCycle: number;
+        unlockBurnHeight: number;
+    }>;
+    unstake(account: Account): Promise<TransferResult & {
+        previous: StakerInfo;
+        unlockCycle: number;
+        unlockBurnHeight: number;
+    }>;
     /**
-     * Get current PoX (Proof of Transfer) info
-     */
-    getPoxInfo(): Promise<PoxInfo>;
-    /**
-     * Get stacking status for an address
-     * Note: Returns whether the address is stacking, but detailed amounts require proper CV parsing
-     */
-    getStackingStatus(address: string): Promise<StackingStatus>;
-    /**
-     * Stack STX tokens
-     */
-    stack(account: Account, amount: bigint, poxAddress: {
-        version: number;
-        hashbytes: string;
-    }, startBurnHeight: number, lockPeriod: number): Promise<TransferResult>;
-    /**
-     * Extend stacking period
-     */
-    extendStacking(account: Account, extendCount: number, poxAddress: {
-        version: number;
-        hashbytes: string;
-    }): Promise<TransferResult>;
-    /**
-     * Increase stacking amount
-     */
-    increaseStacking(account: Account, increaseAmount: bigint): Promise<TransferResult>;
-    /**
-     * Delegate STX to a stacking pool
-     */
-    delegateStx(account: Account, amount: bigint, delegateTo: string, untilBurnHeight?: number, poxAddress?: {
-        version: number;
-        hashbytes: string;
-    }): Promise<TransferResult>;
-    /**
-     * Revoke delegation
+     * 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.
      */
-    revokeDelegation(account: Account): Promise<TransferResult>;
+    pullSignerRewards(account: Account, signerManager: string, rewardCycle: number, unpulledSats: bigint): Promise<TransferResult>;
+    /** Pay this staker their share of a cycle's rewards through the signer manager. */
+    claimStakerRewards(account: Account, signerManager: string, rewardCycle: number, style: Exclude<ClaimStyle, "none">): Promise<TransferResult>;
 }
 export declare function getStackingService(network: Network): StackingService;
 //# sourceMappingURL=stacking.service.d.ts.map