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,7 @@
   - [StacksNodeApi](#stacksnodeapi)
   - [StacksNetwork to StacksNodeApi](#stacksnetwork-to-stacksnodeapi)
   - [Clarity Representation](#clarity-representation)
+  - [`serialize` methods](#serialize-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 +27,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.
 
 ### Stacks Network
 
@@ -144,6 +147,10 @@ For `bigint` values, the type of the `value` property is a now `string`, for bet
 }
 ```
 
+### `serialize` methods
+
+- `serialize` ... todo
+
 ## Stacks.js (&lt;=4.x.x) → (5.x.x)
 
 ### Breaking Changes

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/cl.ts

@@ -9,7 +9,7 @@ import {
   noneCV,
   responseErrorCV,
   responseOkCV,
-  serializeCV,
+  serializeCVBytes,
   someCV,
   standardPrincipalCV,
   stringAsciiCV,
@@ -269,15 +269,15 @@ export const tuple = tupleCV;
 /**
  * `Cl.serialize` — Serializes a Clarity JS object to the equivalent hex-encoded representation
  *
- * Alias for {@link serializeCV}
+ * Alias for {@link serializeCVBytes}
  * @example
  * ```
  * import { Cl } from '@stacks/transactions';
  * Cl.serialize(Cl.uint(100));
  * ```
  * @see {@link deserialize}
  */
-export const serialize = serializeCV;
+export const serialize = serializeCVBytes;
 /**
  * `Cl.deserialize` — Deserializes a hex string to the equivalent Clarity JS object
  *

packages/transactions/src/clarity/deserialize.ts

@@ -16,18 +16,13 @@ import {
   tupleCV,
 } from '.';
 import { BytesReader as BytesReader } from '../bytesReader';
-import { deserializeAddress, deserializeLPString } from '../types';
+import { deserializeAddressBytes, deserializeLPStringBytes } from '../types';
 import { DeserializationError } from '../errors';
 import { stringAsciiCV, stringUtf8CV } from './types/stringCV';
 import { bytesToAscii, bytesToUtf8, hexToBytes } from '@stacks/common';
 
 /**
  * Deserializes clarity value to clarity type
- *
- * @param {value} Uint8Array | string value to be converted to clarity type
- **
- * @returns {ClarityType} returns the clarity type instance
- *
  * @example
  * ```
  *  import { intCV, serializeCV, deserializeCV } from '@stacks/transactions';
@@ -79,12 +74,12 @@ export function deserializeCV<T extends ClarityValue = ClarityValue>(
       return falseCV() as T;
 
     case ClarityWireType.address:
-      const sAddress = deserializeAddress(bytesReader);
+      const sAddress = deserializeAddressBytes(bytesReader);
       return standardPrincipalCVFromAddress(sAddress) as T;
 
     case ClarityWireType.contract:
-      const cAddress = deserializeAddress(bytesReader);
-      const contractName = deserializeLPString(bytesReader);
+      const cAddress = deserializeAddressBytes(bytesReader);
+      const contractName = deserializeLPStringBytes(bytesReader);
       return contractPrincipalCVFromAddress(cAddress, contractName) as T;
 
     case ClarityWireType.ok:
@@ -111,7 +106,7 @@ export function deserializeCV<T extends ClarityValue = ClarityValue>(
       const tupleLength = bytesReader.readUInt32BE();
       const tupleContents: { [key: string]: ClarityValue } = {};
       for (let i = 0; i < tupleLength; i++) {
-        const clarityName = deserializeLPString(bytesReader).content;
+        const clarityName = deserializeLPStringBytes(bytesReader).content;
         if (clarityName === undefined) {
           throw new DeserializationError('"content" is undefined');
         }

packages/transactions/src/clarity/index.ts

@@ -44,5 +44,6 @@ export {
   stringAsciiCV,
   stringCV,
 } from './types/stringCV';
-export { serializeCV } from './serialize';
-export { deserializeCV } from './deserialize';
+
+export * from './serialize';
+export * from './deserialize';

packages/transactions/src/clarity/serialize.ts

@@ -6,8 +6,9 @@ import {
   writeUInt32BE,
   utf8ToBytes,
   asciiToBytes,
+  bytesToHex,
 } from '@stacks/common';
-import { serializeAddress, serializeLPString } from '../types';
+import { serializeAddressBytes, serializeLPStringBytes } from '../types';
 import { createLPString } from '../postcondition-types';
 import {
   BooleanCV,
@@ -40,7 +41,7 @@ function serializeOptionalCV(cv: OptionalCV): Uint8Array {
   if (cv.type === ClarityType.OptionalNone) {
     return new Uint8Array([clarityTypeToByte(cv.type)]);
   } else {
-    return bytesWithTypeID(cv.type, serializeCV(cv.value));
+    return bytesWithTypeID(cv.type, serializeCVBytes(cv.value));
   }
 }
 
@@ -61,18 +62,18 @@ function serializeUIntCV(cv: UIntCV): Uint8Array {
 }
 
 function serializeStandardPrincipalCV(cv: StandardPrincipalCV): Uint8Array {
-  return bytesWithTypeID(cv.type, serializeAddress(cv.address));
+  return bytesWithTypeID(cv.type, serializeAddressBytes(cv.address));
 }
 
 function serializeContractPrincipalCV(cv: ContractPrincipalCV): Uint8Array {
   return bytesWithTypeID(
     cv.type,
-    concatBytes(serializeAddress(cv.address), serializeLPString(cv.contractName))
+    concatBytes(serializeAddressBytes(cv.address), serializeLPStringBytes(cv.contractName))
   );
 }
 
 function serializeResponseCV(cv: ResponseCV) {
-  return bytesWithTypeID(cv.type, serializeCV(cv.value));
+  return bytesWithTypeID(cv.type, serializeCVBytes(cv.value));
 }
 
 function serializeListCV(cv: ListCV) {
@@ -83,7 +84,7 @@ function serializeListCV(cv: ListCV) {
   bytesArray.push(length);
 
   for (const value of cv.list) {
-    const serializedValue = serializeCV(value);
+    const serializedValue = serializeCVBytes(value);
     bytesArray.push(serializedValue);
   }
 
@@ -101,9 +102,9 @@ function serializeTupleCV(cv: TupleCV) {
 
   for (const key of lexicographicOrder) {
     const nameWithLength = createLPString(key);
-    bytesArray.push(serializeLPString(nameWithLength));
+    bytesArray.push(serializeLPStringBytes(nameWithLength));
 
-    const serializedValue = serializeCV(cv.data[key]);
+    const serializedValue = serializeCVBytes(cv.data[key]);
     bytesArray.push(serializedValue);
   }
 
@@ -132,25 +133,23 @@ function serializeStringUtf8CV(cv: StringUtf8CV) {
 }
 
 /**
- * Serializes clarity value to Uint8Array
- *
- * @param {ClarityValue} value to be converted to bytes
- **
- * @returns {Uint8Array} returns the bytes
- *
+ * Serializes clarity value to hex
  * @example
  * ```
  *  import { intCV, serializeCV } from '@stacks/transactions';
  *
  *  const serialized = serializeCV(intCV(100)); // Similarly works for other clarity types as well like listCV, booleanCV ...
- *
- *  // <Uint8Array 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 64>
+ *  // '0000000000000000000000000000000064'
  * ```
  *
  * @see
  * {@link https://github.com/hirosystems/stacks.js/blob/main/packages/transactions/tests/clarity.test.ts | clarity test cases for more examples}
  */
-export function serializeCV(value: ClarityValue): Uint8Array {
+export function serializeCV(value: ClarityValue): string {
+  return bytesToHex(serializeCVBytes(value));
+}
+/** @ignore */
+export function serializeCVBytes(value: ClarityValue): Uint8Array {
   switch (value.type) {
     case ClarityType.BoolTrue:
     case ClarityType.BoolFalse:

packages/transactions/src/constants.ts

@@ -20,7 +20,7 @@ export enum StacksMessageType {
   Principal,
   LengthPrefixedString,
   MemoString,
-  AssetInfo,
+  Asset,
   PostCondition,
   PublicKey,
   LengthPrefixedList,

packages/transactions/src/fetch.ts

@@ -6,24 +6,24 @@ import {
   validateHash256,
   with0x,
 } from '@stacks/common';
+import { deriveDefaultUrl } from '@stacks/network';
 import { ClarityValue, NoneCV, deserializeCV, serializeCV } from './clarity';
+import { ClarityAbi } from './contract-abi';
 import { NoEstimateAvailableError } from './errors';
-import { serializePayload } from './payload';
+import { serializePayloadBytes } from './payload';
 import {
   StacksTransaction,
   deriveNetworkFromTx,
   estimateTransactionByteLength,
 } from './transaction';
-import { cvToHex, defaultApiFromNetwork, parseReadOnlyResponse } from './utils';
 import {
   FeeEstimateResponse,
   FeeEstimation,
   TxBroadcastResult,
   TxBroadcastResultOk,
   TxBroadcastResultRejected,
 } from './types';
-import { deriveDefaultUrl } from '@stacks/network';
-import { ClarityAbi } from './contract-abi';
+import { cvToHex, defaultApiFromNetwork, parseReadOnlyResponse } from './utils';
 
 export const BROADCAST_PATH = '/v2/transactions';
 export const TRANSFER_FEE_ESTIMATE_PATH = '/v2/fees/transfer';
@@ -227,7 +227,7 @@ export async function estimateFee({
     const estimatedLength = estimateTransactionByteLength(txOpt);
     return (
       await estimateTransaction({
-        payload: bytesToHex(serializePayload(txOpt.payload)),
+        payload: bytesToHex(serializePayloadBytes(txOpt.payload)),
         estimatedLength,
         api,
       })
@@ -344,7 +344,7 @@ export async function getContractMapEntry<T extends ClarityValue = ClarityValue>
   mapName: string;
   mapKey: ClarityValue;
 } & ApiParam): Promise<T | NoneCV> {
-  const keyHex = with0x(bytesToHex(serializeCV(mapKey)));
+  const keyHex = with0x(serializeCV(mapKey));
 
   const options = {
     method: 'POST',

packages/transactions/src/index.ts

@@ -70,7 +70,7 @@ export {
   isPoisonPayload,
   isSmartContractPayload,
   isTokenTransferPayload,
-  serializePayload,
+  serializePayloadBytes as serializePayload,
 } from './payload';
 /**
  * ### `Pc.` Post Condition Builder

packages/transactions/src/keys.ts

@@ -13,6 +13,7 @@ import {
   hexToBigInt,
   hexToBytes,
   intToHex,
+  isInstance,
   parseRecoverableSignatureVrs,
   PRIVATE_KEY_COMPRESSED_LENGTH,
   privateKeyToBytes,
@@ -128,7 +129,11 @@ export function publicKeyIsCompressed(publicKey: PublicKey): boolean {
   return !publicKeyToHex(publicKey).startsWith('04');
 }
 
-export function serializePublicKey(key: StacksPublicKey): Uint8Array {
+export function serializePublicKey(key: StacksPublicKey): string {
+  return bytesToHex(serializePublicKeyBytes(key));
+}
+/** @ignore */
+export function serializePublicKeyBytes(key: StacksPublicKey): Uint8Array {
   return key.data.slice();
 }
 
@@ -147,7 +152,14 @@ export function compressPublicKey(publicKey: PublicKey): string {
   return Point.fromHex(publicKeyToHex(publicKey)).toHex(true);
 }
 
-export function deserializePublicKey(bytesReader: BytesReader): StacksPublicKey {
+export function deserializePublicKey(serialized: string): StacksPublicKey {
+  return deserializePublicKeyBytes(hexToBytes(serialized));
+}
+/** @ignore */
+export function deserializePublicKeyBytes(serialized: Uint8Array | BytesReader): StacksPublicKey {
+  const bytesReader = isInstance(serialized, BytesReader)
+    ? serialized
+    : new BytesReader(serialized);
   const fieldId = bytesReader.readUInt8();
   const keyLength =
     fieldId === 4 ? UNCOMPRESSED_PUBKEY_LENGTH_BYTES : COMPRESSED_PUBKEY_LENGTH_BYTES;