npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@kadena/wallet-sdk

v0.1.1

Published

# Kadena Wallet SDK Documentation

Downloads

125

Readme

@kadena/wallet-sdk

Kadena Wallet SDK Documentation

The Kadena Wallet SDK provides a simple and unified interface to integrate Kadena blockchain functionalities into your wallet applications. It abstracts the complexities of interacting with the Kadena network, allowing you to focus on building feature-rich wallet experiences without re-implementing common integrations.

Important Note on Key Generation and Signing

For key generation and signing functionalities, you will need the Kadena HD Wallet package. Please refer to the Kadena HD Wallet documentation for detailed instructions on how to generate keys and sign transactions securely.


Table of Contents


Introduction

Building wallets on the Kadena blockchain has never been easier. The Kadena Wallet SDK is designed to be intuitive and straightforward, enabling developers of all levels—even those with intermediate experience—to seamlessly integrate Kadena functionalities into their wallet applications. With this SDK, you can quickly add essential features like transaction management, account querying, and cross-chain transfers without getting bogged down by the underlying complexities.

Key Benefits

  • Ease of Use: Designed with simplicity in mind, allowing developers to get started quickly.
  • Time-saving: Eliminates the need to re-implement common functionalities, accelerating development.
  • Comprehensive: Offers a wide range of features to cover most wallet integration needs.
  • Flexible: Provides detailed control when needed, with clear parameters and options.

Getting Started

Installation

To install the Kadena Wallet SDK, you can use npm or yarn:

# Using npm
npm install @kadena/wallet-sdk

# Using yarn
yarn add @kadena/wallet-sdk

Basic Usage

Import the WalletSDK class and create an instance:

import { WalletSDK } from '@kadena/wallet-sdk';

const walletSdk = new WalletSDK();

Core Features

Creating and Sending Transactions

createSimpleTransfer

Creates a simple transfer transaction that only accepts k: accounts (accounts identified by public keys).

Method Signature:

createSimpleTransfer(transfer: SimpleCreateTransfer & { networkId: string }): IUnsignedCommand;

Parameters:

  • transfer: An object containing:
    • sender: string - Sender's public key or k: account (e.g., 'k:senderPublicKey' or 'senderPublicKey').
    • receiver: string - Receiver's public key or k: account (e.g., 'k:receiverPublicKey' or 'receiverPublicKey').
    • amount: string - Amount to transfer (e.g., '10').
    • chainId: ChainId - The chain ID where the transaction will be executed (e.g., '1').
    • networkId: string - The network ID (e.g., 'mainnet01', 'testnet04').

Returns:

  • IUnsignedCommand: An unsigned transaction command ready to be signed and sent.

Example:

const unsignedTransaction = walletSdk.createSimpleTransfer({
  sender: 'k:senderPublicKey',
  receiver: 'k:receiverPublicKey',
  amount: '10',
  chainId: '1',
  networkId: 'testnet04',
});

// Sign the transaction (implementation depends on your signing method)
// For example, using a signing function:
// const signedTransaction = signTransaction(unsignedTransaction);

// Send the signed transaction
const transactionDescriptor = await walletSdk.sendTransaction(
  signedTransaction,
  'testnet04',
  '1',
);

console.log(
  'Transaction sent with request key:',
  transactionDescriptor.requestKey,
);

createTransfer

Creates a transfer transaction that accepts any kind of account, including those requiring custom keysets or predicates.

Method Signature:

createTransfer(transfer: CreateTransfer & { networkId: string }): IUnsignedCommand;

Parameters:

  • transfer: An object containing:
    • sender: string - Sender's account name (e.g., 'senderAccount').
    • receiver: string - Receiver's account name (e.g., 'receiverAccount').
    • amount: string - Amount to transfer (e.g., '50').
    • senderGuard: IGuard - Optional guard (keyset) for the sender's account.
    • receiverGuard: IGuard - Optional guard for the receiver's account.
    • chainId: ChainId - The chain ID where the transaction will be executed (e.g., '1').
    • networkId: string - The network ID.

Returns:

  • IUnsignedCommand: An unsigned transaction command ready to be signed and sent.

Example:

const unsignedTransaction = walletSdk.createTransfer({
  sender: 'senderAccount',
  receiver: 'receiverAccount',
  amount: '50',
  chainId: '1',
  networkId: 'testnet04',
  // Optional guards
  // senderGuard: { keys: ['senderPublicKey'], pred: 'keys-all' },
  // receiverGuard: { keys: ['receiverPublicKey'], pred: 'keys-all' },
});

// Sign the transaction
// const signedTransaction = signTransaction(unsignedTransaction);

// Send the signed transaction
const transactionDescriptor = await walletSdk.sendTransaction(
  signedTransaction,
  'testnet04',
  '1',
);

console.log(
  'Transaction sent with request key:',
  transactionDescriptor.requestKey,
);

createCrossChainTransfer

Creates a cross-chain transfer transaction to move assets from one chain to another within the Kadena network.

Method Signature:

createCrossChainTransfer(transfer: CreateCrossChainTransfer & { networkId: string }): IUnsignedCommand;

Parameters:

  • transfer: An object containing:
    • sender: string - Sender's account name (e.g., 'senderAccount').
    • receiver: string - Receiver's account name (e.g., 'receiverAccount').
    • amount: string - Amount to transfer (e.g., '25').
    • fromChainId: ChainId - The source chain ID (e.g., '0').
    • toChainId: ChainId - The target chain ID (e.g., '1').
    • networkId: string - The network ID.
    • senderGuard: IGuard - Optional guard for the sender's account.
    • receiverGuard: IGuard - Optional guard for the receiver's account.

Returns:

  • IUnsignedCommand: An unsigned transaction command ready to be signed and sent.

Example:

const unsignedTransaction = walletSdk.createCrossChainTransfer({
  sender: 'senderAccount',
  receiver: 'receiverAccount',
  amount: '25',
  fromChainId: '0',
  toChainId: '1',
  networkId: 'testnet04',
  // Optional guards
  // senderGuard: { keys: ['senderPublicKey'], pred: 'keys-all' },
  // receiverGuard: { keys: ['receiverPublicKey'], pred: 'keys-all' },
});

// Sign the transaction
// const signedTransaction = signTransaction(unsignedTransaction);

// Send the signed transaction
const transactionDescriptor = await walletSdk.sendTransaction(
  signedTransaction,
  'testnet04',
  '0', // Source chain ID
);

console.log(
  'Cross-chain transaction sent with request key:',
  transactionDescriptor.requestKey,
);

createFinishCrossChainTransfer

Creates the finishing step for a cross-chain transfer. This step is necessary to complete the transfer on the target chain.

Method Signature:

createFinishCrossChainTransfer(
  transfer: ICreateCrossChainFinishInput,
  gasPayer: { account: string; publicKeys: ISigner[] },
): Promise<IUnsignedCommand>;

Parameters:

  • transfer: An object containing:
    • proof: string - The SPV proof obtained from the source chain.
    • requestKey: string - The request key of the initial cross-chain transfer.
    • fromChainId: ChainId - The source chain ID.
    • toChainId: ChainId - The target chain ID.
    • networkId: string - The network ID.
    • receiver: string - Receiver's account name.
    • receiverGuard: IGuard - Optional guard for the receiver's account.
  • gasPayer: An object containing:
    • account: string - The account that will pay for the gas fees.
    • publicKeys: ISigner[] - The public keys associated with the gas payer's account.

Returns:

  • Promise<IUnsignedCommand>: An unsigned transaction command ready to be signed and sent.

Example:

const unsignedTransaction = await walletSdk.createFinishCrossChainTransfer(
  {
    proof: 'spvProofString',
    requestKey: 'initialRequestKey',
    fromChainId: '0',
    toChainId: '1',
    networkId: 'testnet04',
    receiver: 'receiverAccount',
    // Optional receiver guard
    // receiverGuard: { keys: ['receiverPublicKey'], pred: 'keys-all' },
  },
  {
    account: 'gasPayerAccount',
    publicKeys: ['gasPayerPublicKey1', 'gasPayerPublicKey2'],
  },
);

// Sign the transaction
// const signedTransaction = signTransaction(unsignedTransaction);

// Send the signed transaction
const transactionDescriptor = await walletSdk.sendTransaction(
  signedTransaction,
  'testnet04',
  '1', // Target chain ID
);

console.log(
  'Finishing cross-chain transaction sent with request key:',
  transactionDescriptor.requestKey,
);

sendTransaction

Sends a signed transaction to the Kadena network.

Method Signature:

sendTransaction(
  transaction: ICommand,
  networkId: string,
  chainId: ChainId,
): Promise<ITransactionDescriptor>;

Parameters:

  • transaction: ICommand - The signed transaction command.
  • networkId: string - The network ID (e.g., 'mainnet01', 'testnet04').
  • chainId: ChainId - The chain ID where the transaction will be executed.

Returns:

  • Promise<ITransactionDescriptor>: An object containing the request key, chain ID, and network ID of the transaction.

Example:

const transactionDescriptor = await walletSdk.sendTransaction(
  signedTransaction,
  'testnet04',
  '1',
);

console.log(
  'Transaction sent with request key:',
  transactionDescriptor.requestKey,
);

Retrieving History and Updates

getTransfers

Retrieves a list of transfers associated with an account.

Method Signature:

getTransfers(
  accountName: string,
  networkId: string,
  fungible?: string,
  chainId?: ChainId,
): Promise<Transfer[]>;

Parameters:

  • accountName: string - The account name to query (e.g., 'k:accountPublicKey').
  • networkId: string - The network ID.
  • fungible?: string - Optional fungible token name (defaults to 'coin').
  • chainId?: ChainId - Optional chain ID to filter transfers.

Returns:

  • Promise<Transfer[]>: A promise that resolves to an array of transfer objects.

Example:

const transfers = await walletSdk.getTransfers(
  'k:accountPublicKey',
  'testnet04',
);

transfers.forEach((transfer) => {
  console.log(
    `Transfer of ${transfer.amount} from ${transfer.senderAccount} to ${transfer.receiverAccount}`,
  );
});

subscribeOnCrossChainComplete

Subscribes to cross-chain transfer completion events.

Method Signature:

subscribeOnCrossChainComplete(
  accountName: string,
  transfers: ICrossChainTransfer[],
  callback: (transfer: ICrossChainTransfer) => void,
  options?: { signal?: AbortSignal },
): void;

Parameters:

  • accountName: string - The account name associated with the transfers.
  • transfers: ICrossChainTransfer[] - An array of cross-chain transfer objects to monitor.
  • callback: (transfer: ICrossChainTransfer) => void - A function to call when a transfer completes.
  • options?: { signal?: AbortSignal } - Optional settings, including an AbortSignal to cancel the subscription.

Example:

walletSdk.subscribeOnCrossChainComplete(
  'senderAccount',
  [crossChainTransfer1, crossChainTransfer2],
  (transfer) => {
    console.log('Cross-chain transfer completed:', transfer);
  },
);

waitForPendingTransaction

Waits for a pending transaction to be confirmed on the network.

Method Signature:

waitForPendingTransaction(
  transaction: ITransactionDescriptor,
  options?: { signal?: AbortSignal },
): Promise<ResponseResult>;

Parameters:

  • transaction: ITransactionDescriptor - The transaction descriptor to wait for.
  • options?: { signal?: AbortSignal } - Optional settings, including an AbortSignal to cancel the waiting.

Returns:

  • Promise<ResponseResult>: A promise that resolves to the transaction result.

Example:

const result = await walletSdk.waitForPendingTransaction(transactionDescriptor);

if (result.status === 'success') {
  console.log('Transaction confirmed:', result.data);
} else {
  console.error('Transaction failed:', result.error);
}

subscribePendingTransactions

Subscribes to updates for multiple pending transactions.

Method Signature:

subscribePendingTransactions(
  transactions: ITransactionDescriptor[],
  callback: (
    transaction: ITransactionDescriptor,
    result: ResponseResult,
  ) => void,
  options?: {
    signal?: AbortSignal;
    confirmationDepth?: number;
    timeoutSeconds?: number;
    intervalMs?: number;
  },
): void;

Parameters:

  • transactions: ITransactionDescriptor[] - An array of transaction descriptors representing the transactions to monitor.
  • callback: (transaction: ITransactionDescriptor, result: ResponseResult) => void - A function to call when a transaction status updates.
  • options?:
    • signal?: AbortSignal - Optional signal to abort the subscription.
    • confirmationDepth?: number - Optional number of confirmations to wait for (default is 1).
    • timeoutSeconds?: number - Optional timeout in seconds (default is 60 or based on confirmationDepth).
    • intervalMs?: number - Optional polling interval in milliseconds (default is 1000).

Example:

walletSdk.subscribePendingTransactions(
  [transactionDescriptor1, transactionDescriptor2],
  (transaction, result) => {
    if (result.status === 'success') {
      console.log(`Transaction ${transaction.requestKey} confirmed`);
    } else {
      console.error(
        `Transaction ${transaction.requestKey} failed`,
        result.error,
      );
    }
  },
  {
    confirmationDepth: 2,
    timeoutSeconds: 300,
    intervalMs: 2000,
  },
);

Account Information

getAccountDetails

Retrieves detailed information about an account across multiple chains.

Method Signature:

getAccountDetails(
  accountName: string,
  networkId: string,
  fungible: string,
  chainIds?: ChainId[],
): Promise<IAccountDetails[]>;

Parameters:

  • accountName: string - The account name to query (e.g., 'k:accountPublicKey').
  • networkId: string - The network ID.
  • fungible: string - The fungible token name (e.g., 'coin').
  • chainIds?: ChainId[] - Optional list of chain IDs to query.

Returns:

  • Promise<IAccountDetails[]>: A promise that resolves to an array of account details for each chain.

Example:

const accountDetails = await walletSdk.getAccountDetails(
  'k:accountPublicKey',
  'testnet04',
  'coin',
);

accountDetails.forEach((detail) => {
  if (detail.accountDetails) {
    console.log(
      `Chain ${detail.chainId} balance:`,
      detail.accountDetails.balance,
    );
  } else {
    console.log(`Chain ${detail.chainId} has no account details.`);
  }
});

Miscellaneous Functions

getChains

Retrieves the list of chains available on a network.

Method Signature:

getChains(networkHost: string): Promise<IChain[]>;

Parameters:

  • networkHost: string - The network host URL (e.g., 'https://api.testnet.chainweb.com').

Returns:

  • Promise<IChain[]>: A promise that resolves to an array of chain objects, each with an id property.

Example:

const chains = await walletSdk.getChains('https://api.testnet.chainweb.com');

chains.forEach((chain) => {
  console.log('Available chain ID:', chain.id);
});

getNetworkInfo

Retrieves network information.

Method Signature:

getNetworkInfo(networkHost: string): Promise<NodeNetworkInfo>;

Parameters:

  • networkHost: string - The network host URL.

Returns:

  • Promise<NodeNetworkInfo>: A promise that resolves to network information.

Example:

const networkInfo = await walletSdk.getNetworkInfo(
  'https://api.testnet.chainweb.com',
);

console.log('Network Info:', networkInfo);

getGasLimitEstimate

Estimates the gas limit required for a transaction.

Method Signature:

getGasLimitEstimate(
  transaction: ICommand,
  networkId: string,
  chainId: ChainId,
): Promise<number>;

Parameters:

  • transaction: ICommand - The unsigned or signed transaction command to estimate gas for.
  • networkId: string - The network ID.
  • chainId: ChainId - The chain ID where the transaction will be executed.

Returns:

  • Promise<number>: A promise that resolves to the estimated gas limit.

Example:

const gasLimit = await walletSdk.getGasLimitEstimate(
  unsignedTransaction,
  'testnet04',
  '1',
);

console.log('Estimated Gas Limit:', gasLimit);

Extras

Exchange Helper

Provides functionality to retrieve token information from the ETHVM Dev API.

getEthvmDevTokenInfo

Fetches token information such as current price, supply, and 24-hour high/low values.

Method Signature:

getEthvmDevTokenInfo<T extends string>(
  tokens?: T[],
): Promise<Record<T, IEthvmDevTokenInfo | undefined>>;

Parameters:

  • tokens?: T[] - An array of token names as strings (default is ['kadena']).

Returns:

  • Promise<Record<T, IEthvmDevTokenInfo | undefined>>: A promise that resolves to a record mapping token names to their information.

Example:

const tokenInfo = await walletSdk.exchange.getEthvmDevTokenInfo(['kadena']);

console.log('Kadena Token Info:', tokenInfo.kadena);

Kadena Names Service

Provides functions to resolve Kadena names to addresses and vice versa.

nameToAddress

Resolves a Kadena name (e.g., a human-readable name) to a Kadena address.

Method Signature:

nameToAddress(name: string, networkId: string): Promise<string | null>;

Parameters:

  • name: string - The Kadena name to resolve (e.g., 'example.kda').
  • networkId: string - The network ID.

Returns:

  • Promise<string | null>: A promise that resolves to the address or null if not found.

Example:

const address = await walletSdk.kadenaNames.nameToAddress(
  'example.kda',
  'testnet04',
);

if (address) {
  console.log('Resolved address:', address);
} else {
  console.log('No address found for the given name.');
}

addressToName

Resolves a Kadena address to a Kadena name.

Method Signature:

addressToName(address: string, networkId: string): Promise<string | null>;

Parameters:

  • address: string - The Kadena address to resolve (e.g., 'k:accountPublicKey').
  • networkId: string - The network ID.

Returns:

  • Promise<string | null>: A promise that resolves to the name or null if not found.

Example:

const name = await walletSdk.kadenaNames.addressToName(
  'k:accountPublicKey',
  'testnet04',
);

if (name) {
  console.log('Resolved name:', name);
} else {
  console.log('No name found for the given address.');
}

Introduction Text for Wallet SDK Documentation

To explore the capabilities of the Kadena Wallet SDK in action, check out the Wallet SDK Example App. This example app demonstrates every function available in the SDK. It highlights:

  • Usage Examples: See how each function is implemented with real-time code execution.
  • Code Previews: A code highlighter showcases the function being called, the code executed, and its response.
  • Interactive Learning: Learn the SDK features step-by-step while seeing the immediate effects.

Happy Coding!

With the Kadena Wallet SDK and Kadena HD Wallet, you're well-equipped to build powerful and secure wallet applications on the Kadena blockchain. Dive into the documentation, explore the features, and start building today!


Additional Resources