@stacks/encryption

@stacks/encryption

Encryption functions used by Stacks.js packages.

Installation

npm install @stacks/encryption

Encrypt and decrypt string

import { encryptECIES, decryptECIES } from '@stacks/encryption';
import { utf8ToBytes } from '@stacks/common';

const privateKey = 'a5c61c6ca7b3e7e55edee68566aeab22e4da26baa285c7bd10e8d2218aa3b229';
const publicKey = '027d28f9951ce46538951e3697c62588a87f1f1f295de4a14fdd4c780fc52cfe69';

const testString = 'all work and no play makes jack a dull boy';

// Encrypt string with public key
const cipherObj = await encryptECIES(publicKey, utf8ToBytes(testString), true);

// Decrypt the cipher with private key to get the message
const deciphered = await decryptECIES(privateKey, cipherObj);
console.log(deciphered);

Sign content using ECDSA

import { signECDSA, verifyECDSA } from '@stacks/encryption';

const privateKey = 'a5c61c6ca7b3e7e55edee68566aeab22e4da26baa285c7bd10e8d2218aa3b229';
const testString = 'all work and no play makes jack a dull boy';

const sigObj = signECDSA(privateKey, testString);
// Verify content using ECDSA
const result = verifyECDSA(testString, sigObj.publicKey, sigObj.signature);
console.log(result); // true

encryptMnemonic and decryptMnemonic

import { bytesToHex, hexToBytes } from '@stacks/common';
import { encryptMnemonic, decryptMnemonic } from '@stacks/encryption';

const rawPhrase = 'march eager husband pilot waste rely exclude taste twist donkey actress scene';
const rawPassword = 'rawPassword';
const mockSalt = hexToBytes('ff'.repeat(16));

// Encrypt a raw mnemonic phrase to be password protected
const encoded = await encryptMnemonic(rawPhrase, rawPassword, { getRandomBytes: () => mockSalt });

// Decrypt an encrypted mnemonic phrase with a password
const decoded = await decryptMnemonic(bytesToHex(encoded), rawPassword);

console.log(decoded);

Private key to address

import { getPublicKeyFromPrivate, publicKeyToBtcAddress } from '@stacks/encryption';

const privateKey = '00cdce6b5f87d38f2a830cae0da82162e1b487f07c5affa8130f01fe1a2a25fb01';
const expectedAddress = '1WykMawQRnLh7SWmmoRL4qTDNCgAsVRF1';

const publicKey = getPublicKeyFromPrivate(privateKey);
const address = publicKeyToBtcAddress(publicKey);
console.log(address === expectedAddress); // true

Make private key

import { makeECPrivateKey, publicKeyToBtcAddress } from '@stacks/encryption';
import { SECP256K1Client } from 'jsontokens';

const privateKey = makeECPrivateKey();
// Private key is also usable with the jsontokens package
const publicKey = SECP256K1Client.derivePublicKey(privateKey);
const address = publicKeyToBtcAddress(publicKey);
console.log(address);

Changelog

7.0.0 (2024-10-25)

⚠ BREAKING CHANGES

See full list of changes at MIGRATION.md

• Update Cl.serialize to return string instead of bytes (3d4052b)
• Rename StacksTransaction to StacksTransactionWire (fe74e87)
• Update StacksTransaction constructor to options object (2b15209)
• Make StacksTransaction.serialize() return a hex-string instead of bytes (b563a2d)
• Rename message types (3d8b2dc)
• Remove BN.js compatibility (ddd8dde)
• Rename more types to use "Wire" suffix (221633a)
• Remove wrapper type for message signatures (bf08b46)
• Rename networking/fetch methods to include fetch prefix (463176a)
• Update post-condition representation to human readable types (a7cff36)
• Remove optional anchor mode from transaction options (2bec7ae)
• Remove wrapped private key type (a4e86ce)
• Change clarity types to be human readable (edad3b4)
• Update to new network object (57369cc)

Features

• Add origin post-condition principals (ccc79b3)
• Add Address namespace (1291687)
• Add STX unit helper methods (94f6c6b)
• Add postConditionToHex helper (e224b0e)
• Add Cl.parse Clarity value parser (b9f8775)
• Add non-sequential multi-sig support (and fix legacy multi-sig bugs) (879263c)
• Add serialization helpers for transaction (2c57ea4)
• Allow 0x prefix in hexToBytes helper (33ca645)
• Use API for nonce detection if available (855ca69)
• Add new api package (9cf8a75)
• Cleanup common files (8316766)

Bug Fixes

• Update post conditions input in transactions (d005d19)
• Switch to a network and client param solution (e7370a0)
• Fix string parsing in structured signature decode (9760497)
• Remove legacy methods (6cece09)
• Generate compressed private keys by default (badc4bf)
• Compressing private key should ensure string format (350e1fa)
• Move more helper functions to take network parameter (b8cbde2)
• Remove signed option for intToBigInt (1a3cc2f)
• Allow .appendOrigin to be used with unwrapped public key (9c4a951)
• Improve address helper functions (e53528b)
• Allow network name in more helper functions (3d92cc7)
• Add .bootAddress to network objects (9993519)
• Disable legacy triplesec support for mnemonic encryption (9b98e44)
• Remove legacy CLI methods (3c373e1)
• Update remaining packages for api (2378096)
• Consolidate poxaddress return types (0dbe0db)