@stacks/codec 1.4.1 → 1.5.0

package/README.md

@@ -2,8 +2,8 @@
 
 `@stacks/codec` is a Node.js [native addon](https://nodejs.org/api/addons.html) library written in
 Rust, which provides functions for decoding binary/wire formats used in the Stacks blockchain.
-Features include Clarity values, transactions, post-conditions, Stacks and Bitcoin addresses, and
-more.
+Features include Clarity values, transactions, post-conditions, Stacks and Bitcoin addresses, PoX
+synthetic event parsing, and more.
 
 Various ASM/SIMD optimizations are used in areas which are prone to causing CPU bottlenecks when
 used in hot paths, e.g. decoding raw Clarity values on the fly.
@@ -379,6 +379,34 @@ assert.deepStrictEqual(decoded, {
 ```
 </details>
 
+### Decoding PoX synthetic events
+
+Decode serialized Clarity values from PoX contract log events into structured PoX synthetic event objects. This is useful for parsing stacking, delegation, and unlocking events emitted by the PoX contract.
+
+```ts
+import { decodePoxSyntheticEvent, PoxEventName } from '@stacks/codec';
+
+// Serialized hex string of a PoX synthetic event Clarity value (ResponseOk wrapping a Tuple)
+const rawClarityHex = '0x0700...';
+
+const event = decodePoxSyntheticEvent(rawClarityHex, 'mainnet');
+
+if (event !== null) {
+  console.log(event.name);                      // e.g. 'stack-stx'
+  console.log(event.stacker);                   // e.g. 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7'
+  console.log(event.locked);                    // String-quoted u128, e.g. '1000000'
+  console.log(event.balance);                   // String-quoted u128, e.g. '500000'
+  console.log(event.burnchain_unlock_height);   // String-quoted u128, e.g. '150000'
+  console.log(event.pox_addr);                  // BTC address string or null
+  console.log(event.pox_addr_raw);              // Hex-encoded raw PoX address or null
+  console.log(event.data);                      // Event-specific fields (varies by event type)
+}
+```
+
+Supported event types: `handle-unlock`, `stack-stx`, `stack-increase`, `stack-extend`, `delegate-stx`, `delegate-stack-stx`, `delegate-stack-increase`, `delegate-stack-extend`, `stack-aggregation-commit`, `stack-aggregation-commit-indexed`, `stack-aggregation-increase`, `revoke-delegate-stx`.
+
+Returns `null` when the Clarity value is a `ResponseErr` (indicating a non-event). Bitcoin address encoding supports P2PKH, P2SH, P2WPKH (segwit v0), P2WSH (segwit v0), and P2TR (taproot/segwit v1) address formats.
+
 ## Project Layout
 
 The directory structure of this project is:

package/index.d.ts

@@ -519,3 +519,200 @@ export interface StacksWorkScore {
     /** String-quoted unsigned integer - work score */
     work: string;
 }
+export declare enum PoxEventName {
+    HandleUnlock = "handle-unlock",
+    StackStx = "stack-stx",
+    StackIncrease = "stack-increase",
+    StackExtend = "stack-extend",
+    DelegateStx = "delegate-stx",
+    DelegateStackStx = "delegate-stack-stx",
+    DelegateStackIncrease = "delegate-stack-increase",
+    DelegateStackExtend = "delegate-stack-extend",
+    StackAggregationCommit = "stack-aggregation-commit",
+    StackAggregationCommitIndexed = "stack-aggregation-commit-indexed",
+    StackAggregationIncrease = "stack-aggregation-increase",
+    RevokeDelegateStx = "revoke-delegate-stx"
+}
+export interface PoxEventBase {
+    stacker: string;
+    /** String-quoted unsigned integer */
+    locked: string;
+    /** String-quoted unsigned integer */
+    balance: string;
+    /** String-quoted unsigned integer */
+    burnchain_unlock_height: string;
+    pox_addr: string | null;
+    pox_addr_raw: string | null;
+}
+export interface PoxEventHandleUnlock extends PoxEventBase {
+    name: PoxEventName.HandleUnlock;
+    data: {
+        /** String-quoted unsigned integer */
+        first_cycle_locked: string;
+        /** String-quoted unsigned integer */
+        first_unlocked_cycle: string;
+    };
+}
+export interface PoxEventStackStx extends PoxEventBase {
+    name: PoxEventName.StackStx;
+    data: {
+        /** String-quoted unsigned integer */
+        lock_amount: string;
+        /** String-quoted unsigned integer */
+        lock_period: string;
+        /** String-quoted unsigned integer */
+        start_burn_height: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** Hex string or null */
+        signer_key: string | null;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventStackIncrease extends PoxEventBase {
+    name: PoxEventName.StackIncrease;
+    data: {
+        /** String-quoted unsigned integer */
+        increase_by: string;
+        /** String-quoted unsigned integer */
+        total_locked: string;
+        /** Hex string or null */
+        signer_key: string | null;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventStackExtend extends PoxEventBase {
+    name: PoxEventName.StackExtend;
+    data: {
+        /** String-quoted unsigned integer */
+        extend_count: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** Hex string or null */
+        signer_key: string | null;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventDelegateStx extends PoxEventBase {
+    name: PoxEventName.DelegateStx;
+    data: {
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        delegate_to: string;
+        /** String-quoted unsigned integer or null */
+        unlock_burn_height: string | null;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventDelegateStackStx extends PoxEventBase {
+    name: PoxEventName.DelegateStackStx;
+    data: {
+        /** String-quoted unsigned integer */
+        lock_amount: string;
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** String-quoted unsigned integer */
+        start_burn_height: string;
+        /** String-quoted unsigned integer */
+        lock_period: string;
+        delegator: string;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventDelegateStackIncrease extends PoxEventBase {
+    name: PoxEventName.DelegateStackIncrease;
+    data: {
+        /** String-quoted unsigned integer */
+        increase_by: string;
+        /** String-quoted unsigned integer */
+        total_locked: string;
+        delegator: string;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventDelegateStackExtend extends PoxEventBase {
+    name: PoxEventName.DelegateStackExtend;
+    data: {
+        /** String-quoted unsigned integer */
+        unlock_burn_height: string;
+        /** String-quoted unsigned integer */
+        extend_count: string;
+        delegator: string;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventStackAggregationCommit extends PoxEventBase {
+    name: PoxEventName.StackAggregationCommit;
+    data: {
+        /** String-quoted unsigned integer */
+        reward_cycle: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** Hex string or null */
+        signer_key: string | null;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventStackAggregationCommitIndexed extends PoxEventBase {
+    name: PoxEventName.StackAggregationCommitIndexed;
+    data: {
+        /** String-quoted unsigned integer */
+        reward_cycle: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** Hex string or null */
+        signer_key: string | null;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventStackAggregationIncrease extends PoxEventBase {
+    name: PoxEventName.StackAggregationIncrease;
+    data: {
+        /** String-quoted unsigned integer */
+        reward_cycle: string;
+        /** String-quoted unsigned integer */
+        amount_ustx: string;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export interface PoxEventRevokeDelegateStx extends PoxEventBase {
+    name: PoxEventName.RevokeDelegateStx;
+    data: {
+        delegate_to: string;
+        /** String-quoted unsigned integer or null */
+        end_cycle_id: string | null;
+        /** String-quoted unsigned integer or null */
+        start_cycle_id: string | null;
+    };
+}
+export declare type DecodedPoxSyntheticEvent = PoxEventHandleUnlock | PoxEventStackStx | PoxEventStackIncrease | PoxEventStackExtend | PoxEventDelegateStx | PoxEventDelegateStackStx | PoxEventDelegateStackIncrease | PoxEventDelegateStackExtend | PoxEventStackAggregationCommit | PoxEventStackAggregationCommitIndexed | PoxEventStackAggregationIncrease | PoxEventRevokeDelegateStx;

package/index.js

@@ -14,7 +14,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.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.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;
 const bindings = require("./loader");
 __exportStar(require("./loader"), exports);
 exports.StacksNativeEncodingBindings = bindings;
@@ -180,3 +180,21 @@ var ClarityTypeID;
     ClarityTypeID[ClarityTypeID["StringAscii"] = 13] = "StringAscii";
     ClarityTypeID[ClarityTypeID["StringUtf8"] = 14] = "StringUtf8";
 })(ClarityTypeID = exports.ClarityTypeID || (exports.ClarityTypeID = {}));
+// ============================================================================
+// PoX Synthetic Event Types
+// ============================================================================
+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 || (exports.PoxEventName = {}));

package/loader.d.ts

@@ -1,4 +1,4 @@
-import type { DecodedPostConditionsResult, DecodedTxResult, DecodedNakamotoBlockResult, DecodedStacksBlockResult, ClarityValue, ClarityValueAbstract } from ".";
+import type { DecodedPostConditionsResult, DecodedTxResult, DecodedNakamotoBlockResult, DecodedStacksBlockResult, ClarityValue, ClarityValueAbstract, DecodedPoxSyntheticEvent } from ".";
 
 export function getVersion(): string;
 
@@ -60,6 +60,17 @@ 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.
+ * @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
+ */
+export function decodePoxSyntheticEvent(
+  arg: string | Buffer,
+  network: 'mainnet' | 'testnet' | 'devnet' | 'mocknet'
+): DecodedPoxSyntheticEvent | null;
+
 export function startProfiler(): string;
 
 export function stopProfiler(): Buffer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacks/codec",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Encoding & decoding functions for the Stacks blockchain exposed as a fast native Node.js addon",
   "main": "index.js",
   "scripts": {