@secondlayer/stacks 2.16.0 → 2.18.0

package/dist/src/pox5/index.d.ts

@@ -217,6 +217,20 @@ declare function assertPox5Active(client: Client): Promise<void>;
 */
 /** Boot contract name; deployer is the chain's boot address. */
 declare const POX5_CONTRACT_NAME = "pox-5";
+/** Fully-qualified mainnet contract id (boot address + `pox-5`). */
+declare const POX5_CONTRACT_ID_MAINNET: string;
+/**
+* All print-event topic strings emitted by `pox-5.clar`. Unlike pox-2/3/4,
+* pox-5 has NO node-synthesized events — every event is a real `(print ...)`
+* with these `topic` values and the remaining tuple fields flattened at the
+* top level via `merge` (not nested under a `data` key).
+*
+* `add-to-allowlist` and `bond-distribution` are emitted per-item inside
+* folds (`setup-bond` / `calculate-rewards`), so one transaction can carry
+* many prints.
+*/
+declare const POX5_EVENT_TOPICS: readonly ["set-bond-admin", "set-pause-admin", "pause-rewards", "setup-bond", "add-to-allowlist", "register-for-bond", "update-bond-registration", "register-signer", "stake", "stake-update", "announce-l1-early-exit", "unstake-sbtc", "unstake", "calculate-rewards", "bond-distribution", "claim-rewards", "claim-staker-rewards-for-signer", "grant-signer-key", "revoke-signer-grant"];
+type Pox5EventTopic = (typeof POX5_EVENT_TOPICS)[number];
 /**
 * Epoch 4.0 hard-fork activation height on mainnet — Bitcoin block 960,230
 * (expected ~2026-07-29 03:00 UTC, per the stacks-core 4.0.0 release).
@@ -407,6 +421,15 @@ declare function verifySignerGrant(opts: SignerGrantOptions & {
 	publicKey: Uint8Array | string
 	signature: Uint8Array | string
 }): boolean;
+type IntegerType = number | string | bigint | Uint8Array;
+/**
+* Named fee tiers. `'low' | 'mid' | 'high'` map to the node's three fee
+* estimations; `'min'` is the node's minimum relay fee — 1 uSTX per byte of
+* the serialized transaction, computable offline.
+*/
+type FeeTier = "min" | "low" | "mid" | "high";
+/** Fee input accepted by wallet actions: an explicit amount or a named tier. */
+type FeeParam = IntegerType | FeeTier;
 type FungibleComparator = "eq" | "gt" | "gte" | "lt" | "lte";
 type NonFungibleComparator = "sent" | "not-sent";
 type StxPostCondition = {
@@ -442,24 +465,37 @@ type PoxPostCondition = {
 	condition: PoxComparator
 };
 type PostCondition = StxPostCondition | FtPostCondition | NftPostCondition | StakingPostCondition | PoxPostCondition;
-type IntegerType = number | string | bigint | Uint8Array;
 /**
-* Named fee tiers. `'low' | 'mid' | 'high'` map to the node's three fee
-* estimations; `'min'` is the node's minimum relay fee — 1 uSTX per byte of
-* the serialized transaction, computable offline.
+* Mapped read-return types for the pox-5 contract — the JS shapes
+* `getContract` produces from the ABI (camelCase keys, `uint` → `bigint`,
+* `buff` → `Uint8Array`, `none` → `null`, response ok auto-unwrapped).
 */
-type FeeTier = "min" | "low" | "mid" | "high";
-/** Fee input accepted by wallet actions: an explicit amount or a named tier. */
-type FeeParam = IntegerType | FeeTier;
-type CallContractParams = {
-	contract: string
-	functionName: string
-	functionArgs?: ClarityValue[]
-	fee?: FeeParam
-	nonce?: IntegerType
-	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
-};
+/** Staker info from `get-staker-info`; `null` when expired/absent. */
+type StakerInfo = {
+	amountUstx: bigint
+	firstRewardCycle: bigint
+	numCycles: bigint
+	signer: string
+} | null;
+/** Bond membership from `get-bond-membership`; `null` when not in a bond. */
+type BondMembership = {
+	amountSats: bigint
+	amountUstx: bigint
+	bondIndex: bigint
+	isL1Lock: boolean
+	signer: string
+} | null;
+/** Bond parameters from `get-protocol-bond`; `null` for an unknown bond. */
+type ProtocolBond = {
+	earlyUnlockBytes: Uint8Array
+	minUstxRatio: bigint
+	stxValueRatio: bigint
+	targetRate: bigint
+} | null;
+/** Allowlisted max sats from `get-bond-allowance`; `null` when not allowlisted. */
+type BondAllowance = bigint | null;
+/** Signer key from `get-signer-info`; `null` for an unknown signer. */
+type SignerInfo = Uint8Array | null;
 /**
 * PoX-5 contract calls and reads, pinned against the final contract in
 * stacks-core 4.0.0. Wallet actions route through `callContract`, so they
@@ -473,7 +509,12 @@ type CallContractParams = {
 */
 /** Resolve the boot `pox-5` contract id for the client's chain. */
 declare function pox5ContractId(client: Client): string;
-type TxOptions = Pick<CallContractParams, "fee" | "nonce" | "postConditions" | "postConditionMode">;
+type TxOptions = {
+	fee?: FeeParam
+	nonce?: IntegerType
+	postConditions?: PostCondition[]
+	postConditionMode?: "allow" | "deny"
+};
 /**
 * One proven L1 timelock output — a Bitcoin SPV inclusion proof of the lockup
 * tx plus which output is the lockup. `@secondlayer/stacks/bitcoin`'s
@@ -597,18 +638,18 @@ type Pox5Actions = {
 		getActivation: () => Promise<Pox5Activation | undefined>
 		contractId: () => string
 		getStakerState: (staker: string) => Promise<StakerState>
-		getStakerInfo: (staker: string) => Promise<ClarityValue>
-		getBondMembership: (staker: string) => Promise<ClarityValue>
-		getProtocolBond: (bondIndex: IntegerType) => Promise<ClarityValue>
-		getBondAllowance: (bondIndex: IntegerType, staker: string) => Promise<ClarityValue>
-		getTotalSbtcStakedForBond: (bondIndex: IntegerType) => Promise<ClarityValue>
-		getStakerCustodiedSbtc: (staker: string) => Promise<ClarityValue>
-		hasAnnouncedL1EarlyExit: (bondIndex: IntegerType, staker: string) => Promise<ClarityValue>
-		getBondL1UnlockHeight: (bondIndex: IntegerType) => Promise<ClarityValue>
-		getSignerInfo: (signer: string) => Promise<ClarityValue>
-		verifySignerKeyGrant: (signerManager: string, signerKey: Uint8Array | string) => Promise<ClarityValue>
-		getCurrentRewardCycle: () => Promise<ClarityValue>
-		getFirstRewardCycle: () => Promise<ClarityValue>
+		getStakerInfo: (staker: string) => Promise<StakerInfo>
+		getBondMembership: (staker: string) => Promise<BondMembership>
+		getProtocolBond: (bondIndex: IntegerType) => Promise<ProtocolBond>
+		getBondAllowance: (bondIndex: IntegerType, staker: string) => Promise<BondAllowance>
+		getTotalSbtcStakedForBond: (bondIndex: IntegerType) => Promise<bigint>
+		getStakerCustodiedSbtc: (staker: string) => Promise<bigint>
+		hasAnnouncedL1EarlyExit: (bondIndex: IntegerType, staker: string) => Promise<boolean>
+		getBondL1UnlockHeight: (bondIndex: IntegerType) => Promise<bigint>
+		getSignerInfo: (signer: string) => Promise<SignerInfo>
+		verifySignerKeyGrant: (signerManager: string, signerKey: Uint8Array | string) => Promise<boolean>
+		getCurrentRewardCycle: () => Promise<bigint>
+		getFirstRewardCycle: () => Promise<bigint>
 		setupBond: (params: SetupBondParams) => Promise<string>
 		registerForBond: (params: RegisterForBondParams) => Promise<string>
 		updateBondRegistration: (params: UpdateBondRegistrationParams) => Promise<string>
@@ -643,4 +684,4 @@ type Pox5Actions = {
 * }
 */
 declare function pox5(): (client: Client) => Pox5Actions;
-export { verifySignerGrant, stakerPreimage, stakerConsensusBuff, signSignerGrant, serializeCScriptNum, rewardCycleToBurnHeight, pushScriptBytes, pushCScriptNum, pox5ContractId, pox5, isPox5Active, isInPreparePhase, getPox5Activation, computeSignerGrantHash, burnHeightToRewardCycle, burnHeightToDistributionIndex, buildLockupScript, buildLockupOutputScript, buildLockupAddress, buildDefaultStakerUnlockBytes, bondUnlockCycle, bondPhaseAtHeight, bondPeriodToRewardCycle, bondPeriodToBurnHeight, assertPox5Active, UpdateBondRegistrationParams, UnstakeSbtcParams, UnstakeParams, StakerState, StakeUpdateParams, StakeParams, SignerGrantOptions, SetupBondParams, RevokeSignerGrantParams, RegisterForBondParams, PoxCycleParams, Pox5Activation, Pox5Actions, POX5_SIGNER_DOMAIN, POX5_CONTRACT_NAME, POX5_ACTIVATION_BURN_HEIGHT_MAINNET, MAX_NUM_CYCLES, L1LockupOutput, GrantSignerKeyParams, ClaimStakerRewardsForSignerParams, ClaimRewardsParams, CalculateRewardsParams, C_SCRIPT_NUM_MAX, BuildLockupScriptOptions, BtcLockup, BondPhase, BondCycleParams, BOND_LENGTH_CYCLES, BOND_GAP_CYCLES, BITCOIN_LOCKTIME_THRESHOLD, AnnounceL1EarlyExitParams };
+export { verifySignerGrant, stakerPreimage, stakerConsensusBuff, signSignerGrant, serializeCScriptNum, rewardCycleToBurnHeight, pushScriptBytes, pushCScriptNum, pox5ContractId, pox5, isPox5Active, isInPreparePhase, getPox5Activation, computeSignerGrantHash, burnHeightToRewardCycle, burnHeightToDistributionIndex, buildLockupScript, buildLockupOutputScript, buildLockupAddress, buildDefaultStakerUnlockBytes, bondUnlockCycle, bondPhaseAtHeight, bondPeriodToRewardCycle, bondPeriodToBurnHeight, assertPox5Active, UpdateBondRegistrationParams, UnstakeSbtcParams, UnstakeParams, StakerState, StakeUpdateParams, StakeParams, SignerGrantOptions, SetupBondParams, RevokeSignerGrantParams, RegisterForBondParams, PoxCycleParams, Pox5EventTopic, Pox5Activation, Pox5Actions, POX5_SIGNER_DOMAIN, POX5_EVENT_TOPICS, POX5_CONTRACT_NAME, POX5_CONTRACT_ID_MAINNET, POX5_ACTIVATION_BURN_HEIGHT_MAINNET, MAX_NUM_CYCLES, L1LockupOutput, GrantSignerKeyParams, ClaimStakerRewardsForSignerParams, ClaimRewardsParams, CalculateRewardsParams, C_SCRIPT_NUM_MAX, BuildLockupScriptOptions, BtcLockup, BondPhase, BondCycleParams, BOND_LENGTH_CYCLES, BOND_GAP_CYCLES, BITCOIN_LOCKTIME_THRESHOLD, AnnounceL1EarlyExitParams };