Skip to content

Commit

Permalink
feat!: Make serialize methods return hex-encoded strings, instead of …
Browse files Browse the repository at this point in the history
…bytes
  • Loading branch information
janniks committed Apr 25, 2024
1 parent f9682a5 commit 9d97081
Show file tree
Hide file tree
Showing 32 changed files with 546 additions and 360 deletions.
4 changes: 3 additions & 1 deletion .github/.husky/commitlint.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
}
}
40 changes: 40 additions & 0 deletions .github/MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions packages/bns/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import {
makeRandomPrivKey,
makeUnsignedContractCall,
noneCV,
parseAssetInfoString,
parseAssetString,
publicKeyToAddress,
someCV,
standardPrincipalCV,
Expand Down Expand Up @@ -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),
Expand All @@ -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),
Expand Down
10 changes: 5 additions & 5 deletions packages/bns/tests/bns.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import {
falseCV,
hash160,
noneCV,
parseAssetInfoString,
parseAssetString,
publicKeyToAddress,
responseErrorCV,
responseOkCV,
Expand Down Expand Up @@ -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),
Expand All @@ -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),
Expand Down Expand Up @@ -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),
Expand All @@ -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),
Expand Down
4 changes: 2 additions & 2 deletions packages/cli/src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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));
}
Expand Down Expand Up @@ -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));
}
Expand Down
18 changes: 9 additions & 9 deletions packages/transactions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,7 @@ const contractSTXPostCondition = makeContractSTXPostCondition(
```typescript
import {
FungibleConditionCode,
createAssetInfo,
createAsset,
makeStandardFungiblePostCondition,
} from '@stacks/transactions';

Expand All @@ -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
Expand All @@ -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
);
```

Expand All @@ -473,7 +473,7 @@ const contractFungiblePostCondition = makeContractFungiblePostCondition(
```typescript
import {
NonFungibleConditionCode,
createAssetInfo,
createAsset,
makeStandardNonFungiblePostCondition,
makeContractNonFungiblePostCondition,
bufferCVFromString,
Expand All @@ -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
);

Expand All @@ -503,7 +503,7 @@ const contractNonFungiblePostCondition = makeContractNonFungiblePostCondition(
contractAddress,
contractName,
postConditionCode,
nonFungibleAssetInfo,
nonFungibleAsset,
assetId
);
```
Expand Down
12 changes: 6 additions & 6 deletions packages/transactions/src/authorization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -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);
}
Expand All @@ -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);
Expand Down Expand Up @@ -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;
Expand Down
27 changes: 14 additions & 13 deletions packages/transactions/src/builders.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ import {
createSTXPostCondition,
} from './postcondition';
import {
AssetInfo,
Asset,
AssetString,
FungiblePostCondition,
NonFungiblePostCondition,
PostCondition,
Expand Down Expand Up @@ -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
);
}

Expand All @@ -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
);
}

Expand All @@ -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
);
}
Expand All @@ -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}
Expand All @@ -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
);
}
Expand Down
Loading

0 comments on commit 9d97081

Please sign in to comment.