@stacks/codec 1.8.0-pox5.1 → 2.0.0-pox5.1

package/README.md

@@ -236,7 +236,7 @@ import { decodeClarityValueToPrincipal } from '@stacks/codec';
 
 // Serialized hex string of an example Clarity value (0x-prefix optional, Buffer / Uint8Array also accepted)
 const standardPrincipal = decodeClarityValueToPrincipal('0x0516a13dce8114be0f707f94470a2e5e86eb402f2923');
-assert.strictEqual(principal, 'SP2GKVKM12JZ0YW3ZJH3GMBJYGVNM0BS94ERA45AM');
+assert.strictEqual(standardPrincipal, 'SP2GKVKM12JZ0YW3ZJH3GMBJYGVNM0BS94ERA45AM');
 
 const contractPrincipal = decodeClarityValueToPrincipal('0x0616a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c616273');
 assert.strictEqual(contractPrincipal, 'SP2KAF9RF86PVX3NEE27DFV1CQX0T4WGR41X3S45C.bitcoin-monkeys-labs');
@@ -415,17 +415,22 @@ The directory structure of this project is:
 /
 ├── Cargo.toml    # The Cargo <a href="https://doc.rust-lang.org/cargo/reference/manifest.html">manifest file</a>
 ├── package.json  # The npm <a href="https://docs.npmjs.com/cli/v7/configuring-npm/package-json">manifest file</a>
-├── native/       # The <a href="https://nodejs.org/api/addons.html">Node addon</a> modules built by this project, these are <a href="https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries">dynamically-linked shared objects</a>
-├── src/**/*.rs   # Directory containing the Rust source code for the project
-|── index.ts      # Typescript definitions for the js interface exposed by the Node addon
-|── loader.js     # Script to determine which addon file to load based on the executing target platform
-|── loader.d.ts   # Type defintions for the functions exported by the Node addon
-|── builder.js    # Script to build the native Node addon for the executing host platform
-├── tests/*.ts    # Js/ts unit tests, primarily testing the Neon (rust<->nodejs) interop layer
-└── perf-tests/   # Scripts to run performance benchmarks used by commands in package.json
+├── build.js      # Script to build the native Node addon for the executing host platform
+├── index.ts      # Typescript definitions for the JS interface exposed by the Node addon
+├── loader.js     # Script to determine which addon file to load based on the executing target platform
+├── loader.d.ts   # Type definitions for the functions exported by the Node addon
+├── native/       # The <a href="https://nodejs.org/api/addons.html">Node addon</a> binaries built by this project (one per supported target)
+├── src/          # Rust source code
+│   ├── upstream/   # Thin layer over stacks-network/stacks-core types (address, clarity_value, post_condition, stacks_block, stacks_tx)
+│   ├── derived/    # Local decoders that produce Stacks-API-shaped output (memo, pox_events)
+│   ├── util/       # Crate-internal helpers (hex, neon bindings, DeserializeError)
+│   └── lib.rs      # Neon entry point — exports the JS-facing functions
+├── tests/        # Jest end-to-end tests + fixtures
+├── scripts/      # update-stacks-core.sh — bump the upstream git pin
+└── docs/         # Migration / upgrade documentation
 </pre>
 
-The Rust source code inside the `src/**/deserialize.rs` files are responsible for deserializing the Stacks blockchain wire/binary formats defined in [SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md). 
+All consensus wire-format parsing is delegated to upstream `stacks-network/stacks-core` crates (`stackslib`, `clarity`, `stacks-common`, `stacks-codec`) — see [`docs/upstream-migration.md`](docs/upstream-migration.md) for the rationale and pin-bump workflow.
 
 ## NPM Library Bundling
 

package/index.d.ts

@@ -524,7 +524,7 @@ export interface StacksWorkScore {
     /** String-quoted unsigned integer - work score */
     work: string;
 }
-export declare enum PoxEventName {
+export declare enum Pox4EventName {
     HandleUnlock = "handle-unlock",
     StackStx = "stack-stx",
     StackIncrease = "stack-increase",
@@ -538,7 +538,13 @@ export declare enum PoxEventName {
     StackAggregationIncrease = "stack-aggregation-increase",
     RevokeDelegateStx = "revoke-delegate-stx"
 }
-export interface PoxEventBase {
+export interface Pox4EventBase {
+    /**
+     * Discriminant identifying the source PoX contract version. For events
+     * decoded from pox-2 / pox-3 / pox-4 this is always `'pox4'` — pox-5
+     * events come back as {@link Pox5Event} instead.
+     */
+    pox_version: 'pox4';
     stacker: string;
     /** String-quoted unsigned integer */
     locked: string;
@@ -549,8 +555,8 @@ export interface PoxEventBase {
     pox_addr: string | null;
     pox_addr_raw: string | null;
 }
-export interface PoxEventHandleUnlock extends PoxEventBase {
-    name: PoxEventName.HandleUnlock;
+export interface Pox4EventHandleUnlock extends Pox4EventBase {
+    name: Pox4EventName.HandleUnlock;
     data: {
         /** String-quoted unsigned integer */
         first_cycle_locked: string;
@@ -558,8 +564,8 @@ export interface PoxEventHandleUnlock extends PoxEventBase {
         first_unlocked_cycle: string;
     };
 }
-export interface PoxEventStackStx extends PoxEventBase {
-    name: PoxEventName.StackStx;
+export interface Pox4EventStackStx extends Pox4EventBase {
+    name: Pox4EventName.StackStx;
     data: {
         /** String-quoted unsigned integer */
         lock_amount: string;
@@ -577,8 +583,8 @@ export interface PoxEventStackStx extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventStackIncrease extends PoxEventBase {
-    name: PoxEventName.StackIncrease;
+export interface Pox4EventStackIncrease extends Pox4EventBase {
+    name: Pox4EventName.StackIncrease;
     data: {
         /** String-quoted unsigned integer */
         increase_by: string;
@@ -592,8 +598,8 @@ export interface PoxEventStackIncrease extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventStackExtend extends PoxEventBase {
-    name: PoxEventName.StackExtend;
+export interface Pox4EventStackExtend extends Pox4EventBase {
+    name: Pox4EventName.StackExtend;
     data: {
         /** String-quoted unsigned integer */
         extend_count: string;
@@ -607,8 +613,8 @@ export interface PoxEventStackExtend extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventDelegateStx extends PoxEventBase {
-    name: PoxEventName.DelegateStx;
+export interface Pox4EventDelegateStx extends Pox4EventBase {
+    name: Pox4EventName.DelegateStx;
     data: {
         /** String-quoted unsigned integer */
         amount_ustx: string;
@@ -621,8 +627,8 @@ export interface PoxEventDelegateStx extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventDelegateStackStx extends PoxEventBase {
-    name: PoxEventName.DelegateStackStx;
+export interface Pox4EventDelegateStackStx extends Pox4EventBase {
+    name: Pox4EventName.DelegateStackStx;
     data: {
         /** String-quoted unsigned integer */
         lock_amount: string;
@@ -639,8 +645,8 @@ export interface PoxEventDelegateStackStx extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventDelegateStackIncrease extends PoxEventBase {
-    name: PoxEventName.DelegateStackIncrease;
+export interface Pox4EventDelegateStackIncrease extends Pox4EventBase {
+    name: Pox4EventName.DelegateStackIncrease;
     data: {
         /** String-quoted unsigned integer */
         increase_by: string;
@@ -653,8 +659,8 @@ export interface PoxEventDelegateStackIncrease extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventDelegateStackExtend extends PoxEventBase {
-    name: PoxEventName.DelegateStackExtend;
+export interface Pox4EventDelegateStackExtend extends Pox4EventBase {
+    name: Pox4EventName.DelegateStackExtend;
     data: {
         /** String-quoted unsigned integer */
         unlock_burn_height: string;
@@ -667,8 +673,8 @@ export interface PoxEventDelegateStackExtend extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventStackAggregationCommit extends PoxEventBase {
-    name: PoxEventName.StackAggregationCommit;
+export interface Pox4EventStackAggregationCommit extends Pox4EventBase {
+    name: Pox4EventName.StackAggregationCommit;
     data: {
         /** String-quoted unsigned integer */
         reward_cycle: string;
@@ -682,8 +688,8 @@ export interface PoxEventStackAggregationCommit extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventStackAggregationCommitIndexed extends PoxEventBase {
-    name: PoxEventName.StackAggregationCommitIndexed;
+export interface Pox4EventStackAggregationCommitIndexed extends Pox4EventBase {
+    name: Pox4EventName.StackAggregationCommitIndexed;
     data: {
         /** String-quoted unsigned integer */
         reward_cycle: string;
@@ -697,8 +703,8 @@ export interface PoxEventStackAggregationCommitIndexed extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventStackAggregationIncrease extends PoxEventBase {
-    name: PoxEventName.StackAggregationIncrease;
+export interface Pox4EventStackAggregationIncrease extends Pox4EventBase {
+    name: Pox4EventName.StackAggregationIncrease;
     data: {
         /** String-quoted unsigned integer */
         reward_cycle: string;
@@ -710,8 +716,8 @@ export interface PoxEventStackAggregationIncrease extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export interface PoxEventRevokeDelegateStx extends PoxEventBase {
-    name: PoxEventName.RevokeDelegateStx;
+export interface Pox4EventRevokeDelegateStx extends Pox4EventBase {
+    name: Pox4EventName.RevokeDelegateStx;
     data: {
         delegate_to: string;
         /** String-quoted unsigned integer or null */
@@ -720,4 +726,303 @@ export interface PoxEventRevokeDelegateStx extends PoxEventBase {
         start_cycle_id: string | null;
     };
 }
-export type DecodedPoxSyntheticEvent = PoxEventHandleUnlock | PoxEventStackStx | PoxEventStackIncrease | PoxEventStackExtend | PoxEventDelegateStx | PoxEventDelegateStackStx | PoxEventDelegateStackIncrease | PoxEventDelegateStackExtend | PoxEventStackAggregationCommit | PoxEventStackAggregationCommitIndexed | PoxEventStackAggregationIncrease | PoxEventRevokeDelegateStx;
+export type Pox4Event = Pox4EventHandleUnlock | Pox4EventStackStx | Pox4EventStackIncrease | Pox4EventStackExtend | Pox4EventDelegateStx | Pox4EventDelegateStackStx | Pox4EventDelegateStackIncrease | Pox4EventDelegateStackExtend | Pox4EventStackAggregationCommit | Pox4EventStackAggregationCommitIndexed | Pox4EventStackAggregationIncrease | Pox4EventRevokeDelegateStx;
+export declare enum Pox5EventName {
+    SetupBond = "setup-bond",
+    AddToAllowlist = "add-to-allowlist",
+    RegisterForBond = "register-for-bond",
+    UpdateBondRegistration = "update-bond-registration",
+    RegisterSigner = "register-signer",
+    Stake = "stake",
+    StakeUpdate = "stake-update",
+    AnnounceL1EarlyExit = "announce-l1-early-exit",
+    UnstakeSbtc = "unstake-sbtc",
+    Unstake = "unstake",
+    CalculateRewards = "calculate-rewards",
+    BondDistribution = "bond-distribution",
+    ClaimRewards = "claim-rewards"
+}
+export interface Pox5EventBase {
+    /**
+     * Discriminant identifying the source PoX contract version. For events
+     * decoded from pox-5 this is always `'pox5'` — earlier-contract events
+     * come back as {@link Pox4Event} instead.
+     */
+    pox_version: 'pox5';
+}
+export interface Pox5EventSetupBond extends Pox5EventBase {
+    name: Pox5EventName.SetupBond;
+    data: {
+        /** String-quoted unsigned integer */
+        bond_index: string;
+        /** String-quoted unsigned integer (basis points) */
+        target_rate: string;
+        /** String-quoted unsigned integer */
+        stx_value_ratio: string;
+        /** String-quoted unsigned integer */
+        min_ustx_ratio: string;
+        /**
+         * `(buff 683)` hex string. Opaque early-unlock authorization script
+         * (e.g. `<pubkey> OP_CHECKSIGVERIFY`, or an M-of-N multisig template).
+         */
+        early_unlock_bytes: string;
+        /** c32 principal allowed to call `announce-l1-early-exit` for stakers in this bond. */
+        early_unlock_admin: string;
+        /** String-quoted unsigned integer */
+        first_reward_cycle: string;
+        /** String-quoted unsigned integer */
+        bond_start_height: string;
+        /** String-quoted unsigned integer */
+        unlock_cycle: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+    };
+}
+export interface Pox5EventAddToAllowlist extends Pox5EventBase {
+    name: Pox5EventName.AddToAllowlist;
+    data: {
+        /** c32 principal of the staker being added to a bond's allowlist. */
+        staker: string;
+        /** String-quoted unsigned integer */
+        max_sats: string;
+        /** String-quoted unsigned integer */
+        bond_index: string;
+    };
+}
+export interface Pox5EventRegisterForBond extends Pox5EventBase {
+    name: Pox5EventName.RegisterForBond;
+    data: {
+        /** c32 principal */
+        signer: string;
+        /** c32 principal */
+        staker: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** String-quoted unsigned integer */
+        sats_total: string;
+        /** String-quoted unsigned integer */
+        bond_index: string;
+        /** String-quoted unsigned integer */
+        first_reward_cycle: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** String-quoted unsigned integer */
+        unlock_cycle: string;
+        /** True if the participant proved an L1 BTC lockup; false if they locked sBTC. */
+        is_l1_lock: boolean;
+    };
+}
+export interface Pox5EventUpdateBondRegistration extends Pox5EventBase {
+    name: Pox5EventName.UpdateBondRegistration;
+    data: {
+        /** c32 principal */
+        staker: string;
+        /** c32 principal of the new signer */
+        signer: string;
+        /** c32 principal of the previous signer */
+        old_signer: string;
+        /** String-quoted unsigned integer */
+        bond_index: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** String-quoted unsigned integer */
+        amount_sats: string;
+        /** String-quoted unsigned integer */
+        first_reward_cycle: string;
+        /** String-quoted unsigned integer */
+        num_cycles: string;
+        /** True if the participant's stake is an L1 BTC lockup. */
+        is_l1_lock: boolean;
+    };
+}
+export interface Pox5EventRegisterSigner extends Pox5EventBase {
+    name: Pox5EventName.RegisterSigner;
+    data: {
+        /** c32 principal */
+        signer: string;
+        /** `(buff 33)` hex string — compressed secp256k1 public key. */
+        signer_key: string;
+    };
+}
+export interface Pox5EventStake extends Pox5EventBase {
+    name: Pox5EventName.Stake;
+    data: {
+        /** c32 principal */
+        signer: string;
+        /** c32 principal */
+        staker: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** String-quoted unsigned integer */
+        num_cycles: string;
+        /** String-quoted unsigned integer */
+        first_reward_cycle: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** String-quoted unsigned integer */
+        unlock_cycle: string;
+    };
+}
+export interface Pox5EventStakeUpdate extends Pox5EventBase {
+    name: Pox5EventName.StakeUpdate;
+    data: {
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** c32 principal */
+        staker: string;
+        /** c32 principal of the new signer */
+        signer: string;
+        /** c32 principal of the previous signer */
+        old_signer: string;
+        /** String-quoted unsigned integer (the previous unlock cycle before extension) */
+        prev_unlock_height: string;
+        /** String-quoted unsigned integer */
+        unlock_cycle: string;
+        /** String-quoted unsigned integer */
+        num_cycles: string;
+        /** String-quoted unsigned integer — total locked amount after this update */
+        amount_ustx: string;
+        /** String-quoted unsigned integer */
+        amount_increase: string;
+        /** String-quoted unsigned integer */
+        cycles_to_extend: string;
+    };
+}
+export interface Pox5EventAnnounceL1EarlyExit extends Pox5EventBase {
+    name: Pox5EventName.AnnounceL1EarlyExit;
+    data: {
+        /** c32 principal */
+        staker: string;
+        /** c32 principal */
+        signer: string;
+        /** String-quoted unsigned integer */
+        bond_index: string;
+        /** String-quoted unsigned integer */
+        amount_sats_released: string;
+    };
+}
+export interface Pox5EventUnstakeSbtc extends Pox5EventBase {
+    name: Pox5EventName.UnstakeSbtc;
+    data: {
+        /** c32 principal */
+        staker: string;
+        /** c32 principal */
+        signer: string;
+        /** String-quoted unsigned integer */
+        bond_index: string;
+        /** String-quoted unsigned integer */
+        amount_withdrawn_sats: string;
+        /** String-quoted unsigned integer — sBTC shares remaining after withdrawal */
+        new_amount_sats: string;
+    };
+}
+export interface Pox5EventUnstake extends Pox5EventBase {
+    name: Pox5EventName.Unstake;
+    data: {
+        /** c32 principal */
+        staker: string;
+        /** c32 principal */
+        signer: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** String-quoted unsigned integer */
+        first_reward_cycle: string;
+        /** String-quoted unsigned integer */
+        unlock_cycle: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+    };
+}
+/**
+ * Logged by `calculate-rewards`. The contract emits this topic **twice** per
+ * call: a phase-1 (pre-distribution) print carrying `stranded_staker_cut`,
+ * and a phase-2 (post-distribution) print carrying `new_reserve`. Exactly
+ * one of those two fields is populated per event; the other is `null`.
+ *
+ * Phase-1 fires before reserve and accounting state are updated; useful for
+ * inspecting whether the staker cut was folded into the reserve because no
+ * STX was staked.
+ *
+ * Phase-2 fires after state is committed and matches the value returned to
+ * the caller.
+ */
+export interface Pox5EventCalculateRewards extends Pox5EventBase {
+    name: Pox5EventName.CalculateRewards;
+    data: {
+        /** Array of string-quoted unsigned integers (bond indices being settled) */
+        bond_periods: string[];
+        /** String-quoted unsigned integer */
+        calculation_height: string;
+        /** String-quoted unsigned integer */
+        remaining_rewards: string;
+        /** String-quoted unsigned integer */
+        accrued_rewards: string;
+        /**
+         * Phase-2 only. String-quoted unsigned integer — portion of accrued
+         * rewards retained in the reserve. `null` on the phase-1 event.
+         */
+        new_reserve: string | null;
+        /**
+         * Phase-1 only. String-quoted unsigned integer — the would-be STX
+         * staker cut that gets folded into the reserve when no STX is staked
+         * for the cycle. `null` on the phase-2 event.
+         */
+        stranded_staker_cut: string | null;
+        /** String-quoted unsigned integer */
+        stx_staker_rewards: string;
+        /** String-quoted unsigned integer */
+        stx_cycle: string;
+        /** String-quoted unsigned integer */
+        cycle_staked_ustx: string;
+        /** String-quoted unsigned integer */
+        next_rewards_per_ustx: string;
+    };
+}
+export interface Pox5EventBondDistribution extends Pox5EventBase {
+    name: Pox5EventName.BondDistribution;
+    data: {
+        /** String-quoted unsigned integer */
+        bond_index: string;
+        /** String-quoted unsigned integer */
+        target_yield: string;
+        /** String-quoted unsigned integer */
+        earned: string;
+    };
+}
+/** Sub-tuple emitted under `stx_rewards` in `claim-rewards` events. */
+export interface Pox5ClaimRewardsInfo {
+    /** String-quoted unsigned integer */
+    earned: string;
+    /** String-quoted unsigned integer */
+    rewards_per_token: string;
+}
+/** One entry in the `bond_rewards` list of a `claim-rewards` event. */
+export interface Pox5BondRewardsInfo extends Pox5ClaimRewardsInfo {
+    /** String-quoted unsigned integer */
+    bond_index: string;
+}
+export interface Pox5EventClaimRewards extends Pox5EventBase {
+    name: Pox5EventName.ClaimRewards;
+    data: {
+        stx_rewards: Pox5ClaimRewardsInfo;
+        bond_rewards: Pox5BondRewardsInfo[];
+        /** String-quoted unsigned integer */
+        bond_totals: string;
+        /** String-quoted unsigned integer */
+        total_rewards: string;
+    };
+}
+export type Pox5Event = Pox5EventSetupBond | Pox5EventAddToAllowlist | Pox5EventRegisterForBond | Pox5EventUpdateBondRegistration | Pox5EventRegisterSigner | Pox5EventStake | Pox5EventStakeUpdate | Pox5EventAnnounceL1EarlyExit | Pox5EventUnstakeSbtc | Pox5EventUnstake | Pox5EventCalculateRewards | Pox5EventBondDistribution | Pox5EventClaimRewards;
+/**
+ * Any decoded PoX synthetic event, regardless of the source contract version.
+ *
+ * Two discriminants are available; use whichever fits the call site:
+ *
+ * - `event.pox_version` — `'pox4'` or `'pox5'`. Use this when you only care
+ *   which contract family the event came from (e.g. routing to a per-version
+ *   handler).
+ * - `event.name` — the specific event-name string literal. The pox-4 and
+ *   pox-5 name sets don't overlap, so a single switch on `name` narrows
+ *   all the way down to the per-event interface.
+ */
+export type PoxEvent = Pox4Event | Pox5Event;

package/index.js

@@ -36,7 +36,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PoxEventName = exports.ClarityTypeID = exports.PostConditionModeID = exports.AnchorModeID = exports.TransactionVersion = exports.TxPublicKeyEncoding = exports.TxAuthFieldTypeID = exports.ClarityVersion = exports.TxSpendingConditionMultiSigHashMode = exports.TxSpendingConditionSingleSigHashMode = exports.PostConditionAuthFlag = exports.TxPayloadTypeID = exports.TenureChangeCause = exports.PrincipalTypeID = exports.PostConditionPrincipalTypeID = exports.PostConditionFungibleConditionCodeName = exports.PostConditionFungibleConditionCodeID = exports.PostConditionNonFungibleConditionName = exports.PostConditionNonfungibleConditionCodeID = exports.PostConditionAssetInfoID = exports.StacksNativeEncodingBindings = void 0;
+exports.Pox5EventName = exports.Pox4EventName = exports.ClarityTypeID = exports.PostConditionModeID = exports.AnchorModeID = exports.TransactionVersion = exports.TxPublicKeyEncoding = exports.TxAuthFieldTypeID = exports.ClarityVersion = exports.TxSpendingConditionMultiSigHashMode = exports.TxSpendingConditionSingleSigHashMode = exports.PostConditionAuthFlag = exports.TxPayloadTypeID = exports.TenureChangeCause = exports.PrincipalTypeID = exports.PostConditionPrincipalTypeID = exports.PostConditionFungibleConditionCodeName = exports.PostConditionFungibleConditionCodeID = exports.PostConditionNonFungibleConditionName = exports.PostConditionNonfungibleConditionCodeID = exports.PostConditionAssetInfoID = exports.StacksNativeEncodingBindings = void 0;
 const bindings = __importStar(require("./loader.js"));
 __exportStar(require("./loader.js"), exports);
 exports.StacksNativeEncodingBindings = bindings;
@@ -208,20 +208,58 @@ var ClarityTypeID;
     ClarityTypeID[ClarityTypeID["StringUtf8"] = 14] = "StringUtf8";
 })(ClarityTypeID || (exports.ClarityTypeID = ClarityTypeID = {}));
 // ============================================================================
-// PoX Synthetic Event Types
+// PoX Synthetic Event Types — pox-2 / pox-3 / pox-4
+//
+// These describe synthetic events the Stacks node emits for the older PoX
+// contracts (pox-2 through pox-4). The wire shape is always
+// `Response(Ok({ stacker, locked, ..., name, data }))` — the node
+// synthesizes the wrapper from contract-call return values.
+//
+// PoX-5 changed the model: events are produced by `(print { topic, ... })`
+// calls inside the contract itself, so they have a different shape. Those
+// types live in the next section below.
 // ============================================================================
-var PoxEventName;
-(function (PoxEventName) {
-    PoxEventName["HandleUnlock"] = "handle-unlock";
-    PoxEventName["StackStx"] = "stack-stx";
-    PoxEventName["StackIncrease"] = "stack-increase";
-    PoxEventName["StackExtend"] = "stack-extend";
-    PoxEventName["DelegateStx"] = "delegate-stx";
-    PoxEventName["DelegateStackStx"] = "delegate-stack-stx";
-    PoxEventName["DelegateStackIncrease"] = "delegate-stack-increase";
-    PoxEventName["DelegateStackExtend"] = "delegate-stack-extend";
-    PoxEventName["StackAggregationCommit"] = "stack-aggregation-commit";
-    PoxEventName["StackAggregationCommitIndexed"] = "stack-aggregation-commit-indexed";
-    PoxEventName["StackAggregationIncrease"] = "stack-aggregation-increase";
-    PoxEventName["RevokeDelegateStx"] = "revoke-delegate-stx";
-})(PoxEventName || (exports.PoxEventName = PoxEventName = {}));
+var Pox4EventName;
+(function (Pox4EventName) {
+    Pox4EventName["HandleUnlock"] = "handle-unlock";
+    Pox4EventName["StackStx"] = "stack-stx";
+    Pox4EventName["StackIncrease"] = "stack-increase";
+    Pox4EventName["StackExtend"] = "stack-extend";
+    Pox4EventName["DelegateStx"] = "delegate-stx";
+    Pox4EventName["DelegateStackStx"] = "delegate-stack-stx";
+    Pox4EventName["DelegateStackIncrease"] = "delegate-stack-increase";
+    Pox4EventName["DelegateStackExtend"] = "delegate-stack-extend";
+    Pox4EventName["StackAggregationCommit"] = "stack-aggregation-commit";
+    Pox4EventName["StackAggregationCommitIndexed"] = "stack-aggregation-commit-indexed";
+    Pox4EventName["StackAggregationIncrease"] = "stack-aggregation-increase";
+    Pox4EventName["RevokeDelegateStx"] = "revoke-delegate-stx";
+})(Pox4EventName || (exports.Pox4EventName = Pox4EventName = {}));
+// ============================================================================
+// PoX Synthetic Event Types — pox-5
+//
+// PoX-5 events are emitted by explicit `(print { topic: "...", ... })` calls
+// in the contract source, so each event arrives as a flat Clarity tuple with
+// a `topic` ASCII string plus event-specific data. This is structurally
+// different from pox-2/3/4, where the Stacks node synthesizes a
+// `Response(Ok({ stacker, locked, ..., name, data }))` per stacking call.
+//
+// On the JS side every pox-5 event has the same outer shape
+// `{ name: string, data: { ... } }`; the per-event `data` payloads are
+// modeled below.
+// ============================================================================
+var Pox5EventName;
+(function (Pox5EventName) {
+    Pox5EventName["SetupBond"] = "setup-bond";
+    Pox5EventName["AddToAllowlist"] = "add-to-allowlist";
+    Pox5EventName["RegisterForBond"] = "register-for-bond";
+    Pox5EventName["UpdateBondRegistration"] = "update-bond-registration";
+    Pox5EventName["RegisterSigner"] = "register-signer";
+    Pox5EventName["Stake"] = "stake";
+    Pox5EventName["StakeUpdate"] = "stake-update";
+    Pox5EventName["AnnounceL1EarlyExit"] = "announce-l1-early-exit";
+    Pox5EventName["UnstakeSbtc"] = "unstake-sbtc";
+    Pox5EventName["Unstake"] = "unstake";
+    Pox5EventName["CalculateRewards"] = "calculate-rewards";
+    Pox5EventName["BondDistribution"] = "bond-distribution";
+    Pox5EventName["ClaimRewards"] = "claim-rewards";
+})(Pox5EventName || (exports.Pox5EventName = Pox5EventName = {}));

package/index.mjs

@@ -142,21 +142,37 @@ var ClarityTypeID = /* @__PURE__ */ ((ClarityTypeID2) => {
   ClarityTypeID2[ClarityTypeID2["StringUtf8"] = 14] = "StringUtf8";
   return ClarityTypeID2;
 })(ClarityTypeID || {});
-var PoxEventName = /* @__PURE__ */ ((PoxEventName2) => {
-  PoxEventName2["HandleUnlock"] = "handle-unlock";
-  PoxEventName2["StackStx"] = "stack-stx";
-  PoxEventName2["StackIncrease"] = "stack-increase";
-  PoxEventName2["StackExtend"] = "stack-extend";
-  PoxEventName2["DelegateStx"] = "delegate-stx";
-  PoxEventName2["DelegateStackStx"] = "delegate-stack-stx";
-  PoxEventName2["DelegateStackIncrease"] = "delegate-stack-increase";
-  PoxEventName2["DelegateStackExtend"] = "delegate-stack-extend";
-  PoxEventName2["StackAggregationCommit"] = "stack-aggregation-commit";
-  PoxEventName2["StackAggregationCommitIndexed"] = "stack-aggregation-commit-indexed";
-  PoxEventName2["StackAggregationIncrease"] = "stack-aggregation-increase";
-  PoxEventName2["RevokeDelegateStx"] = "revoke-delegate-stx";
-  return PoxEventName2;
-})(PoxEventName || {});
+var Pox4EventName = /* @__PURE__ */ ((Pox4EventName2) => {
+  Pox4EventName2["HandleUnlock"] = "handle-unlock";
+  Pox4EventName2["StackStx"] = "stack-stx";
+  Pox4EventName2["StackIncrease"] = "stack-increase";
+  Pox4EventName2["StackExtend"] = "stack-extend";
+  Pox4EventName2["DelegateStx"] = "delegate-stx";
+  Pox4EventName2["DelegateStackStx"] = "delegate-stack-stx";
+  Pox4EventName2["DelegateStackIncrease"] = "delegate-stack-increase";
+  Pox4EventName2["DelegateStackExtend"] = "delegate-stack-extend";
+  Pox4EventName2["StackAggregationCommit"] = "stack-aggregation-commit";
+  Pox4EventName2["StackAggregationCommitIndexed"] = "stack-aggregation-commit-indexed";
+  Pox4EventName2["StackAggregationIncrease"] = "stack-aggregation-increase";
+  Pox4EventName2["RevokeDelegateStx"] = "revoke-delegate-stx";
+  return Pox4EventName2;
+})(Pox4EventName || {});
+var Pox5EventName = /* @__PURE__ */ ((Pox5EventName2) => {
+  Pox5EventName2["SetupBond"] = "setup-bond";
+  Pox5EventName2["AddToAllowlist"] = "add-to-allowlist";
+  Pox5EventName2["RegisterForBond"] = "register-for-bond";
+  Pox5EventName2["UpdateBondRegistration"] = "update-bond-registration";
+  Pox5EventName2["RegisterSigner"] = "register-signer";
+  Pox5EventName2["Stake"] = "stake";
+  Pox5EventName2["StakeUpdate"] = "stake-update";
+  Pox5EventName2["AnnounceL1EarlyExit"] = "announce-l1-early-exit";
+  Pox5EventName2["UnstakeSbtc"] = "unstake-sbtc";
+  Pox5EventName2["Unstake"] = "unstake";
+  Pox5EventName2["CalculateRewards"] = "calculate-rewards";
+  Pox5EventName2["BondDistribution"] = "bond-distribution";
+  Pox5EventName2["ClaimRewards"] = "claim-rewards";
+  return Pox5EventName2;
+})(Pox5EventName || {});
 export {
   AnchorModeID,
   ClarityTypeID,
@@ -169,7 +185,8 @@ export {
   PostConditionNonFungibleConditionName,
   PostConditionNonfungibleConditionCodeID,
   PostConditionPrincipalTypeID,
-  PoxEventName,
+  Pox4EventName,
+  Pox5EventName,
   PrincipalTypeID,
   StacksNativeEncodingBindings,
   TenureChangeCause,

package/loader.d.ts

@@ -5,7 +5,7 @@ import type {
   DecodedStacksBlockResult,
   ClarityValue,
   ClarityValueAbstract,
-  DecodedPoxSyntheticEvent,
+  PoxEvent,
 } from './index.js';
 
 export function getVersion(): string;
@@ -72,20 +72,29 @@ export function stacksAddressFromParts(version: number, hash160: string | Buffer
 export function memoToString(memo: string | Buffer): string;
 
 /**
- * Decode a serialized Clarity value representing a PoX synthetic print event.
+ * Decode a serialized Clarity value representing a PoX synthetic event.
+ *
+ * The native runtime sniffs the Clarity value's shape and routes it to the
+ * appropriate per-version decoder:
+ *
+ * - A flat tuple with a `topic` ASCII field → pox-5 event (returns a
+ *   {@link Pox5Event}).
+ * - A `Response(Ok({ stacker, locked, ..., name, data }))` tuple →
+ *   pox-2 / pox-3 / pox-4 event (returns a {@link Pox4Event}).
+ * - Anything else → `null`. This includes pox-2/3/4 `Response(Err _)`
+ *   payloads from failed stacking calls.
+ *
+ * Narrow the result on `event.name` (a string-literal field present on every
+ * variant). The pox-4 and pox-5 name sets don't overlap, so a single switch
+ * over `name` is enough to discriminate.
+ *
  * @param arg - Hex string or Buffer containing the serialized Clarity value
- * @param network - The Stacks network type
- * @returns The decoded PoX event, or null if the Clarity value is a ResponseErr
+ * @param network - The Stacks network type (used only by the pox-4 decoder
+ *   when encoding pox-addr bytes into a BTC address; ignored by pox-5).
+ * @returns The decoded PoX event, or `null` if the Clarity value isn't a
+ *   recognized event shape.
  */
 export function decodePoxSyntheticEvent(
   arg: string | Buffer,
   network: 'mainnet' | 'testnet' | 'devnet' | 'mocknet'
-): DecodedPoxSyntheticEvent | null;
-
-export function startProfiler(): string;
-
-export function stopProfiler(): Buffer;
-
-export function createProfiler(): () => Buffer;
-
-export function perfTestC32Encode(): Buffer;
+): PoxEvent | null;

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@stacks/codec",
-  "version": "1.8.0-pox5.1",
+  "version": "2.0.0-pox5.1",
+  "author": "Stacks Labs",
+  "license": "GPL-3.0",
   "description": "Encoding & decoding functions for the Stacks blockchain exposed as a fast native Node.js addon",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -23,14 +25,8 @@
     "lint": "npm run lint:cargo",
     "lint:cargo": "cargo fmt --all -- --check",
     "lint:fix": "cargo fmt --all",
-    "perf-test:contract-call-args": "node --expose-gc perf-tests/decode-contract-call-args/test.js",
-    "perf-test:decode-post-conditions": "node --expose-gc perf-tests/decode-post-conditions/test.js",
-    "perf-test:encode-stx-address": "node perf-tests/encode-stx-address/test.js",
-    "perf-test:decode-stx-address": "node perf-tests/decode-stx-address/test.js",
     "prepublishOnly": "npm run build"
   },
-  "author": "Stacks Labs",
-  "license": "GPL-3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stx-labs/stacks-codec-js.git"
@@ -49,7 +45,7 @@
     "typescript": "^5.7.0"
   },
   "dependencies": {
-    "@types/node": "^20.14.0",
+    "@types/node": "^24.0.0",
     "detect-libc": "^2.0.1"
   },
   "files": [