diff --git a/packages/transactions/README.md b/packages/transactions/README.md index 40a36bbb5..1669aaddc 100644 --- a/packages/transactions/README.md +++ b/packages/transactions/README.md @@ -18,7 +18,7 @@ This library supports the creation of the following Stacks transaction types: ## Key Generation -```javascript +```typescript import { createStacksPrivateKey, makeRandomPrivKey, getPublicKey } from '@stacks/transactions'; // Random key @@ -33,26 +33,24 @@ const privateKey = createStacksPrivateKey(key); ## STX Token Transfer Transaction -```javascript +```typescript import { makeSTXTokenTransfer, - makeStandardSTXPostCondition, broadcastTransaction, + AnchorMode, } from '@stacks/transactions'; import { StacksTestnet, StacksMainnet } from '@stacks/network'; -const BigNum = require('bn.js'); // for mainnet, use `StacksMainnet()` const network = new StacksTestnet(); const txOptions = { recipient: 'SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159', - amount: new BigNum(12345), + amount: 12345n, senderKey: 'b244296d5907de9864c0b0d51f98a13c52890be0404e83f273144cd5b9960eed01', network, memo: 'test memo', - nonce: new BigNum(0), // set a nonce manually if you don't want builder to fetch from a Stacks node - fee: new BigNum(200), // set a tx fee if you don't want the builder to estimate + fee: 200n, // set a tx fee if you don't want the builder to estimate anchorMode: AnchorMode.Any }; @@ -62,37 +60,44 @@ const transaction = await makeSTXTokenTransfer(txOptions); const serializedTx = transaction.serialize().toString('hex'); // broadcasting transaction to the specified network -broadcastTransaction(transaction, network); +const result = await broadcastTransaction(transaction, network); ``` ## Smart Contract Deploy Transaction -```javascript +```typescript import { makeContractDeploy, broadcastTransaction, AnchorMode } from '@stacks/transactions'; import { StacksTestnet, StacksMainnet } from '@stacks/network'; -const BigNum = require('bn.js'); +import { readFileSync } from 'fs'; // for mainnet, use `StacksMainnet()` const network = new StacksTestnet(); const txOptions = { contractName: 'contract_name', - codeBody: fs.readFileSync('/path/to/contract.clar').toString(), + codeBody: readFileSync('/path/to/contract.clar').toString(), senderKey: 'b244296d5907de9864c0b0d51f98a13c52890be0404e83f273144cd5b9960eed01', network, + anchorMode: AnchorMode.Any, }; const transaction = await makeContractDeploy(txOptions); -broadcastTransaction(transaction, network); +const result = await broadcastTransaction(transaction, network); ``` ## Smart Contract Function Call -```javascript -import { makeContractCall, BufferCV, broadcastTransaction, AnchorMode } from '@stacks/transactions'; +```typescript +import { + makeContractCall, + broadcastTransaction, + AnchorMode, + FungibleConditionCode, + makeStandardSTXPostCondition, + bufferCVFromString, +} from '@stacks/transactions'; import { StacksTestnet, StacksMainnet } from '@stacks/network'; -const BigNum = require('bn.js'); // for mainnet, use `StacksMainnet()` const network = new StacksTestnet(); @@ -101,7 +106,7 @@ const network = new StacksTestnet(); // See below for details on constructing post conditions const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE'; const postConditionCode = FungibleConditionCode.GreaterEqual; -const postConditionAmount = new BigNum(1000000); +const postConditionAmount = 1000000n; const postConditions = [ makeStandardSTXPostCondition(postConditionAddress, postConditionCode, postConditionAmount), ]; @@ -120,24 +125,27 @@ const txOptions = { const transaction = await makeContractCall(txOptions); -broadcastTransaction(transaction, network); +const result = await broadcastTransaction(transaction, network); ``` In this example we construct a `contract-call` transaction with a post condition. We have set the `validateWithAbi` option to `true`, so the `makeContractCall` builder will attempt to fetch this contracts ABI from the specified Stacks network, and validate that the provided functionArgs match what is described in the ABI. This should help you avoid constructing invalid contract-call transactions. If you would prefer to provide your own ABI instead of fetching it from the network, the `validateWithABI` option also accepts [ClarityABI](https://github.com/blockstack/stacks-transactions-js/blob/master/src/contract-abi.ts#L231) objects, which can be constructed from ABI files like so: ```typescript +import { + ClarityAbi +} from '@stacks/transactions'; import { readFileSync } from 'fs'; const abi: ClarityAbi = JSON.parse(readFileSync('abi.json').toString()); +// For sample abi json see: stacks.js/packages/transactions/tests/abi/test-abi.json ``` ## Sponsoring Transactions To generate a sponsored transaction, first create and sign the transaction as the origin. The `sponsored` property in the options object must be set to true. -```javascript -import { makeContractCall, BufferCV, AnchorMode } from '@stacks/transactions'; -const BigNum = require('bn.js'); +```typescript +import { makeContractCall, BufferCV, AnchorMode, bufferCVFromString } from '@stacks/transactions'; const txOptions = { contractAddress: 'SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X', @@ -156,7 +164,7 @@ const serializedTx = transaction.serialize().toString('hex'); The serialized transaction can now be passed to the sponsoring party which will sign the sponsor portion of the transaction and set the fee. -```javascript +```typescript import { sponsorTransaction, BufferReader, @@ -164,12 +172,11 @@ import { broadcastTransaction, } from '@stacks/transactions'; import { StacksTestnet, StacksMainnet } from '@stacks/network'; -const BigNum = require('bn.js'); const bufferReader = new BufferReader(Buffer.from(serializedTx)); const deserializedTx = deserializeTransaction(bufferReader); const sponsorKey = '770287b9471081c8acd37d57190c7a70f0da2633311cc120853537362d32e67c01'; -const fee = new BigNum(1000); +const fee = 1000n; const sponsorOptions = { transaction: deserializedTx, @@ -181,7 +188,7 @@ const sponsoredTx = await sponsorTransaction(sponsorOptions); // for mainnet, use `StacksMainnet()` const network = new StacksTestnet(); -broadcastTransaction(sponsoredTx, network); +const result = await broadcastTransaction(sponsoredTx, network); ``` ## Supporting multi-signature transactions @@ -193,6 +200,7 @@ The `numSignatures` and `publicKeys` properties in the options object must be se import { makeUnsignedSTXTokenTransfer, createStacksPrivateKey, + deserializeTransaction, pubKeyfromPrivKey, publicKeyToString, TransactionSigner, @@ -200,12 +208,10 @@ import { BufferReader, AnchorMode, } from '@stacks/transactions'; -const BigNum = require('bn.js'); const recipient = standardPrincipalCV('SP3FGQ8...'); -const amount = new BigNum(2500000); -const fee = new BigNum(0); -const nonce = new BigNum(0); +const amount = 2500000n; +const fee = 0n; const memo = 'test memo'; // private keys of the participants in the transaction @@ -224,7 +230,6 @@ const transaction = await makeUnsignedSTXTokenTransfer({ recipient, amount, fee, - nonce, memo, numSignatures: 2, // number of signature required publicKeys: pubKeyStrings, // public key string array with >= numSignatures elements @@ -264,6 +269,12 @@ const serializedSignedTx = deserializedTx.serialize(); Read-only contract functions can be called without generating or broadcasting a transaction. Instead it works via a direct API call to a Stacks node. ```typescript +import { + bufferCVFromString, + callReadOnlyFunction, +} from '@stacks/transactions'; +import { StacksTestnet } from '@stacks/network'; + const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; const contractName = 'kv-store'; const functionName = 'get-value'; @@ -308,7 +319,24 @@ Building transactions that call functions in deployed clarity contracts requires This library contains Typescript types and classes that map to the Clarity types, in order to make it easy to construct well-typed Clarity values in Javascript. These types all extend the abstract class `ClarityValue`. -```javascript +```typescript +import { + trueCV, + falseCV, + noneCV, + someCV, + intCV, + uintCV, + standardPrincipalCV, + contractPrincipalCV, + responseErrorCV, + responseOkCV, + listCV, + tupleCV, + bufferCV, +} from '@stacks/transactions'; +import { Buffer } from '@stacks/common'; + // construct boolean clarity values const t = trueCV(); const f = falseCV(); @@ -364,11 +392,17 @@ For details see: https://github.com/blockstack/stacks-blockchain/blob/master/sip ### STX post condition -```javascript +```typescript +import { + FungibleConditionCode, + makeStandardSTXPostCondition, + makeContractSTXPostCondition, +} from '@stacks/transactions'; + // With a standard principal const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE'; const postConditionCode = FungibleConditionCode.GreaterEqual; -const postConditionAmount = new BigNum(12345); +const postConditionAmount = 12345n; const standardSTXPostCondition = makeStandardSTXPostCondition( postConditionAddress, @@ -390,11 +424,17 @@ const contractSTXPostCondition = makeContractSTXPostCondition( ### Fungible token post condition -```javascript +```typescript +import { + FungibleConditionCode, + createAssetInfo, + makeStandardFungiblePostCondition, +} from '@stacks/transactions'; + // With a standard principal const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE'; const postConditionCode = FungibleConditionCode.GreaterEqual; -const postConditionAmount = new BigNum(12345); +const postConditionAmount = 12345n; const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ'; const assetContractName = 'test-asset-contract'; const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName); @@ -424,14 +464,22 @@ const contractFungiblePostCondition = makeContractFungiblePostCondition( ### Non-fungible token post condition -```javascript +```typescript +import { + NonFungibleConditionCode, + createAssetInfo, + makeStandardNonFungiblePostCondition, + makeContractNonFungiblePostCondition, + bufferCVFromString, +} from '@stacks/transactions'; + // With a standard principal const postConditionAddress = 'SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE'; const postConditionCode = NonFungibleConditionCode.Owns; const assetAddress = 'SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ'; const assetContractName = 'test-asset-contract'; const assetName = 'test-asset'; -const tokenAssetName = 'test-token-asset'; +const tokenAssetName = bufferCVFromString('test-token-asset'); const nonFungibleAssetInfo = createAssetInfo(assetAddress, assetContractName, assetName); const standardNonFungiblePostCondition = makeStandardNonFungiblePostCondition( @@ -460,6 +508,11 @@ const contractNonFungiblePostCondition = makeContractNonFungiblePostCondition( Clarity Values represent values of Clarity contracts. If a JSON format is required the helper function `cvToJSON` can be used. -``` +```typescript +import { + cvToJSON, + hexToCV +} from '@stacks/transactions'; + cvToJSON(hexToCV(tx.tx_result.hex)) ```