feat!: Make serialize methods return hex-encoded strings, instead of …

…bytes

.github/.husky/commitlint.json

@@ -8,6 +8,8 @@
     "header-max-length": [0, "always"],
     "scope-max-length": [0, "always"],
     "subject-max-length": [0, "always"],
-    "type-max-length": [0, "always"]
+    "type-max-length": [0, "always"],
+
+    "subject-case": [0, "always", "sentence-case"]
   }
 }

.github/MIGRATION.md

@@ -6,6 +6,8 @@
   - [StacksNodeApi](#stacksnodeapi)
   - [StacksNetwork to StacksNodeApi](#stacksnetwork-to-stacksnodeapi)
   - [Clarity Representation](#clarity-representation)
+  - [`serialize` methods](#serialize-methods)
+  - [Asset Helper Methods](#asset-helper-methods)
 - [Stacks.js (\<=4.x.x) → (5.x.x)](#stacksjs-4xx--5xx)
   - [Breaking Changes](#breaking-changes-1)
     - [Buffer to Uint8Array](#buffer-to-uint8array)
@@ -26,6 +28,8 @@
 
 - The `@stacks/network` `new StacksNetwork()` objects were removed. Instead `@stacks/network` now exports the objects `STACKS_MAINNET`, `STACKS_TESNET`, and `STACKS_DEVNET`, which are static (and shouldn't be changed for most use-cases). [Read more...](#stacks-network)
 - The `ClarityType` enum was replaced by a readable version. The previous (wire format compatible) enum is still available as `ClarityWireType`. [Read more...](#clarity-representation)
+- The `serializeXyz` methods were changed to return `string` (hex-encoded) instead of `Uint8Array`. Compatible `serializeXzyBytes` methods were added to ease the migration. [Read more...](#serialize-methods)
+- The `AssetInfo` type was renamed to `Asset` for accuracy. The `Asset` helper methods were also renamed to to remove the `Info` suffix. [Read more...](#asset-helper-methods)
 
 ### Stacks Network
 
@@ -144,6 +148,42 @@ For `bigint` values, the type of the `value` property is a now `string`, for bet
 }
 ```
 
+### `serialize` methods
+
+Existing methods now use hex-encoded strings instead of `Uint8Array`s.
+For easiery migrating, renaming the following methods is possible to keep the previous behavior:
+
+- `serializeCV` → `serializeCVBytes`
+- `serializeAddress` → `serializeAddressBytes`
+- `deserializeAddress` → `deserializeAddressBytes`
+- `serializeLPList` → `serializeLPListBytes`
+- `deserializeLPList` → `deserializeLPListBytes`
+- `serializeLPString` → `serializeLPStringBytes`
+- `deserializeLPString` → `deserializeLPStringBytes`
+- `serializePayload` → `serializePayloadBytes`
+- `deserializePayload` → `deserializePayloadBytes`
+- `serializePublicKey` → `serializePublicKeyBytes`
+- `deserializePublicKey` → `deserializePublicKeyBytes`
+- `serializeStacksMessage` → `serializeStacksMessageBytes`
+- `deserializeStacksMessage` → `deserializeStacksMessageBytes`
+- `serializeMemoString` → `serializeMemoStringBytes`
+- `deserializeMemoString` → `deserializeMemoStringBytes`
+- `serializeTransactionAuthField` → `serializeTransactionAuthFieldBytes`
+- `deserializeTransactionAuthField` → `deserializeTransactionAuthFieldBytes`
+- `serializeMessageSignature` → `serializeMessageSignatureBytes`
+- `deserializeMessageSignature` → `deserializeMessageSignatureBytes`
+- `serializePostCondition` → `serializePostConditionBytes`
+- `deserializePostCondition` → `deserializePostConditionBytes`
+
+### Asset Helper Methods
+
+The following interfaces and methods were renamed:
+
+- `AssetInfo` → `Asset`
+- `StacksMessageType.AssetInfo` → `StacksMessageType.Asset`
+- `createAssetInfo` → `createAsset`
+- `parseAssetInfoString` → `parseAssetString`
+
 ## Stacks.js (&lt;=4.x.x) → (5.x.x)
 
 ### Breaking Changes

packages/bns/src/index.ts

@@ -23,7 +23,7 @@ import {
   makeRandomPrivKey,
   makeUnsignedContractCall,
   noneCV,
-  parseAssetInfoString,
+  parseAssetString,
   publicKeyToAddress,
   someCV,
   standardPrincipalCV,
@@ -705,7 +705,7 @@ export async function buildTransferNameTx({
   const postConditionSender = createNonFungiblePostCondition(
     publicKeyToAddress(getAddressVersion(network), publicKey),
     NonFungibleConditionCode.Sends,
-    parseAssetInfoString(`${getBnsContractAddress(network)}.bns::names`),
+    parseAssetString(`${getBnsContractAddress(network)}.bns::names`),
     tupleCV({
       name: bufferCVFromString(name),
       namespace: bufferCVFromString(namespace),
@@ -714,7 +714,7 @@ export async function buildTransferNameTx({
   const postConditionReceiver = createNonFungiblePostCondition(
     newOwnerAddress,
     NonFungibleConditionCode.DoesNotSend,
-    parseAssetInfoString(`${getBnsContractAddress(network)}.bns::names`),
+    parseAssetString(`${getBnsContractAddress(network)}.bns::names`),
     tupleCV({
       name: bufferCVFromString(name),
       namespace: bufferCVFromString(namespace),

packages/bns/tests/bns.test.ts

@@ -12,7 +12,7 @@ import {
   falseCV,
   hash160,
   noneCV,
-  parseAssetInfoString,
+  parseAssetString,
   publicKeyToAddress,
   responseErrorCV,
   responseOkCV,
@@ -704,7 +704,7 @@ test('transferName', async () => {
   const nameTransferPostConditionOne = createNonFungiblePostCondition(
     publicKeyToAddress(getAddressVersion(network), publicKey),
     NonFungibleConditionCode.Sends,
-    parseAssetInfoString(`${getBnsContractAddress(network)}.bns::names`),
+    parseAssetString(`${getBnsContractAddress(network)}.bns::names`),
     tupleCV({
       name: bufferCVFromString(name),
       namespace: bufferCVFromString(namespace),
@@ -713,7 +713,7 @@ test('transferName', async () => {
   const nameTransferPostConditionTwo = createNonFungiblePostCondition(
     newOwnerAddress,
     NonFungibleConditionCode.DoesNotSend,
-    parseAssetInfoString(`${getBnsContractAddress(network)}.bns::names`),
+    parseAssetString(`${getBnsContractAddress(network)}.bns::names`),
     tupleCV({
       name: bufferCVFromString(name),
       namespace: bufferCVFromString(namespace),
@@ -772,7 +772,7 @@ test('transferName optionalArguments', async () => {
   const nameTransferPostConditionOne = createNonFungiblePostCondition(
     publicKeyToAddress(getAddressVersion(network), publicKey),
     NonFungibleConditionCode.Sends,
-    parseAssetInfoString(`${getBnsContractAddress(network)}.bns::names`),
+    parseAssetString(`${getBnsContractAddress(network)}.bns::names`),
     tupleCV({
       name: bufferCVFromString(name),
       namespace: bufferCVFromString(namespace),
@@ -781,7 +781,7 @@ test('transferName optionalArguments', async () => {
   const nameTransferPostConditionTwo = createNonFungiblePostCondition(
     newOwnerAddress,
     NonFungibleConditionCode.DoesNotSend,
-    parseAssetInfoString(`${getBnsContractAddress(network)}.bns::names`),
+    parseAssetString(`${getBnsContractAddress(network)}.bns::names`),
     tupleCV({
       name: bufferCVFromString(name),
       namespace: bufferCVFromString(namespace),

packages/cli/src/cli.ts

@@ -783,7 +783,7 @@ async function contractDeploy(network: CLINetworkAdapter, args: string[]): Promi
 
   if (estimateOnly) {
     return estimateTransaction({
-      payload: bytesToHex(serializePayload(tx.payload)),
+      payload: serializePayload(tx.payload),
       estimatedLength: estimateTransactionByteLength(tx),
     }).then(costs => costs[1].fee.toString(10));
   }
@@ -870,7 +870,7 @@ async function contractFunctionCall(network: CLINetworkAdapter, args: string[]):
 
       if (estimateOnly) {
         return estimateTransaction({
-          payload: bytesToHex(serializePayload(tx.payload)),
+          payload: serializePayload(tx.payload),
           estimatedLength: estimateTransactionByteLength(tx),
         }).then(costs => costs[1].fee.toString(10));
       }

packages/transactions/README.md

@@ -425,7 +425,7 @@ const contractSTXPostCondition = makeContractSTXPostCondition(
 ```typescript
 import {
   FungibleConditionCode,
-  createAssetInfo,
+  createAsset,
   makeStandardFungiblePostCondition,
 } from '@stacks/transactions';
 
@@ -436,13 +436,13 @@ const postConditionAmount = 12345n;
 const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ';
 const assetContractName = 'test-asset-contract';
 const assetName = 'test-token';
-const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName, assetName);
+const fungibleAsset = createAsset(assetAddress, assetContractName, assetName);
 
 const standardFungiblePostCondition = makeStandardFungiblePostCondition(
   postConditionAddress,
   postConditionCode,
   postConditionAmount,
-  fungibleAssetInfo
+  fungibleAsset
 );
 
 // With a contract principal
@@ -451,14 +451,14 @@ const contractName = 'test-contract';
 const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ';
 const assetContractName = 'test-asset-contract';
 const assetName = 'test-token';
-const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName, assetName);
+const fungibleAsset = createAsset(assetAddress, assetContractName, assetName);
 
 const contractFungiblePostCondition = makeContractFungiblePostCondition(
   contractAddress,
   contractName,
   postConditionCode,
   postConditionAmount,
-  fungibleAssetInfo
+  fungibleAsset
 );
 ```
 
@@ -473,7 +473,7 @@ const contractFungiblePostCondition = makeContractFungiblePostCondition(
 ```typescript
 import {
   NonFungibleConditionCode,
-  createAssetInfo,
+  createAsset,
   makeStandardNonFungiblePostCondition,
   makeContractNonFungiblePostCondition,
   bufferCVFromString,
@@ -486,12 +486,12 @@ const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ';
 const assetContractName = 'test-asset-contract';
 const assetName = 'test-asset';
 const assetId = bufferCVFromString('test-token-asset-id');
-const nonFungibleAssetInfo = createAssetInfo(assetAddress, assetContractName, assetName);
+const nonFungibleAsset = createAsset(assetAddress, assetContractName, assetName);
 
 const standardNonFungiblePostCondition = makeStandardNonFungiblePostCondition(
   postConditionAddress,
   postConditionCode,
-  nonFungibleAssetInfo,
+  nonFungibleAsset,
   assetId
 );
 
@@ -503,7 +503,7 @@ const contractNonFungiblePostCondition = makeContractNonFungiblePostCondition(
   contractAddress,
   contractName,
   postConditionCode,
-  nonFungibleAssetInfo,
+  nonFungibleAsset,
   assetId
 );
 ```

packages/transactions/src/authorization.ts

@@ -31,15 +31,15 @@ import {
 } from './keys';
 import {
   deserializeMessageSignature,
-  serializeMessageSignature,
+  serializeMessageSignatureBytes,
   TransactionAuthField,
 } from './signature';
 import {
   addressFromPublicKeys,
   createEmptyAddress,
   createLPList,
-  deserializeLPList,
-  serializeLPList,
+  deserializeLPListBytes,
+  serializeLPListBytes,
 } from './types';
 import { cloneDeep, leftPadHex, txidFromData } from './utils';
 
@@ -205,7 +205,7 @@ export function serializeSingleSigSpendingCondition(
     intToBytes(condition.nonce, false, 8),
     intToBytes(condition.fee, false, 8),
     condition.keyEncoding as number,
-    serializeMessageSignature(condition.signature),
+    serializeMessageSignatureBytes(condition.signature),
   ];
   return concatArray(bytesArray);
 }
@@ -221,7 +221,7 @@ export function serializeMultiSigSpendingCondition(
   ];
 
   const fields = createLPList(condition.fields);
-  bytesArray.push(serializeLPList(fields));
+  bytesArray.push(serializeLPListBytes(fields));
 
   const numSigs = new Uint8Array(2);
   writeUInt16BE(numSigs, condition.signaturesRequired, 0);
@@ -265,7 +265,7 @@ export function deserializeMultiSigSpendingCondition(
   const nonce = BigInt('0x' + bytesToHex(bytesReader.readBytes(8)));
   const fee = BigInt('0x' + bytesToHex(bytesReader.readBytes(8)));
 
-  const fields = deserializeLPList(bytesReader, StacksMessageType.TransactionAuthField)
+  const fields = deserializeLPListBytes(bytesReader, StacksMessageType.TransactionAuthField)
     .values as TransactionAuthField[];
 
   let haveUncompressed = false;

packages/transactions/src/builders.ts

@@ -42,7 +42,8 @@ import {
   createSTXPostCondition,
 } from './postcondition';
 import {
-  AssetInfo,
+  Asset,
+  AssetString,
   FungiblePostCondition,
   NonFungiblePostCondition,
   PostCondition,
@@ -595,19 +596,19 @@ export function makeContractSTXPostCondition(
  * @param address - the c32check address
  * @param conditionCode - the condition code
  * @param amount - the amount of fungible tokens (in their respective base unit)
- * @param assetInfo - asset info describing the fungible token
+ * @param asset - asset info describing the fungible token
  */
 export function makeStandardFungiblePostCondition(
   address: string,
   conditionCode: FungibleConditionCode,
   amount: IntegerType,
-  assetInfo: string | AssetInfo
+  asset: AssetString | Asset
 ): FungiblePostCondition {
   return createFungiblePostCondition(
     createStandardPrincipal(address),
     conditionCode,
     amount,
-    assetInfo
+    asset
   );
 }
 
@@ -620,20 +621,20 @@ export function makeStandardFungiblePostCondition(
  * @param contractName - the name of the contract
  * @param conditionCode - the condition code
  * @param amount - the amount of fungible tokens (in their respective base unit)
- * @param assetInfo - asset info describing the fungible token
+ * @param asset - asset info describing the fungible token
  */
 export function makeContractFungiblePostCondition(
   address: string,
   contractName: string,
   conditionCode: FungibleConditionCode,
   amount: IntegerType,
-  assetInfo: string | AssetInfo
+  asset: AssetString | Asset
 ): FungiblePostCondition {
   return createFungiblePostCondition(
     createContractPrincipal(address, contractName),
     conditionCode,
     amount,
-    assetInfo
+    asset
   );
 }
 
@@ -644,21 +645,21 @@ export function makeContractFungiblePostCondition(
  *
  * @param {String} address - the c32check address
  * @param {FungibleConditionCode} conditionCode - the condition code
- * @param {AssetInfo} assetInfo - asset info describing the non-fungible token
+ * @param {Asset} asset - asset info describing the non-fungible token
  * @param {ClarityValue} assetId - asset identifier of the nft instance (typically a uint/buffer/string)
  *
  * @return {NonFungiblePostCondition}
  */
 export function makeStandardNonFungiblePostCondition(
   address: string,
   conditionCode: NonFungibleConditionCode,
-  assetInfo: string | AssetInfo,
+  asset: AssetString | Asset,
   assetId: ClarityValue
 ): NonFungiblePostCondition {
   return createNonFungiblePostCondition(
     createStandardPrincipal(address),
     conditionCode,
-    assetInfo,
+    asset,
     assetId
   );
 }
@@ -671,7 +672,7 @@ export function makeStandardNonFungiblePostCondition(
  * @param {String} address - the c32check address
  * @param {String} contractName - the name of the contract
  * @param {FungibleConditionCode} conditionCode - the condition code
- * @param {AssetInfo} assetInfo - asset info describing the non-fungible token
+ * @param {Asset} asset - asset info describing the non-fungible token
  * @param {ClarityValue} assetId - asset identifier of the nft instance (typically a uint/buffer/string)
  *
  * @return {NonFungiblePostCondition}
@@ -680,13 +681,13 @@ export function makeContractNonFungiblePostCondition(
   address: string,
   contractName: string,
   conditionCode: NonFungibleConditionCode,
-  assetInfo: string | AssetInfo,
+  asset: AssetString | Asset,
   assetId: ClarityValue
 ): NonFungiblePostCondition {
   return createNonFungiblePostCondition(
     createContractPrincipal(address, contractName),
     conditionCode,
-    assetInfo,
+    asset,
     assetId
   );
 }