refactor!: change clarity types to be human readable

BREAKING CHANGE:
The `ClarityType` was changed to a readable string, from the previous Number type. This makes it easier to read and construct types when debugging.

Author: janniks

packages/transactions/src/clarity/constants.ts

@@ -1,21 +1,52 @@
+/**
+ * Clarity type names used for the human-readable representation of Clarity values
+ */
+export enum ClarityType {
+  Int = 'int',
+  UInt = 'uint',
+  Buffer = 'buffer',
+  BoolTrue = 'true',
+  BoolFalse = 'false',
+  PrincipalStandard = 'address',
+  PrincipalContract = 'contract',
+  ResponseOk = 'ok',
+  ResponseErr = 'err',
+  OptionalNone = 'none',
+  OptionalSome = 'some',
+  List = 'list',
+  Tuple = 'tuple',
+  StringASCII = 'ascii',
+  StringUTF8 = 'utf8',
+}
+
 /**
  * Type IDs corresponding to each of the Clarity value types as described here:
  * {@link https://github.com/blockstack/blockstack-core/blob/sip/sip-005/sip/sip-005-blocks-and-transactions.md#clarity-value-representation}
  */
-export enum ClarityType {
-  Int = 0x00,
-  UInt = 0x01,
-  Buffer = 0x02,
-  BoolTrue = 0x03,
-  BoolFalse = 0x04,
-  PrincipalStandard = 0x05,
-  PrincipalContract = 0x06,
-  ResponseOk = 0x07,
-  ResponseErr = 0x08,
-  OptionalNone = 0x09,
-  OptionalSome = 0x0a,
-  List = 0x0b,
-  Tuple = 0x0c,
-  StringASCII = 0x0d,
-  StringUTF8 = 0x0e,
+export enum ClarityWireType {
+  int = 0x00,
+  uint = 0x01,
+  buffer = 0x02,
+  true = 0x03,
+  false = 0x04,
+  address = 0x05,
+  contract = 0x06,
+  ok = 0x07,
+  err = 0x08,
+  none = 0x09,
+  some = 0x0a,
+  list = 0x0b,
+  tuple = 0x0c,
+  ascii = 0x0d,
+  utf8 = 0x0e,
+}
+
+/** @ignore internal for now */
+export function clarityTypeToByte(type: ClarityType): ClarityWireType {
+  return ClarityWireType[type];
+}
+
+/** @ignore internal for now */
+export function clarityByteToType(wireType: ClarityWireType): ClarityType {
+  return ClarityWireType[wireType] as ClarityType; // numerical enums are bidirectional in TypeScript
 }

packages/transactions/src/clarity/deserialize.ts

@@ -1,5 +1,5 @@
 import {
-  ClarityType,
+  ClarityWireType,
   ClarityValue,
   intCV,
   uintCV,
@@ -43,7 +43,7 @@ import { bytesToAscii, bytesToUtf8, hexToBytes } from '@stacks/common';
  * @see
  * {@link https://github.com/hirosystems/stacks.js/blob/main/packages/transactions/tests/clarity.test.ts | clarity test cases for more examples}
  */
-export default function deserializeCV<T extends ClarityValue = ClarityValue>(
+export function deserializeCV<T extends ClarityValue = ClarityValue>(
   serializedClarityValue: BytesReader | Uint8Array | string
 ): T {
   let bytesReader: BytesReader;
@@ -57,57 +57,57 @@ export default function deserializeCV<T extends ClarityValue = ClarityValue>(
   } else {
     bytesReader = serializedClarityValue;
   }
-  const type = bytesReader.readUInt8Enum(ClarityType, n => {
+  const type = bytesReader.readUInt8Enum(ClarityWireType, n => {
     throw new DeserializationError(`Cannot recognize Clarity Type: ${n}`);
   });
 
   switch (type) {
-    case ClarityType.Int:
+    case ClarityWireType.int:
       return intCV(bytesReader.readBytes(16)) as T;
 
-    case ClarityType.UInt:
+    case ClarityWireType.uint:
       return uintCV(bytesReader.readBytes(16)) as T;
 
-    case ClarityType.Buffer:
+    case ClarityWireType.buffer:
       const bufferLength = bytesReader.readUInt32BE();
       return bufferCV(bytesReader.readBytes(bufferLength)) as T;
 
-    case ClarityType.BoolTrue:
+    case ClarityWireType.true:
       return trueCV() as T;
 
-    case ClarityType.BoolFalse:
+    case ClarityWireType.false:
       return falseCV() as T;
 
-    case ClarityType.PrincipalStandard:
+    case ClarityWireType.address:
       const sAddress = deserializeAddress(bytesReader);
       return standardPrincipalCVFromAddress(sAddress) as T;
 
-    case ClarityType.PrincipalContract:
+    case ClarityWireType.contract:
       const cAddress = deserializeAddress(bytesReader);
       const contractName = deserializeLPString(bytesReader);
       return contractPrincipalCVFromAddress(cAddress, contractName) as T;
 
-    case ClarityType.ResponseOk:
+    case ClarityWireType.ok:
       return responseOkCV(deserializeCV(bytesReader)) as T;
 
-    case ClarityType.ResponseErr:
+    case ClarityWireType.err:
       return responseErrorCV(deserializeCV(bytesReader)) as T;
 
-    case ClarityType.OptionalNone:
+    case ClarityWireType.none:
       return noneCV() as T;
 
-    case ClarityType.OptionalSome:
+    case ClarityWireType.some:
       return someCV(deserializeCV(bytesReader)) as T;
 
-    case ClarityType.List:
+    case ClarityWireType.list:
       const listLength = bytesReader.readUInt32BE();
       const listContents: ClarityValue[] = [];
       for (let i = 0; i < listLength; i++) {
         listContents.push(deserializeCV(bytesReader));
       }
       return listCV(listContents) as T;
 
-    case ClarityType.Tuple:
+    case ClarityWireType.tuple:
       const tupleLength = bytesReader.readUInt32BE();
       const tupleContents: { [key: string]: ClarityValue } = {};
       for (let i = 0; i < tupleLength; i++) {
@@ -119,12 +119,12 @@ export default function deserializeCV<T extends ClarityValue = ClarityValue>(
       }
       return tupleCV(tupleContents) as T;
 
-    case ClarityType.StringASCII:
+    case ClarityWireType.ascii:
       const asciiStrLen = bytesReader.readUInt32BE();
       const asciiStr = bytesToAscii(bytesReader.readBytes(asciiStrLen));
       return stringAsciiCV(asciiStr) as T;
 
-    case ClarityType.StringUTF8:
+    case ClarityWireType.utf8:
       const utf8StrLen = bytesReader.readUInt32BE();
       const utf8Str = bytesToUtf8(bytesReader.readBytes(utf8StrLen));
       return stringUtf8CV(utf8Str) as T;

packages/transactions/src/clarity/index.ts

@@ -1,28 +1,28 @@
-import {
+// todo: use `export *` for more exports here
+
+export {
   ClarityValue,
   getCVTypeString,
   cvToString,
   cvToJSON,
   cvToValue,
   isClarityType,
 } from './clarityValue';
-import { ClarityType } from './constants';
-import { BooleanCV, TrueCV, FalseCV, trueCV, falseCV, boolCV } from './types/booleanCV';
-import { IntCV, UIntCV, intCV, uintCV } from './types/intCV';
-import { BufferCV, bufferCV, bufferCVFromString } from './types/bufferCV';
-import { OptionalCV, NoneCV, SomeCV, noneCV, someCV, optionalCVOf } from './types/optionalCV';
-
-// todo: reduce manual re-exporting
+export * from './constants';
+export { BooleanCV, TrueCV, FalseCV, trueCV, falseCV, boolCV } from './types/booleanCV';
+export { IntCV, UIntCV, intCV, uintCV } from './types/intCV';
+export { BufferCV, bufferCV, bufferCVFromString } from './types/bufferCV';
+export { OptionalCV, NoneCV, SomeCV, noneCV, someCV, optionalCVOf } from './types/optionalCV';
 
-import {
+export {
   ResponseCV,
   ResponseOkCV,
   ResponseErrorCV,
   responseOkCV,
   responseErrorCV,
 } from './types/responseCV';
 
-import {
+export {
   StandardPrincipalCV,
   ContractPrincipalCV,
   standardPrincipalCV,
@@ -35,74 +35,14 @@ import {
   principalToString,
 } from './types/principalCV';
 
-import { ListCV, listCV } from './types/listCV';
-import { TupleCV, tupleCV } from './types/tupleCV';
-import {
+export { ListCV, listCV } from './types/listCV';
+export { TupleCV, tupleCV } from './types/tupleCV';
+export {
   StringAsciiCV,
   StringUtf8CV,
   stringUtf8CV,
   stringAsciiCV,
   stringCV,
 } from './types/stringCV';
-import { serializeCV } from './serialize';
-import deserializeCV from './deserialize';
-
-// Types
-export {
-  ClarityType,
-  ClarityValue,
-  BooleanCV,
-  TrueCV,
-  FalseCV,
-  IntCV,
-  UIntCV,
-  BufferCV,
-  OptionalCV,
-  NoneCV,
-  SomeCV,
-  ResponseCV,
-  ResponseOkCV,
-  ResponseErrorCV,
-  PrincipalCV,
-  StandardPrincipalCV,
-  ContractPrincipalCV,
-  ListCV,
-  TupleCV,
-  StringAsciiCV,
-  StringUtf8CV,
-};
-
-// Value construction functions
-export {
-  boolCV,
-  trueCV,
-  falseCV,
-  intCV,
-  uintCV,
-  bufferCV,
-  bufferCVFromString,
-  noneCV,
-  someCV,
-  optionalCVOf,
-  responseOkCV,
-  responseErrorCV,
-  principalCV,
-  standardPrincipalCV,
-  standardPrincipalCVFromAddress,
-  contractPrincipalCV,
-  contractPrincipalCVFromAddress,
-  contractPrincipalCVFromStandard,
-  listCV,
-  tupleCV,
-  stringCV,
-  stringAsciiCV,
-  stringUtf8CV,
-  getCVTypeString,
-  isClarityType,
-};
-
-// Serialization
-export { serializeCV, deserializeCV };
-
-// toString
-export { cvToString, cvToJSON, cvToValue, principalToString };
+export { serializeCV } from './serialize';
+export { deserializeCV } from './deserialize';

packages/transactions/src/clarity/serialize.ts

@@ -22,23 +22,23 @@ import {
   TupleCV,
   ClarityValue,
 } from '.';
-import { ClarityType } from './constants';
+import { ClarityType, clarityTypeToByte } from './constants';
 
 import { SerializationError } from '../errors';
 import { StringAsciiCV, StringUtf8CV } from './types/stringCV';
 import { CLARITY_INT_BYTE_SIZE, CLARITY_INT_SIZE } from '../constants';
 
 function bytesWithTypeID(typeId: ClarityType, bytes: Uint8Array): Uint8Array {
-  return concatArray([typeId, bytes]);
+  return concatArray([clarityTypeToByte(typeId), bytes]);
 }
 
 function serializeBoolCV(value: BooleanCV): Uint8Array {
-  return new Uint8Array([value.type]);
+  return new Uint8Array([clarityTypeToByte(value.type)]);
 }
 
 function serializeOptionalCV(cv: OptionalCV): Uint8Array {
   if (cv.type === ClarityType.OptionalNone) {
-    return new Uint8Array([cv.type]);
+    return new Uint8Array([clarityTypeToByte(cv.type)]);
   } else {
     return bytesWithTypeID(cv.type, serializeCV(cv.value));
   }

packages/transactions/src/clarity/types/booleanCV.ts

@@ -20,7 +20,7 @@ interface FalseCV {
  *  import { trueCV } from '@stacks/transactions';
  *
  *  const trueCV = trueCV();
- *  // { type: 3 }
+ *  // { type: 'true' }
  * ```
  *
  * @see
@@ -38,7 +38,7 @@ const trueCV = (): BooleanCV => ({ type: ClarityType.BoolTrue });
  *  import { falseCV } from '@stacks/transactions';
  *
  *  const falseCV = falseCV();
- *  // { type: 4 }
+ *  // { type: 'false' }
  * ```
  *
  * @see
@@ -56,7 +56,7 @@ const falseCV = (): BooleanCV => ({ type: ClarityType.BoolFalse });
  *  import { boolCV } from '@stacks/transactions';
  *
  *  const boolCV = boolCV(false);
- *  // { type: 4 }
+ *  // { type: 'false' }
  * ```
  *
  * @see

packages/transactions/src/clarity/types/bufferCV.ts

@@ -19,7 +19,7 @@ interface BufferCV {
  *
  *  const buffer = utf8ToBytes('this is a test');
  *  const buf = bufferCV(buffer);
- *  // { type: 2, buffer: <Uint8Array 74 68 69 73 20 69 73 20 61 20 74 65 73 74> }
+ *  // { type: 'buffer', buffer: <Uint8Array 74 68 69 73 20 69 73 20 61 20 74 65 73 74> }
  *  const value = bytesToUtf8(buf.buffer);
  *  // this is a test
  * ```
@@ -48,7 +48,7 @@ const bufferCV = (buffer: Uint8Array): BufferCV => {
  *
  *  const str = 'this is a test';
  *  const buf = bufferCVFromString(str);
- *  // { type: 2, buffer: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74> }
+ *  // { type: 'buffer', buffer: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74> }
  *  const value = bytesToUtf8(buf.buffer);
  *  // this is a test
  *```

packages/transactions/src/clarity/types/intCV.ts

@@ -24,7 +24,7 @@ interface IntCV {
  *  import { intCV } from '@stacks/transactions';
  *
  *  const value = intCV('100'); // parameter any of type: number | string | bigint | Uint8Array | BN
- *  // { type: 0, value: 100n }
+ *  // { type: 'int', value: 100n }
  * ```
  *
  * @see
@@ -57,7 +57,7 @@ interface UIntCV {
  *  import { uintCV } from '@stacks/transactions';
  *
  *  const value = uintCV('100'); // parameter any of type: number | string | bigint | Uint8Array | BN
- *  // { type: 1, value: 100n }
+ *  // { type: 'uint', value: 100n }
  * ```
  *
  * @see

packages/transactions/src/clarity/types/listCV.ts

@@ -18,7 +18,7 @@ interface ListCV<T extends ClarityValue = ClarityValue> {
  *  import { listCV, intCV } from '@stacks/transactions';
  *
  *  const list = listCV([intCV(1), intCV(2), intCV(3), intCV(-4)]);
- *  // { type: 11, list: [ { type: 0, value: 1n }, { type: 0, value: 2n }, { type: 0, value: 3n }, { type: 0, value: -4n } ] }
+ *  // { type: 'list', list: [ { type: 0, value: 1n }, { type: 0, value: 2n }, { type: 0, value: 3n }, { type: 0, value: -4n } ] }
  * ```
  *
  * @see