@stacks/codec 1.4.0

package/README.md

@@ -0,0 +1,404 @@
+# Stacks Codec JS
+
+`@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.
+
+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.
+
+_This project was bootstrapped by [create-neon](https://www.npmjs.com/package/create-neon)._
+
+### Runtime Support
+* Node.js v16+
+
+### Platform Support
+
+* Linux (glibc) x86_64
+* Linux (glibc) aarch64
+* Linux (musl) x86_64
+* Linux (musl) aarch64
+* MacOS x86_64
+* MacOS aarch64 (Apple Silicon M1)
+* Windows x86_64
+
+## Installation and Usage
+
+```shell
+npm install @stacks/codec
+```
+
+### Decoding serialized Clarity values
+_Example Clarity value:_
+<details>
+<summary>Expand</summary>
+
+```clar
+(tuple 
+  (active true) 
+  (address 'SPA2MZWV9N67TBYVWTE0PSSKMJ2F6YXW7CBE6YPW) 
+  (alias "Alice") 
+  (balance u2000) 
+  (ping (ok 250)) 
+  (public_key (some 0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58)) 
+  (tags (list u"contributor" u"og \u{e2ad90}" u"clarity"))
+)
+```
+</details>
+
+#### Decode serialized Clarity value to repr string
+```ts
+import * as assert from 'node:assert';
+import { decodeClarityValueToRepr } from '@stacks/codec';
+
+// Serialized hex string of the example Clarity value (0x-prefix optional, Buffer / Uint8Array also accepted)
+const hex = '0x0c00000007066163746976650307616464726573730516142a7f9b4d4c7d2fdbe69c0b6733a484f37bbc3b05616c6961730d00000005416c6963650762616c616e636501000000000000000000000000000007d00470696e670700000000000000000000000000000000fa0a7075626c69635f6b65790a020000002102d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e5804746167730b000000030e0000000b636f6e7472696275746f720e000000066f6720e2ad900e00000007636c6172697479';
+
+const reprStr = decodeClarityValueToRepr(hex);
+
+assert.strictEqual(
+  reprStr, 
+  `(tuple (active true) (address 'SPA2MZWV9N67TBYVWTE0PSSKMJ2F6YXW7CBE6YPW) (alias "Alice") (balance u2000) (ping (ok 250)) (public_key (some 0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58)) (tags (list u"contributor" u"og \\u{e2ad90}" u"clarity")))`
+);
+```
+
+#### Decode serialized Clarity value to object
+```ts
+import * as assert from 'node:assert';
+import { decodeClarityValue } from '@stacks/codec';
+
+// Serialized hex string of the example Clarity value (0x-prefix optional, Buffer / Uint8Array also accepted)
+const hex = '0x0c00000007066163746976650307616464726573730516142a7f9b4d4c7d2fdbe69c0b6733a484f37bbc3b05616c6961730d00000005416c6963650762616c616e636501000000000000000000000000000007d00470696e670700000000000000000000000000000000fa0a7075626c69635f6b65790a020000002102d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e5804746167730b000000030e0000000b636f6e7472696275746f720e000000066f6720e2ad900e00000007636c6172697479';
+
+// Decode into JSON object
+const decoded = decodeClarityValue(hex);
+```
+
+Decoded Clarity value output result:
+
+<details>
+<summary>Expand</summary>
+
+```ts
+// Result object
+assert.deepStrictEqual(decoded, {
+  repr: `(tuple (active true) (address 'SPA2MZWV9N67TBYVWTE0PSSKMJ2F6YXW7CBE6YPW) (alias "Alice") (balance u2000) (ping (ok 250)) (public_key (some 0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58)) (tags (list u"contributor" u"og \\u{e2ad90}" u"clarity")))`,
+  hex: '0x0c00000007066163746976650307616464726573730516142a7f9b4d4c7d2fdbe69c0b6733a484f37bbc3b05616c6961730d00000005416c6963650762616c616e636501000000000000000000000000000007d00470696e670700000000000000000000000000000000fa0a7075626c69635f6b65790a020000002102d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e5804746167730b000000030e0000000b636f6e7472696275746f720e000000066f6720e2ad900e00000007636c6172697479',
+  type_id: 12,
+  data: {
+    active: { repr: 'true', hex: '0x03', type_id: 3, value: true },
+    address: {
+      repr: "'SPA2MZWV9N67TBYVWTE0PSSKMJ2F6YXW7CBE6YPW",
+      hex: '0x0516142a7f9b4d4c7d2fdbe69c0b6733a484f37bbc3b',
+      type_id: 5,
+      address_version: 22,
+      address_hash_bytes: '0x142a7f9b4d4c7d2fdbe69c0b6733a484f37bbc3b',
+      address: 'SPA2MZWV9N67TBYVWTE0PSSKMJ2F6YXW7CBE6YPW'
+    },
+    alias: {
+      repr: '"Alice"',
+      hex: '0x0d00000005416c696365',
+      type_id: 13,
+      data: 'Alice'
+    },
+    balance: {
+      repr: 'u2000',
+      hex: '0x01000000000000000000000000000007d0',
+      type_id: 1,
+      value: '2000'
+    },
+    ping: {
+      repr: '(ok 250)',
+      hex: '0x0700000000000000000000000000000000fa',
+      type_id: 7,
+      value: {
+        repr: '250',
+        hex: '0x00000000000000000000000000000000fa',
+        type_id: 0,
+        value: '250'
+      }
+    },
+    public_key: {
+      repr: '(some 0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58)',
+      hex: '0x0a020000002102d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58',
+      type_id: 10,
+      value: {
+        repr: '0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58',
+        hex: '0x020000002102d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58',
+        type_id: 2,
+        buffer: '0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58'
+      }
+    },
+    tags: {
+      repr: '(list u"contributor" u"og \\u{e2ad90}" u"clarity")',
+      hex: '0x0b000000030e0000000b636f6e7472696275746f720e000000066f6720e2ad900e00000007636c6172697479',
+      type_id: 11,
+      list: [
+        {
+          repr: 'u"contributor"',
+          hex: '0x0e0000000b636f6e7472696275746f72',
+          type_id: 14,
+          data: 'contributor'
+        },
+        {
+          repr: 'u"og \\u{e2ad90}"',
+          hex: '0x0e000000066f6720e2ad90',
+          type_id: 14,
+          data: 'og ⭐'
+        },
+        {
+          repr: 'u"clarity"',
+          hex: '0x0e00000007636c6172697479',
+          type_id: 14,
+          data: 'clarity'
+        }
+      ]
+    }
+  }
+});
+```
+</details>
+
+#### Decode serialized Clarity value to typed object
+
+```ts
+import * as assert from 'node:assert';
+import { 
+  decodeClarityValue,
+  ClarityTypeID,
+  ClarityValueTuple,
+  ClarityValuePrincipalStandard,
+  ClarityValueStringAscii,
+  ClarityValueInt,
+  ClarityValueBoolTrue,
+  ClarityValueResponseOk,
+  ClarityValueBuffer,
+  ClarityValueList,
+  ClarityValueStringUtf8,
+  ClarityValueOptionalSome,
+  ClarityValueUInt,
+} from '@stacks/codec';
+
+// Serialized hex string of the example Clarity value (0x-prefix optional, Buffer / Uint8Array also accepted)
+const hex = '0x0c00000007066163746976650307616464726573730516142a7f9b4d4c7d2fdbe69c0b6733a484f37bbc3b05616c6961730d00000005416c6963650762616c616e636501000000000000000000000000000007d00470696e670700000000000000000000000000000000fa0a7075626c69635f6b65790a020000002102d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e5804746167730b000000030e0000000b636f6e7472696275746f720e000000066f6720e2ad900e00000007636c6172697479';
+
+// Provide a typed view of the decoded value
+const decoded = decodeClarityValue<ClarityValueTuple<{
+  active: ClarityValueBoolTrue;
+  address: ClarityValuePrincipalStandard;
+  alias: ClarityValueStringAscii;
+  balance: ClarityValueUInt;
+  ping: ClarityValueResponseOk<ClarityValueInt>;
+  public_key: ClarityValueOptionalSome<ClarityValueBuffer>;
+  tags: ClarityValueList<ClarityValueStringUtf8>;
+}>>(hex);
+
+assert.deepStrictEqual(decoded.data.tags.list.map(v => v.data), ['contributor', 'og ⭐', 'clarity']);
+```
+
+The annotated types are _not_ automatically checked at runtime, so type checks are needed for error handling:
+
+<details>
+<summary>Expand</summary>
+
+```ts
+assert.strictEqual(decoded.type_id, ClarityTypeID.Tuple);
+assert.strictEqual(decoded.data.active.type_id, ClarityTypeID.BoolTrue);
+assert.strictEqual(decoded.data.address.type_id, ClarityTypeID.PrincipalStandard);
+assert.strictEqual(decoded.data.alias.type_id, ClarityTypeID.StringAscii);
+assert.strictEqual(decoded.data.balance.type_id, ClarityTypeID.UInt);
+assert.strictEqual(decoded.data.ping.type_id, ClarityTypeID.ResponseOk);
+assert.strictEqual(decoded.data.ping.value.type_id, ClarityTypeID.Int);
+assert.strictEqual(decoded.data.public_key.type_id, ClarityTypeID.OptionalSome);
+assert.strictEqual(decoded.data.public_key.value.type_id, ClarityTypeID.Buffer);
+assert.strictEqual(decoded.data.tags.type_id, ClarityTypeID.List);
+assert.strictEqual(decoded.data.tags.list[0].type_id, ClarityTypeID.StringUtf8);
+
+// Now we can safely access typed properties
+assert.strictEqual(decoded.data.active.value, true);
+assert.strictEqual(decoded.data.address.address, 'SPA2MZWV9N67TBYVWTE0PSSKMJ2F6YXW7CBE6YPW');
+assert.strictEqual(decoded.data.alias.data, 'Alice');
+assert.strictEqual(decoded.data.balance.value, '2000');
+assert.strictEqual(decoded.data.ping.value.value, '250');
+assert.strictEqual(decoded.data.public_key.value.buffer, '0x02d4dada83bff981f0cb7ebafcfc6fc7cb5e078b9ee2302a93aae19fb90f872e58');
+assert.deepStrictEqual(decoded.data.tags.list.map(v => v.data), ['contributor', 'og ⭐', 'clarity']);
+```
+</details>
+
+### Decoding principals
+
+#### Principal from serialized Clarity value
+
+```ts
+import * as assert from 'node:assert';
+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');
+
+const contractPrincipal = decodeClarityValueToPrincipal('0x0616a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c616273');
+assert.strictEqual(contractPrincipal, 'SP2KAF9RF86PVX3NEE27DFV1CQX0T4WGR41X3S45C.bitcoin-monkeys-labs');
+```
+
+#### Stacks address from parts
+
+```ts
+import * as assert from 'node:assert';
+import { stacksAddressFromParts } from '@stacks/codec';
+
+const stacksAddressData = {
+  version: 26,
+  // Serialized hex string (0x-prefix optional, Buffer / Uint8Array also accepted)
+  hash160: '0xcd1f5bc9aa49e7417cee3e5dba1a92567da41af6'
+};
+
+const stacksAddress = stacksAddressFromParts(stacksAddressData.version, stacksAddressData.hash160);
+assert.strictEqual(stacksAddress, 'ST36HYPY9N94YEGBWXRZ5VEGTJ9B7V90TYTM9HGTJ');
+```
+
+#### Stacks address to parts
+
+```ts
+import * as assert from 'node:assert';
+import { decodeStacksAddress } from '@stacks/codec';
+
+const [version, hash160] = decodeStacksAddress('ST36HYPY9N94YEGBWXRZ5VEGTJ9B7V90TYTM9HGTJ');
+assert.strictEqual(version, 26);
+assert.strictEqual(hash160, '0xcd1f5bc9aa49e7417cee3e5dba1a92567da41af6');
+```
+
+### Decoding transactions
+
+```ts
+import * as assert from 'node:assert';
+import { 
+  decodeTransaction,
+  AnchorModeID,
+  TransactionVersion,
+  TxPayloadTypeID,
+  TxSpendingConditionSingleSigHashMode,
+  TxPublicKeyEncoding,
+  ClarityTypeID,
+  PostConditionModeID,
+  PostConditionAuthFlag,
+  PostConditionAssetInfoID,
+  PostConditionNonfungibleConditionCodeID,
+  PostConditionNonFungibleConditionName
+} from '@stacks/codec';
+
+// Serialized hex string (0x-prefix optional, Buffer / Uint8Array also accepted)
+const rawTx = '0000000001040089f5fd1f719e4449c980de38e3504be6770a2698000000000000014500000000000001f400008b510c9e20dc22040953d9d7eabf2038008fa4d89a5a6cb78bb9d513e75cd0df3924af9ce3b5f185705bc2f6ba3071710ec6a8803ed6da4addc40a05a01ee0f503020000000102021689f5fd1f719e4449c980de38e3504be6770a269816a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c61627314626974636f696e2d6d6f6e6b6579732d6c61627301000000000000000000000000000008ba1002162bcf9762d5b90bc36dc1b4759b1727690f92ddd30e6d61726b6574706c6163652d76340a6c6973742d6173736574000000040616a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c61627301000000000000000000000000000008ba010000000000000000000000000c84588001000000000000000000000000000000c8';
+
+const decoded = decodeTransaction(rawTx);
+```
+
+Decoded transaction output result:
+<details>
+<summary>Expand</summary>
+
+```ts
+assert.deepStrictEqual(decoded, {
+  tx_id: "0x49bcdba540d5c486f6f7a71de639a128a65f0378d7571e20c75a61661dd5b469",
+  chain_id: 1,
+  version: TransactionVersion.Mainnet,
+  anchor_mode: AnchorModeID.Any,
+  auth: {
+    type_id: PostConditionAuthFlag.Standard,
+    origin_condition: {
+      hash_mode: TxSpendingConditionSingleSigHashMode.P2PKH,
+      key_encoding: TxPublicKeyEncoding.Compressed,
+      nonce: "325",
+      signature: "0x008b510c9e20dc22040953d9d7eabf2038008fa4d89a5a6cb78bb9d513e75cd0df3924af9ce3b5f185705bc2f6ba3071710ec6a8803ed6da4addc40a05a01ee0f5",
+      signer: {
+        address: "SP24ZBZ8ZE6F48JE9G3F3HRTG9FK7E2H6K2QZ3Q1K",
+        address_hash_bytes: "0x89f5fd1f719e4449c980de38e3504be6770a2698",
+        address_version: 22
+      },
+      tx_fee: "500"
+    }
+  },
+  payload: {
+    type_id: TxPayloadTypeID.ContractCall,
+    address: "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S",
+    address_hash_bytes: "0x2bcf9762d5b90bc36dc1b4759b1727690f92ddd3",
+    address_version: 22,
+    contract_name: "marketplace-v4",
+    function_name: "list-asset",
+    function_args: [
+      {
+        type_id: ClarityTypeID.PrincipalContract,
+        hex: "0x0616a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c616273",
+        repr: "'SP2KAF9RF86PVX3NEE27DFV1CQX0T4WGR41X3S45C.bitcoin-monkeys-labs"
+      },
+      {
+        type_id: ClarityTypeID.UInt,
+        hex: "0x01000000000000000000000000000008ba",
+        repr: "u2234"
+      },
+      {
+        type_id: ClarityTypeID.UInt,
+        hex: "0x010000000000000000000000000c845880",
+        repr: "u210000000"
+      },
+      {
+        type_id: ClarityTypeID.UInt,
+        hex: "0x01000000000000000000000000000000c8",
+        repr: "u200"
+      }
+    ],
+    function_args_buffer: "0x000000040616a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c61627301000000000000000000000000000008ba010000000000000000000000000c84588001000000000000000000000000000000c8"
+  },
+  post_condition_mode: PostConditionModeID.Deny,
+  post_conditions: [
+    {
+      condition_code: PostConditionNonfungibleConditionCodeID.Sent,
+      condition_name: PostConditionNonFungibleConditionName.Sent,
+      asset: {
+        asset_name: "bitcoin-monkeys-labs",
+        contract_address: "SP2KAF9RF86PVX3NEE27DFV1CQX0T4WGR41X3S45C",
+        contract_name: "bitcoin-monkeys-labs"
+      },
+      asset_info_id: PostConditionAssetInfoID.NonfungibleAsset,
+      asset_value: {
+        hex: "0x01000000000000000000000000000008ba",
+        repr: "u2234",
+        type_id: ClarityTypeID.UInt
+      },
+      principal: {
+        address: "SP24ZBZ8ZE6F48JE9G3F3HRTG9FK7E2H6K2QZ3Q1K",
+        address_hash_bytes: "0x89f5fd1f719e4449c980de38e3504be6770a2698",
+        address_version: 22,
+        type_id: ClarityTypeID.Buffer
+      }
+    }
+  ],
+  post_conditions_buffer: "0x020000000102021689f5fd1f719e4449c980de38e3504be6770a269816a6a7a70f41adbe8eae708ed7ec2cbf41a272182014626974636f696e2d6d6f6e6b6579732d6c61627314626974636f696e2d6d6f6e6b6579732d6c61627301000000000000000000000000000008ba10"
+});
+```
+</details>
+
+## Project Layout
+
+The directory structure of this project is:
+
+<pre>
+/
+├── 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
+</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). 
+
+## NPM Library Bundling
+
+The Node addon modules for all supported platforms are compiled by [CI](.github/workflows/build.yml) and bundled inside the npm package. The native binary files are small enough that the bundled npm package is an acceptable ~20 MB in size. 

package/index.d.ts

@@ -0,0 +1,521 @@
+import * as bindings from './loader';
+export * from './loader';
+export declare const StacksNativeEncodingBindings: typeof bindings;
+export default StacksNativeEncodingBindings;
+export declare type TxPostCondition = PostConditionStx | PostConditionFungible | PostConditionNonfungible;
+export interface DecodedPostConditionsResult {
+    post_condition_mode: PostConditionModeID;
+    post_conditions: TxPostCondition[];
+}
+export interface DecodedTxResult {
+    /** Hex encoded string of the serialized transaction */
+    tx_id: string;
+    version: TransactionVersion;
+    chain_id: number;
+    auth: TxAuthStandard | TxAuthSponsored;
+    anchor_mode: AnchorModeID;
+    post_condition_mode: PostConditionModeID;
+    post_conditions: TxPostCondition[];
+    /** Hex string */
+    post_conditions_buffer: string;
+    payload: TxPayloadTokenTransfer | TxPayloadSmartContract | TxPayloadContractCall | TxPayloadPoisonMicroblock | TxPayloadCoinbase | TxPayloadCoinbaseToAltRecipient | TxPayloadVersionedSmartContract | TxPayloadTenureChange | TxPayloadNakamotoCoinbase;
+}
+export declare enum PostConditionAssetInfoID {
+    STX = 0,
+    FungibleAsset = 1,
+    NonfungibleAsset = 2
+}
+export interface PostConditionStx {
+    asset_info_id: PostConditionAssetInfoID.STX;
+    principal: PostConditionPrincipal;
+    condition_code: PostConditionFungibleConditionCodeID;
+    condition_name: PostConditionFungibleConditionCodeName;
+    amount: string;
+}
+export interface PostConditionFungible {
+    asset_info_id: PostConditionAssetInfoID.FungibleAsset;
+    principal: PostConditionPrincipal;
+    asset: PostConditionAssetInfo;
+    condition_code: PostConditionFungibleConditionCodeID;
+    condition_name: PostConditionFungibleConditionCodeName;
+    amount: string;
+}
+export interface PostConditionNonfungible {
+    asset_info_id: PostConditionAssetInfoID.NonfungibleAsset;
+    principal: PostConditionPrincipal;
+    asset: PostConditionAssetInfo;
+    asset_value: ClarityValueAbstract;
+    condition_code: PostConditionNonfungibleConditionCodeID;
+    condition_name: PostConditionNonFungibleConditionName;
+}
+export interface PostConditionAssetInfo {
+    contract_address: string;
+    contract_name: string;
+    asset_name: string;
+}
+export declare enum PostConditionNonfungibleConditionCodeID {
+    Sent = 16,
+    NotSent = 17
+}
+export declare enum PostConditionNonFungibleConditionName {
+    Sent = "sent",
+    NotSent = "not_sent"
+}
+export declare enum PostConditionFungibleConditionCodeID {
+    SentEq = 1,
+    SentGt = 2,
+    SentGe = 3,
+    SentLt = 4,
+    SentLe = 5
+}
+export declare enum PostConditionFungibleConditionCodeName {
+    SentEq = "sent_equal_to",
+    SentGt = "sent_greater_than",
+    SentGe = "sent_greater_than_or_equal_to",
+    SentLt = "sent_less_than",
+    SentLe = "sent_less_than_or_equal_to"
+}
+export declare enum PostConditionPrincipalTypeID {
+    /** A STX post-condition, which pertains to the origin account's STX. */
+    Origin = 1,
+    /** A Fungible token post-condition, which pertains to one of the origin account's fungible tokens. */
+    Standard = 2,
+    /** A Non-fungible token post-condition, which pertains to one of the origin account's non-fungible tokens. */
+    Contract = 3
+}
+export declare type PostConditionPrincipal = PostConditionPrincipalOrigin | PostConditionPrincipalStandard | PostConditionPrincipalContract;
+export interface PostConditionPrincipalOrigin {
+    type_id: PostConditionPrincipalTypeID.Origin;
+}
+export interface PostConditionPrincipalStandard {
+    type_id: PostConditionPrincipalTypeID.Standard;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+    address: string;
+}
+export interface PostConditionPrincipalContract {
+    type_id: PostConditionPrincipalTypeID.Contract;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+    address: string;
+    contract_name: string;
+}
+export interface TxPayloadTokenTransfer {
+    type_id: TxPayloadTypeID.TokenTransfer;
+    recipient: PrincipalStandardData | PrincipalContractData;
+    amount: string;
+    /** Hex encoded string of the 34-bytes */
+    memo_hex: string;
+}
+export declare enum PrincipalTypeID {
+    Standard = 5,
+    Contract = 6
+}
+export interface PrincipalStandardData {
+    type_id: PrincipalTypeID.Standard;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+    address: string;
+}
+export interface PrincipalContractData {
+    type_id: PrincipalTypeID.Contract;
+    contract_name: string;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+    address: string;
+}
+export interface TxPayloadSmartContract {
+    type_id: TxPayloadTypeID.SmartContract;
+    contract_name: string;
+    code_body: string;
+}
+export interface TxPayloadContractCall {
+    type_id: TxPayloadTypeID.ContractCall;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+    address: string;
+    contract_name: string;
+    function_name: string;
+    function_args: ClarityValueAbstract[];
+    /** Hex string */
+    function_args_buffer: string;
+}
+export interface TxPayloadPoisonMicroblock {
+    type_id: TxPayloadTypeID.PoisonMicroblock;
+    microblock_header_1: TxMicroblockHeader;
+    microblock_header_2: TxMicroblockHeader;
+}
+export interface TxPayloadCoinbase {
+    type_id: TxPayloadTypeID.Coinbase;
+    /** Hex string */
+    payload_buffer: string;
+}
+export interface TxPayloadCoinbaseToAltRecipient {
+    type_id: TxPayloadTypeID.CoinbaseToAltRecipient;
+    /** Hex string */
+    payload_buffer: string;
+    recipient: PrincipalStandardData | PrincipalContractData;
+}
+export interface TxPayloadNakamotoCoinbase {
+    type_id: TxPayloadTypeID.NakamotoCoinbase;
+    /** Hex string */
+    payload_buffer: string;
+    /** Optional, null if not specified */
+    recipient: PrincipalStandardData | PrincipalContractData | null;
+    /** Hex string */
+    vrf_proof: string;
+}
+export interface TxPayloadVersionedSmartContract {
+    type_id: TxPayloadTypeID.VersionedSmartContract;
+    clarity_version: ClarityVersion;
+    contract_name: string;
+    code_body: string;
+}
+export interface TxPayloadTenureChange {
+    type_id: TxPayloadTypeID.TenureChange;
+    /** Consensus hash of this tenure.  Corresponds to the sortition in which the miner of this
+     * block was chosen. It may be the case that this miner's tenure gets _extended_ across
+     * subsequent sortitions; if this happens, then this `consensus_hash` value _remains the same_
+     * as the sortition in which the winning block-commit was mined. */
+    tenure_consensus_hash: string;
+    /** Consensus hash of the previous tenure. Corresponds to the sortition of the previous winning block-commit. */
+    prev_tenure_consensus_hash: string;
+    /** Current consensus hash on the underlying burnchain. Corresponds to the last-seen sortition. */
+    burn_view_consensus_hash: string;
+    /** The StacksBlockId of the last block from the previous tenure */
+    previous_tenure_end: string;
+    /** The number of blocks produced since the last sortition-linked tenure */
+    previous_tenure_blocks: number;
+    /** Cause of change in mining tenure. Depending on cause, tenure can be ended or extended. */
+    cause: TenureChangeCause;
+    /** (Hex string) The ECDSA public key hash of the current tenure */
+    pubkey_hash: string;
+}
+export declare enum TenureChangeCause {
+    /** A valid winning block-commit */
+    BlockFound = 0,
+    /** The next burnchain block is taking too long, so extend the runtime budget */
+    Extended = 1,
+    /** SIP-034: extend specific dimensions - runtime */
+    ExtendedRuntime = 2,
+    /** SIP-034: extend specific dimensions - read count */
+    ExtendedReadCount = 3,
+    /** SIP-034: extend specific dimensions - read length */
+    ExtendedReadLength = 4,
+    /** SIP-034: extend specific dimensions - write count */
+    ExtendedWriteCount = 5,
+    /** SIP-034: extend specific dimensions - write length */
+    ExtendedWriteLength = 6
+}
+export declare enum TxPayloadTypeID {
+    TokenTransfer = 0,
+    SmartContract = 1,
+    ContractCall = 2,
+    PoisonMicroblock = 3,
+    Coinbase = 4,
+    CoinbaseToAltRecipient = 5,
+    VersionedSmartContract = 6,
+    TenureChange = 7,
+    NakamotoCoinbase = 8
+}
+export declare enum PostConditionAuthFlag {
+    Standard = 4,
+    Sponsored = 5
+}
+export interface TxAuthStandard {
+    type_id: PostConditionAuthFlag.Standard;
+    origin_condition: DecodedTxSpendingConditionSingleSig | DecodedTxSpendingConditionMultiSig;
+}
+export interface TxAuthSponsored {
+    type_id: PostConditionAuthFlag.Sponsored;
+    origin_condition: DecodedTxSpendingConditionSingleSig | DecodedTxSpendingConditionMultiSig;
+    sponsor_condition: DecodedTxSpendingConditionSingleSig | DecodedTxSpendingConditionMultiSig;
+}
+export declare enum TxSpendingConditionSingleSigHashMode {
+    /** hash160(public-key), same as bitcoin's p2pkh */
+    P2PKH = 0,
+    /** hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh */
+    P2WPKH = 2
+}
+export declare enum TxSpendingConditionMultiSigHashMode {
+    /** hash160(multisig-redeem-script), same as bitcoin's multisig p2sh */
+    P2SH = 1,
+    /** hash160(multisig-redeem-script), same as bitcoin's multisig p2sh (non-sequential signing) */
+    P2SHNonSequential = 5,
+    /** hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh */
+    P2WSH = 3,
+    /** hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh (non-sequential signing) */
+    P2WSHNonSequential = 7
+}
+export declare enum ClarityVersion {
+    Clarity1 = 1,
+    Clarity2 = 2,
+    Clarity3 = 3,
+    Clarity4 = 4,
+    Clarity5 = 5
+}
+export interface DecodedTxSpendingConditionSingleSig {
+    hash_mode: TxSpendingConditionSingleSigHashMode;
+    signer: DecodedStacksAddress;
+    nonce: string;
+    tx_fee: string;
+    /** A 1-byte public key encoding field to indicate whether or not the public key should be compressed before hashing. */
+    key_encoding: TxPublicKeyEncoding;
+    signature: string;
+}
+export interface DecodedTxSpendingConditionMultiSig {
+    hash_mode: TxSpendingConditionMultiSigHashMode;
+    signer: DecodedStacksAddress;
+    nonce: string;
+    tx_fee: string;
+    fields: (TxAuthFieldPublicKey | TxAuthFieldSignature)[];
+    signatures_required: number;
+}
+export declare enum TxAuthFieldTypeID {
+    /** The next 33 bytes are a compressed secp256k1 public key. If the field ID is 0x00, the key will be loaded as a compressed secp256k1 public key. */
+    PublicKeyCompressed = 0,
+    /** The next 33 bytes are a compressed secp256k1 public key. If it is 0x01, then the key will be loaded as an uncompressed secp256k1 public key. */
+    PublicKeyUncompressed = 1,
+    /** The next 65 bytes are a recoverable secp256k1 ECDSA signature. If the field ID is 0x02, then the recovered public key will be loaded as a compressed public key. */
+    SignatureCompressed = 2,
+    /** The next 65 bytes are a recoverable secp256k1 ECDSA signature. If it is 0x03, then the recovered public key will be loaded as an uncompressed public key. */
+    SignatureUncompressed = 3
+}
+export interface TxAuthFieldPublicKey {
+    type_id: TxAuthFieldTypeID.PublicKeyCompressed | TxAuthFieldTypeID.PublicKeyUncompressed;
+    /** Hex encoded public key bytes. */
+    public_key: string;
+}
+export interface TxAuthFieldSignature {
+    type_id: TxAuthFieldTypeID.SignatureCompressed | TxAuthFieldTypeID.SignatureUncompressed;
+    /** Hex encoded signatures bytes. */
+    signature: string;
+}
+export interface TxMicroblockHeader {
+    /** Hex string */
+    buffer: string;
+    version: number;
+    sequence: number;
+    /** Hex string */
+    prev_block: string;
+    /** Hex string */
+    tx_merkle_root: string;
+    /** Hex string */
+    signature: string;
+}
+export declare enum TxPublicKeyEncoding {
+    Compressed = 0,
+    Uncompressed = 1
+}
+export interface DecodedStacksAddress {
+    address_version: number;
+    /** Hex-encoded string of the hash160 signer address. */
+    address_hash_bytes: string;
+    address: string;
+}
+export declare enum TransactionVersion {
+    Mainnet = 0,
+    Testnet = 128
+}
+export declare enum AnchorModeID {
+    /** The transaction MUST be included in an anchored block. */
+    OnChainOnly = 1,
+    /** The transaction MUST be included in a microblock. */
+    OffChainOnly = 2,
+    /** The leader can choose where to include the transaction. */
+    Any = 3
+}
+export declare enum PostConditionModeID {
+    /** This transaction may affect other assets not listed in the post-conditions. */
+    Allow = 1,
+    /** This transaction may NOT affect other assets besides those listed in the post-conditions. */
+    Deny = 2
+}
+export interface ClarityValueCommon {
+    /** Clarity repr value */
+    repr: string;
+    /** Hex encoded string of the serialized Clarity value */
+    hex: string;
+}
+export interface ClarityValueAbstract extends ClarityValueCommon {
+    type_id: number;
+}
+export declare enum ClarityTypeID {
+    Int = 0,
+    UInt = 1,
+    Buffer = 2,
+    BoolTrue = 3,
+    BoolFalse = 4,
+    PrincipalStandard = 5,
+    PrincipalContract = 6,
+    ResponseOk = 7,
+    ResponseError = 8,
+    OptionalNone = 9,
+    OptionalSome = 10,
+    List = 11,
+    Tuple = 12,
+    StringAscii = 13,
+    StringUtf8 = 14
+}
+export interface ClarityValueInt extends ClarityValueCommon {
+    type_id: ClarityTypeID.Int;
+    /** String-quoted signed integer */
+    value: string;
+}
+export interface ClarityValueUInt extends ClarityValueCommon {
+    type_id: ClarityTypeID.UInt;
+    /** String-quoted unsigned integer */
+    value: string;
+}
+export interface ClarityValueBoolTrue extends ClarityValueCommon {
+    type_id: ClarityTypeID.BoolTrue;
+    value: true;
+}
+export interface ClarityValueBoolFalse extends ClarityValueCommon {
+    type_id: ClarityTypeID.BoolFalse;
+    value: false;
+}
+export interface ClarityValueBuffer extends ClarityValueCommon {
+    type_id: ClarityTypeID.Buffer;
+    /** Hex string */
+    buffer: string;
+}
+export interface ClarityValueList<T extends ClarityValue = ClarityValue> extends ClarityValueCommon {
+    type_id: ClarityTypeID.List;
+    list: T[];
+}
+export interface ClarityValueStringAscii extends ClarityValueCommon {
+    type_id: ClarityTypeID.StringAscii;
+    data: string;
+}
+export interface ClarityValueStringUtf8 extends ClarityValueCommon {
+    type_id: ClarityTypeID.StringUtf8;
+    data: string;
+}
+export interface ClarityValuePrincipalStandard extends ClarityValueCommon {
+    type_id: ClarityTypeID.PrincipalStandard;
+    address: string;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+}
+export interface ClarityValuePrincipalContract extends ClarityValueCommon {
+    type_id: ClarityTypeID.PrincipalContract;
+    address: string;
+    address_version: number;
+    /** Hex string */
+    address_hash_bytes: string;
+    contract_name: string;
+}
+export declare type ClarityTupleData<T extends ClarityValue = ClarityValue> = {
+    [key: string]: T;
+};
+export interface ClarityValueTuple<T extends ClarityTupleData = ClarityTupleData> extends ClarityValueCommon {
+    type_id: ClarityTypeID.Tuple;
+    data: T;
+}
+export interface ClarityValueOptionalSome<T extends ClarityValue = ClarityValue> extends ClarityValueCommon {
+    type_id: ClarityTypeID.OptionalSome;
+    value: T;
+}
+export interface ClarityValueOptionalNone extends ClarityValueCommon {
+    type_id: ClarityTypeID.OptionalNone;
+}
+export interface ClarityValueResponseOk<T extends ClarityValue = ClarityValue> extends ClarityValueCommon {
+    type_id: ClarityTypeID.ResponseOk;
+    value: T;
+}
+export interface ClarityValueResponseError<T extends ClarityValue = ClarityValue> extends ClarityValueCommon {
+    type_id: ClarityTypeID.ResponseError;
+    value: T;
+}
+export declare type ClarityValue = ClarityValueInt | ClarityValueUInt | ClarityValueBoolTrue | ClarityValueBoolFalse | ClarityValueBuffer | ClarityValueList | ClarityValueStringAscii | ClarityValueStringUtf8 | ClarityValuePrincipalStandard | ClarityValuePrincipalContract | ClarityValueTuple | ClarityValueOptionalSome | ClarityValueOptionalNone | ClarityValueResponseOk | ClarityValueResponseError;
+export declare type ClarityValueOptional<T extends ClarityValue = ClarityValue> = ClarityValueOptionalSome<T> | ClarityValueOptionalNone;
+export declare type ClarityValueBool = ClarityValueBoolTrue | ClarityValueBoolFalse;
+export declare type ClarityValueResponse<TOk extends ClarityValue = ClarityValue, TError extends ClarityValue = ClarityValue> = ClarityValueResponseOk<TOk> | ClarityValueResponseError<TError>;
+/**
+ * Type for commonly used `(optional bool)`
+ */
+export declare type ClarityValueOptionalBool = ClarityValueOptional<ClarityValueBool>;
+/**
+ * Type for commonly used `(optional uint)`
+ */
+export declare type ClarityValueOptionalUInt = ClarityValueOptional<ClarityValueUInt>;
+export interface DecodedNakamotoBlockResult {
+    /** Hex encoded string of the block ID (index block hash) */
+    block_id: string;
+    header: NakamotoBlockHeader;
+    txs: DecodedTxResult[];
+}
+export interface NakamotoBlockHeader {
+    version: number;
+    /** String-quoted unsigned integer - total blocks preceding this one */
+    chain_length: string;
+    /** String-quoted unsigned integer - total BTC spent in sortition */
+    burn_spent: string;
+    /** Hex string (20 bytes) - consensus hash of the burnchain block */
+    consensus_hash: string;
+    /** Hex string (32 bytes) - parent block ID */
+    parent_block_id: string;
+    /** Hex string (32 bytes) - merkle root of transactions */
+    tx_merkle_root: string;
+    /** Hex string (32 bytes) - MARF trie root hash */
+    state_index_root: string;
+    /** String-quoted unsigned integer - Unix timestamp */
+    timestamp: string;
+    /** Hex string (65 bytes) - miner's ECDSA signature */
+    miner_signature: string;
+    /** Array of hex strings (65 bytes each) - signer signatures */
+    signer_signature: string[];
+    /** PoX treatment bitvec */
+    pox_treatment: BitVec;
+    /** Hex string (32 bytes) - computed block hash */
+    block_hash: string;
+    /** Hex string (32 bytes) - computed index block hash */
+    index_block_hash: string;
+}
+export interface BitVec {
+    /** Number of bits */
+    len: number;
+    /** Hex encoded data bytes */
+    data: string;
+    /** Array of boolean values for each bit */
+    bits: boolean[];
+}
+export interface DecodedStacksBlockResult {
+    /** Hex encoded string of the block hash */
+    block_hash: string;
+    header: StacksBlockHeader;
+    txs: DecodedTxResult[];
+}
+export interface StacksBlockHeader {
+    version: number;
+    total_work: StacksWorkScore;
+    /** Hex string (80 bytes) - VRF proof */
+    proof: string;
+    /** Hex string (32 bytes) - parent block hash */
+    parent_block: string;
+    /** Hex string (32 bytes) - parent microblock hash */
+    parent_microblock: string;
+    /** Parent microblock sequence number */
+    parent_microblock_sequence: number;
+    /** Hex string (32 bytes) - merkle root of transactions */
+    tx_merkle_root: string;
+    /** Hex string (32 bytes) - MARF trie root hash */
+    state_index_root: string;
+    /** Hex string (20 bytes) - hash160 of microblock public key */
+    microblock_pubkey_hash: string;
+    /** Hex string (32 bytes) - computed block hash */
+    block_hash: string;
+}
+export interface StacksWorkScore {
+    /** String-quoted unsigned integer - burn amount */
+    burn: string;
+    /** String-quoted unsigned integer - work score */
+    work: string;
+}

package/index.js

@@ -0,0 +1,182 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+const bindings = require("./loader");
+__exportStar(require("./loader"), exports);
+exports.StacksNativeEncodingBindings = bindings;
+exports.default = exports.StacksNativeEncodingBindings;
+var PostConditionAssetInfoID;
+(function (PostConditionAssetInfoID) {
+    PostConditionAssetInfoID[PostConditionAssetInfoID["STX"] = 0] = "STX";
+    PostConditionAssetInfoID[PostConditionAssetInfoID["FungibleAsset"] = 1] = "FungibleAsset";
+    PostConditionAssetInfoID[PostConditionAssetInfoID["NonfungibleAsset"] = 2] = "NonfungibleAsset";
+})(PostConditionAssetInfoID = exports.PostConditionAssetInfoID || (exports.PostConditionAssetInfoID = {}));
+var PostConditionNonfungibleConditionCodeID;
+(function (PostConditionNonfungibleConditionCodeID) {
+    PostConditionNonfungibleConditionCodeID[PostConditionNonfungibleConditionCodeID["Sent"] = 16] = "Sent";
+    PostConditionNonfungibleConditionCodeID[PostConditionNonfungibleConditionCodeID["NotSent"] = 17] = "NotSent";
+})(PostConditionNonfungibleConditionCodeID = exports.PostConditionNonfungibleConditionCodeID || (exports.PostConditionNonfungibleConditionCodeID = {}));
+var PostConditionNonFungibleConditionName;
+(function (PostConditionNonFungibleConditionName) {
+    PostConditionNonFungibleConditionName["Sent"] = "sent";
+    PostConditionNonFungibleConditionName["NotSent"] = "not_sent";
+})(PostConditionNonFungibleConditionName = exports.PostConditionNonFungibleConditionName || (exports.PostConditionNonFungibleConditionName = {}));
+var PostConditionFungibleConditionCodeID;
+(function (PostConditionFungibleConditionCodeID) {
+    PostConditionFungibleConditionCodeID[PostConditionFungibleConditionCodeID["SentEq"] = 1] = "SentEq";
+    PostConditionFungibleConditionCodeID[PostConditionFungibleConditionCodeID["SentGt"] = 2] = "SentGt";
+    PostConditionFungibleConditionCodeID[PostConditionFungibleConditionCodeID["SentGe"] = 3] = "SentGe";
+    PostConditionFungibleConditionCodeID[PostConditionFungibleConditionCodeID["SentLt"] = 4] = "SentLt";
+    PostConditionFungibleConditionCodeID[PostConditionFungibleConditionCodeID["SentLe"] = 5] = "SentLe";
+})(PostConditionFungibleConditionCodeID = exports.PostConditionFungibleConditionCodeID || (exports.PostConditionFungibleConditionCodeID = {}));
+var PostConditionFungibleConditionCodeName;
+(function (PostConditionFungibleConditionCodeName) {
+    PostConditionFungibleConditionCodeName["SentEq"] = "sent_equal_to";
+    PostConditionFungibleConditionCodeName["SentGt"] = "sent_greater_than";
+    PostConditionFungibleConditionCodeName["SentGe"] = "sent_greater_than_or_equal_to";
+    PostConditionFungibleConditionCodeName["SentLt"] = "sent_less_than";
+    PostConditionFungibleConditionCodeName["SentLe"] = "sent_less_than_or_equal_to";
+})(PostConditionFungibleConditionCodeName = exports.PostConditionFungibleConditionCodeName || (exports.PostConditionFungibleConditionCodeName = {}));
+var PostConditionPrincipalTypeID;
+(function (PostConditionPrincipalTypeID) {
+    /** A STX post-condition, which pertains to the origin account's STX. */
+    PostConditionPrincipalTypeID[PostConditionPrincipalTypeID["Origin"] = 1] = "Origin";
+    /** A Fungible token post-condition, which pertains to one of the origin account's fungible tokens. */
+    PostConditionPrincipalTypeID[PostConditionPrincipalTypeID["Standard"] = 2] = "Standard";
+    /** A Non-fungible token post-condition, which pertains to one of the origin account's non-fungible tokens. */
+    PostConditionPrincipalTypeID[PostConditionPrincipalTypeID["Contract"] = 3] = "Contract";
+})(PostConditionPrincipalTypeID = exports.PostConditionPrincipalTypeID || (exports.PostConditionPrincipalTypeID = {}));
+var PrincipalTypeID;
+(function (PrincipalTypeID) {
+    PrincipalTypeID[PrincipalTypeID["Standard"] = 5] = "Standard";
+    PrincipalTypeID[PrincipalTypeID["Contract"] = 6] = "Contract";
+})(PrincipalTypeID = exports.PrincipalTypeID || (exports.PrincipalTypeID = {}));
+var TenureChangeCause;
+(function (TenureChangeCause) {
+    /** A valid winning block-commit */
+    TenureChangeCause[TenureChangeCause["BlockFound"] = 0] = "BlockFound";
+    /** The next burnchain block is taking too long, so extend the runtime budget */
+    TenureChangeCause[TenureChangeCause["Extended"] = 1] = "Extended";
+    /** SIP-034: extend specific dimensions - runtime */
+    TenureChangeCause[TenureChangeCause["ExtendedRuntime"] = 2] = "ExtendedRuntime";
+    /** SIP-034: extend specific dimensions - read count */
+    TenureChangeCause[TenureChangeCause["ExtendedReadCount"] = 3] = "ExtendedReadCount";
+    /** SIP-034: extend specific dimensions - read length */
+    TenureChangeCause[TenureChangeCause["ExtendedReadLength"] = 4] = "ExtendedReadLength";
+    /** SIP-034: extend specific dimensions - write count */
+    TenureChangeCause[TenureChangeCause["ExtendedWriteCount"] = 5] = "ExtendedWriteCount";
+    /** SIP-034: extend specific dimensions - write length */
+    TenureChangeCause[TenureChangeCause["ExtendedWriteLength"] = 6] = "ExtendedWriteLength";
+})(TenureChangeCause = exports.TenureChangeCause || (exports.TenureChangeCause = {}));
+var TxPayloadTypeID;
+(function (TxPayloadTypeID) {
+    TxPayloadTypeID[TxPayloadTypeID["TokenTransfer"] = 0] = "TokenTransfer";
+    TxPayloadTypeID[TxPayloadTypeID["SmartContract"] = 1] = "SmartContract";
+    TxPayloadTypeID[TxPayloadTypeID["ContractCall"] = 2] = "ContractCall";
+    TxPayloadTypeID[TxPayloadTypeID["PoisonMicroblock"] = 3] = "PoisonMicroblock";
+    TxPayloadTypeID[TxPayloadTypeID["Coinbase"] = 4] = "Coinbase";
+    TxPayloadTypeID[TxPayloadTypeID["CoinbaseToAltRecipient"] = 5] = "CoinbaseToAltRecipient";
+    TxPayloadTypeID[TxPayloadTypeID["VersionedSmartContract"] = 6] = "VersionedSmartContract";
+    TxPayloadTypeID[TxPayloadTypeID["TenureChange"] = 7] = "TenureChange";
+    TxPayloadTypeID[TxPayloadTypeID["NakamotoCoinbase"] = 8] = "NakamotoCoinbase";
+})(TxPayloadTypeID = exports.TxPayloadTypeID || (exports.TxPayloadTypeID = {}));
+var PostConditionAuthFlag;
+(function (PostConditionAuthFlag) {
+    PostConditionAuthFlag[PostConditionAuthFlag["Standard"] = 4] = "Standard";
+    PostConditionAuthFlag[PostConditionAuthFlag["Sponsored"] = 5] = "Sponsored";
+})(PostConditionAuthFlag = exports.PostConditionAuthFlag || (exports.PostConditionAuthFlag = {}));
+var TxSpendingConditionSingleSigHashMode;
+(function (TxSpendingConditionSingleSigHashMode) {
+    /** hash160(public-key), same as bitcoin's p2pkh */
+    TxSpendingConditionSingleSigHashMode[TxSpendingConditionSingleSigHashMode["P2PKH"] = 0] = "P2PKH";
+    /** hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh */
+    TxSpendingConditionSingleSigHashMode[TxSpendingConditionSingleSigHashMode["P2WPKH"] = 2] = "P2WPKH";
+})(TxSpendingConditionSingleSigHashMode = exports.TxSpendingConditionSingleSigHashMode || (exports.TxSpendingConditionSingleSigHashMode = {}));
+var TxSpendingConditionMultiSigHashMode;
+(function (TxSpendingConditionMultiSigHashMode) {
+    /** hash160(multisig-redeem-script), same as bitcoin's multisig p2sh */
+    TxSpendingConditionMultiSigHashMode[TxSpendingConditionMultiSigHashMode["P2SH"] = 1] = "P2SH";
+    /** hash160(multisig-redeem-script), same as bitcoin's multisig p2sh (non-sequential signing) */
+    TxSpendingConditionMultiSigHashMode[TxSpendingConditionMultiSigHashMode["P2SHNonSequential"] = 5] = "P2SHNonSequential";
+    /** hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh */
+    TxSpendingConditionMultiSigHashMode[TxSpendingConditionMultiSigHashMode["P2WSH"] = 3] = "P2WSH";
+    /** hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh (non-sequential signing) */
+    TxSpendingConditionMultiSigHashMode[TxSpendingConditionMultiSigHashMode["P2WSHNonSequential"] = 7] = "P2WSHNonSequential";
+})(TxSpendingConditionMultiSigHashMode = exports.TxSpendingConditionMultiSigHashMode || (exports.TxSpendingConditionMultiSigHashMode = {}));
+var ClarityVersion;
+(function (ClarityVersion) {
+    ClarityVersion[ClarityVersion["Clarity1"] = 1] = "Clarity1";
+    ClarityVersion[ClarityVersion["Clarity2"] = 2] = "Clarity2";
+    ClarityVersion[ClarityVersion["Clarity3"] = 3] = "Clarity3";
+    ClarityVersion[ClarityVersion["Clarity4"] = 4] = "Clarity4";
+    ClarityVersion[ClarityVersion["Clarity5"] = 5] = "Clarity5";
+})(ClarityVersion = exports.ClarityVersion || (exports.ClarityVersion = {}));
+var TxAuthFieldTypeID;
+(function (TxAuthFieldTypeID) {
+    /** The next 33 bytes are a compressed secp256k1 public key. If the field ID is 0x00, the key will be loaded as a compressed secp256k1 public key. */
+    TxAuthFieldTypeID[TxAuthFieldTypeID["PublicKeyCompressed"] = 0] = "PublicKeyCompressed";
+    /** The next 33 bytes are a compressed secp256k1 public key. If it is 0x01, then the key will be loaded as an uncompressed secp256k1 public key. */
+    TxAuthFieldTypeID[TxAuthFieldTypeID["PublicKeyUncompressed"] = 1] = "PublicKeyUncompressed";
+    /** The next 65 bytes are a recoverable secp256k1 ECDSA signature. If the field ID is 0x02, then the recovered public key will be loaded as a compressed public key. */
+    TxAuthFieldTypeID[TxAuthFieldTypeID["SignatureCompressed"] = 2] = "SignatureCompressed";
+    /** The next 65 bytes are a recoverable secp256k1 ECDSA signature. If it is 0x03, then the recovered public key will be loaded as an uncompressed public key. */
+    TxAuthFieldTypeID[TxAuthFieldTypeID["SignatureUncompressed"] = 3] = "SignatureUncompressed";
+})(TxAuthFieldTypeID = exports.TxAuthFieldTypeID || (exports.TxAuthFieldTypeID = {}));
+var TxPublicKeyEncoding;
+(function (TxPublicKeyEncoding) {
+    TxPublicKeyEncoding[TxPublicKeyEncoding["Compressed"] = 0] = "Compressed";
+    TxPublicKeyEncoding[TxPublicKeyEncoding["Uncompressed"] = 1] = "Uncompressed";
+})(TxPublicKeyEncoding = exports.TxPublicKeyEncoding || (exports.TxPublicKeyEncoding = {}));
+var TransactionVersion;
+(function (TransactionVersion) {
+    TransactionVersion[TransactionVersion["Mainnet"] = 0] = "Mainnet";
+    TransactionVersion[TransactionVersion["Testnet"] = 128] = "Testnet";
+})(TransactionVersion = exports.TransactionVersion || (exports.TransactionVersion = {}));
+var AnchorModeID;
+(function (AnchorModeID) {
+    /** The transaction MUST be included in an anchored block. */
+    AnchorModeID[AnchorModeID["OnChainOnly"] = 1] = "OnChainOnly";
+    /** The transaction MUST be included in a microblock. */
+    AnchorModeID[AnchorModeID["OffChainOnly"] = 2] = "OffChainOnly";
+    /** The leader can choose where to include the transaction. */
+    AnchorModeID[AnchorModeID["Any"] = 3] = "Any";
+})(AnchorModeID = exports.AnchorModeID || (exports.AnchorModeID = {}));
+var PostConditionModeID;
+(function (PostConditionModeID) {
+    /** This transaction may affect other assets not listed in the post-conditions. */
+    PostConditionModeID[PostConditionModeID["Allow"] = 1] = "Allow";
+    /** This transaction may NOT affect other assets besides those listed in the post-conditions. */
+    PostConditionModeID[PostConditionModeID["Deny"] = 2] = "Deny";
+})(PostConditionModeID = exports.PostConditionModeID || (exports.PostConditionModeID = {}));
+var ClarityTypeID;
+(function (ClarityTypeID) {
+    ClarityTypeID[ClarityTypeID["Int"] = 0] = "Int";
+    ClarityTypeID[ClarityTypeID["UInt"] = 1] = "UInt";
+    ClarityTypeID[ClarityTypeID["Buffer"] = 2] = "Buffer";
+    ClarityTypeID[ClarityTypeID["BoolTrue"] = 3] = "BoolTrue";
+    ClarityTypeID[ClarityTypeID["BoolFalse"] = 4] = "BoolFalse";
+    ClarityTypeID[ClarityTypeID["PrincipalStandard"] = 5] = "PrincipalStandard";
+    ClarityTypeID[ClarityTypeID["PrincipalContract"] = 6] = "PrincipalContract";
+    ClarityTypeID[ClarityTypeID["ResponseOk"] = 7] = "ResponseOk";
+    ClarityTypeID[ClarityTypeID["ResponseError"] = 8] = "ResponseError";
+    ClarityTypeID[ClarityTypeID["OptionalNone"] = 9] = "OptionalNone";
+    ClarityTypeID[ClarityTypeID["OptionalSome"] = 10] = "OptionalSome";
+    ClarityTypeID[ClarityTypeID["List"] = 11] = "List";
+    ClarityTypeID[ClarityTypeID["Tuple"] = 12] = "Tuple";
+    ClarityTypeID[ClarityTypeID["StringAscii"] = 13] = "StringAscii";
+    ClarityTypeID[ClarityTypeID["StringUtf8"] = 14] = "StringUtf8";
+})(ClarityTypeID = exports.ClarityTypeID || (exports.ClarityTypeID = {}));

package/loader.d.ts

@@ -0,0 +1,69 @@
+import type { DecodedPostConditionsResult, DecodedTxResult, DecodedNakamotoBlockResult, DecodedStacksBlockResult, ClarityValue, ClarityValueAbstract } from ".";
+
+export function getVersion(): string;
+
+export function decodeTransaction(arg: string | Buffer): DecodedTxResult;
+
+/**
+ * Decode a Nakamoto block (Stacks 3.x+).
+ * The input should be the raw binary block data as returned by /v3/blocks/{block_id} endpoint.
+ * @param arg - Hex string or Buffer containing the raw block data
+ */
+export function decodeNakamotoBlock(arg: string | Buffer): DecodedNakamotoBlockResult;
+
+/**
+ * Decode a Stacks 2.x block.
+ * The input should be the raw binary block data as returned by /v2/blocks/{block_id} endpoint.
+ * @param arg - Hex string or Buffer containing the raw block data
+ */
+export function decodeStacksBlock(arg: string | Buffer): DecodedStacksBlockResult;
+
+export function decodeClarityValueToRepr(arg: string | Buffer): string;
+
+export function decodeClarityValueToTypeName(arg: string | Buffer): string;
+
+export function decodeClarityValue<T extends ClarityValue = ClarityValue>(arg: string | Buffer): T;
+
+/**
+ * 
+ * @param arg 
+ * @param deep - If not true, then the deserialized objects will only contain the 
+ * properties `hex, repr, type, type_id`. And nested types like Tuple, List, Response, etc will
+ * not contain decoded children.
+ * TODO: fix the clarity result type definition to be more accurate.
+ */
+export function decodeClarityValueList(arg: string | Buffer, deep?: false | undefined): ClarityValueAbstract[];
+
+/**
+ * 
+ * @param arg 
+ * @param deep - If not true, then the deserialized objects will only contain the 
+ * properties `hex, repr, type, type_id`. And nested types like Tuple, List, Response, etc will
+ * not contain decoded children.
+ * TODO: fix the clarity result type definition to be more accurate.
+ */
+export function decodeClarityValueList(arg: string | Buffer, deep: true): ClarityValue[];
+
+export function decodePostConditions(arg: string | Buffer): DecodedPostConditionsResult;
+
+export function stacksToBitcoinAddress(stackAddress: string): string;
+
+export function bitcoinToStacksAddress(bitcoinAddress: string): string;
+
+export function isValidStacksAddress(address: string): boolean;
+
+export function decodeStacksAddress(address: string): [version: number, hash160: string];
+
+export function decodeClarityValueToPrincipal(clarityValue: string | Buffer) : string;
+
+export function stacksAddressFromParts(version: number, hash160: string | Buffer): string;
+
+export function memoToString(memo: string | Buffer): string;
+
+export function startProfiler(): string;
+
+export function stopProfiler(): Buffer;
+
+export function createProfiler(): () => Buffer;
+
+export function perfTestC32Encode(): Buffer;

package/loader.js

@@ -0,0 +1,7 @@
+let targetName = `${process.platform}-${process.arch}`;
+if (process.platform === 'linux') {
+    const libc = require('detect-libc').familySync() || 'glibc';
+    targetName += `-${libc}`;
+}
+module.exports = require(`./native/${targetName}.node`);
+

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@stacks/codec",
+  "version": "1.4.0",
+  "description": "Encoding & decoding functions for the Stacks blockchain exposed as a fast native Node.js addon",
+  "main": "index.js",
+  "scripts": {
+    "build:cargo": "node build.js",
+    "build:ts": "tsc",
+    "build": "npm run build:ts",
+    "build:dev": "npm run build:ts && npm run build:cargo -- dev",
+    "test:cargo": "cargo test",
+    "test:js": "jest",
+    "test": "npm run test:js",
+    "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"
+  },
+  "prettier": "@stacks/prettier-config",
+  "devDependencies": {
+    "@stacks/prettier-config": "^0.0.10",
+    "@types/jest": "^27.4.1",
+    "cargo-cp-artifact": "^0.1.9",
+    "jest": "^27.5.1",
+    "ts-jest": "^27.1.4",
+    "typescript": "^4.6.3"
+  },
+  "dependencies": {
+    "@types/node": "^16.11.26",
+    "detect-libc": "^2.0.1"
+  },
+  "files": [
+    "README.md",
+    "native/**/*",
+    "index.js",
+    "index.d.ts",
+    "loader.js",
+    "loader.d.ts"
+  ],
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/tests"
+    ]
+  }
+}