Options
All
  • Public
  • Public/Protected
  • All
Menu

Package keychain

@stacks/keychain

Create and manage keys/wallets for the Stacks blockchain.

Installation

npm install @stacks/keychain

Mnemonic

Generate encrypted mnemonic

import { decrypt, generateEncryptedMnemonicRootKeychain } from '@stacks/keychain';

const password = '427706da374f435f959283de93652375';
const twelveWorder = await generateEncryptedMnemonicRootKeychain(password, 128);
const twentyFourWorder = await generateEncryptedMnemonicRootKeychain(password, 256);

const twelveWordDecrypted = await decrypt(twelveWorder.encryptedMnemonicPhrase, password);
console.log(twelveWordDecrypted);

const twentyFourWordDecrypted = await decrypt(twentyFourWorder.encryptedMnemonicPhrase, password);
console.log(twentyFourWordDecrypted);

Restore keychain from mnemonic

import { deriveRootKeychainFromMnemonic } from '@stacks/keychain';

const phrase =
'eternal army wreck noodle click shock include orchard jungle only middle forget idle pulse give empower iron curtain silent blush blossom chef animal sphere';

const rootNode = await deriveRootKeychainFromMnemonic(phrase);
const privateKey = rootNode.privateKey?.toString('hex');
// privateKey

Encryption

Encrypt and decrypt

import { decrypt, encrypt } from '@stacks/keychain';

const phrase = 'vivid oxygen neutral wheat find thumb cigar wheel board kiwi portion business';
const password = 'supersecret';

const encryptedText = await encrypt(phrase, password);
const plainTextBuffer = await decrypt(encryptedText, password);
console.log(plainTextBuffer);

Wallet

Generate and restore wallet

import keychain, { decrypt } from '@stacks/keychain';
import { ChainID } from '@stacks/transactions';
import { Buffer } from '@stacks/common';

const password = 'password';
const generated = await keychain.Wallet.generate(password, ChainID.Testnet);

const encryptedBackupPhrase = generated.encryptedBackupPhrase;

const plainTextBuffer = await decrypt(Buffer.from(encryptedBackupPhrase, 'hex'), password);

const backupPhrase = plainTextBuffer.toString();

const restored = await keychain.Wallet.restore(password, backupPhrase, ChainID.Mainnet);

console.log(restored.identityPublicKeychain === generated.identityPublicKeychain);
// true

Get profile from auth response

import keychain from '@stacks/keychain';
import { ChainID } from '@stacks/transactions';
import { getPublicKeyFromPrivate, makeECPrivateKey } from '@stacks/encryption';
import { decodeToken } from 'jsontokens';

const password = 'password';
const generated = await keychain.Wallet.generate(password, ChainID.Testnet);
const [identity] = generated.identities;

const appDomain = 'https://banter.pub';
const gaiaUrl = 'https://hub.blockstack.org';
const transitPrivateKey = makeECPrivateKey();
const transitPublicKey = getPublicKeyFromPrivate(transitPrivateKey);

const authResponse = await identity.makeAuthResponse({
appDomain,
gaiaUrl,
transitPublicKey,
scopes: ['publish_data'],
});
const decoded = decodeToken(authResponse);
console.log(decoded);

Get a STX address

import keychain from '@stacks/keychain';
import { ChainID, TransactionVersion } from '@stacks/transactions';

const password = 'password';
const generated = await keychain.Wallet.generate(password, ChainID.Testnet);
const signer = generated.getSigner();
const mainnetAddress = signer.getSTXAddress(TransactionVersion.Mainnet);
console.log(mainnetAddress);

const testnetAddress = signer.getSTXAddress(TransactionVersion.Testnet);
console.log(testnetAddress);

Index

Type Aliases

AllowedKeyEntropyBits: 128 | 256

Variables

DEFAULT_PROFILE: Profile = ...
default: { Wallet: typeof Wallet }

Type declaration

derivationPaths: { 1: string; 2147483648: string } = ...

Type declaration

  • 1: string
  • 2147483648: string
registrars: { id.blockstack: { apiUrl: string; registerUrl: string }; test-personal.id: { apiUrl: string; registerUrl: string } } = ...

Type declaration

  • id.blockstack: { apiUrl: string; registerUrl: string }
    • apiUrl: string
    • registerUrl: string
  • test-personal.id: { apiUrl: string; registerUrl: string }
    • apiUrl: string
    • registerUrl: string

Functions

  • assertIsTruthy<T>(val: any): asserts val is NonNullable<T>
  • Type Parameters

    • T

    Parameters

    • val: any

    Returns asserts val is NonNullable<T>

  • decrypt(dataBuffer: string | Buffer, password: string): Promise<string>
  • Decrypt an encrypted mnemonic phrase with a password. Legacy triplesec encrypted payloads are also supported.

    Parameters

    • dataBuffer: string | Buffer
    • password: string

      Password for data

    Returns Promise<string>

    the raw mnemonic phrase

  • Parameters

    • identityOwnerAddressNode: default

    Returns IdentityKeyPair

  • deriveRootKeychainFromMnemonic(plaintextMnemonic: string): Promise<BIP32Interface>
  • Parameters

    • plaintextMnemonic: string

    Returns Promise<BIP32Interface>

  • deriveStxAddressChain(chain: ChainID): ((rootNode: BIP32Interface) => { address: string; childKey: BIP32Interface; privateKey: string })
  • Parameters

    Returns ((rootNode: BIP32Interface) => { address: string; childKey: BIP32Interface; privateKey: string })

      • (rootNode: BIP32Interface): { address: string; childKey: BIP32Interface; privateKey: string }
      • Parameters

        • rootNode: BIP32Interface

        Returns { address: string; childKey: BIP32Interface; privateKey: string }

        • address: string
        • childKey: BIP32Interface
        • privateKey: string
  • encrypt(phrase: string, password: string): Promise<Buffer>
  • Encrypt a raw mnemonic phrase to be password protected

    Parameters

    • phrase: string

      Raw mnemonic phrase

    • password: string

      Password to encrypt mnemonic with

    Returns Promise<Buffer>

    The encrypted phrase

  • encryptMnemonicFormatted(plaintextMnemonic: string, password: string): Promise<{ encryptedMnemonic: Buffer; encryptedMnemonicHex: string }>
  • Parameters

    • plaintextMnemonic: string
    • password: string

    Returns Promise<{ encryptedMnemonic: Buffer; encryptedMnemonicHex: string }>

  • fetchProfile(__namedParameters: { fetchFn?: FetchFn; gaiaUrl: string; identity: Identity }): Promise<null | Profile>
  • Parameters

    • __namedParameters: { fetchFn?: FetchFn; gaiaUrl: string; identity: Identity }
      • Optional fetchFn?: FetchFn
      • gaiaUrl: string
      • identity: Identity

    Returns Promise<null | Profile>

  • generateEncryptedMnemonicRootKeychain(password: string, entropy: AllowedKeyEntropyBits): Promise<{ encryptedMnemonicPhrase: string; rootNode: BIP32Interface }>
  • Parameters

    Returns Promise<{ encryptedMnemonicPhrase: string; rootNode: BIP32Interface }>

  • generateMnemonicRootKeychain(entropy: AllowedKeyEntropyBits): Promise<{ plaintextMnemonic: string; rootNode: BIP32Interface }>
  • Parameters

    Returns Promise<{ plaintextMnemonic: string; rootNode: BIP32Interface }>

  • getAddress(node: BIP32Interface): string
  • Parameters

    • node: BIP32Interface

    Returns string

  • getBitcoinAddressNode(bitcoinKeychain: BIP32Interface, addressIndex?: number, chainType?: string): BIP32Interface
  • Parameters

    • bitcoinKeychain: BIP32Interface
    • addressIndex: number = 0
    • chainType: string = EXTERNAL_ADDRESS

    Returns BIP32Interface

  • getBitcoinPrivateKeychain(rootNode: BIP32Interface): BIP32Interface
  • Parameters

    • rootNode: BIP32Interface

    Returns BIP32Interface

  • getBlockchainIdentities(rootNode: BIP32Interface, identitiesToGenerate: number): Promise<{ bitcoinPublicKeychain: string; firstBitcoinAddress: string; identities: Identity[]; identityAddresses: string[]; identityKeypairs: IdentityKeyPair[]; identityPublicKeychain: string }>
  • Parameters

    • rootNode: BIP32Interface
    • identitiesToGenerate: number

    Returns Promise<{ bitcoinPublicKeychain: string; firstBitcoinAddress: string; identities: Identity[]; identityAddresses: string[]; identityKeypairs: IdentityKeyPair[]; identityPublicKeychain: string }>

  • getDerivationPath(chain: ChainID): string
  • Parameters

    Returns string

  • getIdentityOwnerAddressNode(identityPrivateKeychain: BIP32Interface, identityIndex?: number): Promise<default>
  • Parameters

    • identityPrivateKeychain: BIP32Interface
    • identityIndex: number = 0

    Returns Promise<default>

  • getIdentityPrivateKeychain(rootNode: BIP32Interface): BIP32Interface
  • Parameters

    • rootNode: BIP32Interface

    Returns BIP32Interface

  • getProfileURLFromZoneFile(name: string, fetchFn?: FetchFn): Promise<undefined | string>
  • Parameters

    Returns Promise<undefined | string>

  • makeIdentity(rootNode: BIP32Interface, index: number): Promise<Identity>
  • Parameters

    • rootNode: BIP32Interface
    • index: number

    Returns Promise<Identity>

  • recursiveRestoreIdentities(__namedParameters: RecursiveMakeIdentitiesOptions): Promise<Identity[]>
  • Restore identities by recursively making a new identity, and checking if it has a username.

    As soon as a username is not found for an identity, the recursion stops.

    Parameters

    • __namedParameters: RecursiveMakeIdentitiesOptions

    Returns Promise<Identity[]>

  • registerSubdomain(__namedParameters: RegisterParams): Promise<Identity>
  • Register a subdomain for a given identity

    Parameters

    • __namedParameters: RegisterParams

    Returns Promise<Identity>

  • signAndUploadProfile(__namedParameters: { gaiaHubConfig?: GaiaHubConfig; gaiaHubUrl: string; identity: Identity; profile: Profile }): Promise<void>
  • Parameters

    • __namedParameters: { gaiaHubConfig?: GaiaHubConfig; gaiaHubUrl: string; identity: Identity; profile: Profile }

    Returns Promise<void>

  • Parameters

    Returns string

  • uploadProfile(gaiaHubUrl: string, identity: Identity, signedProfileTokenData: string, gaiaHubConfig?: GaiaHubConfig): Promise<string>
  • Parameters

    • gaiaHubUrl: string
    • identity: Identity
    • signedProfileTokenData: string
    • Optional gaiaHubConfig: GaiaHubConfig

    Returns Promise<string>

  • Validate the format and availability of a subdomain. Will return an error of enum IdentityNameValidityError if an error is present. If no errors are found, will return null.

    Parameters

    • name: string

      the subdomain to be registered

    • subdomain: Subdomains = Subdomains.BLOCKSTACK

      a valid Subdomains enum

    Returns Promise<null | IdentityNameValidityError>

  • validateSubdomainAvailability(name: string, subdomain?: Subdomains, fetchFn?: FetchFn): Promise<any>
  • Parameters

    Returns Promise<any>

Generated using TypeDoc