CoolWallet Cardano SDK

Typescript library with support for the integration of Cardano for third party application, include the functionalities of generation of addresses and signed transactions.

Updates

1. Support combined register and delegate in single transaction.
2. Support testnet address.

Install

npm install @coolwallet/ada

Usage

import ADA, { TransferWithoutFee, Options } from '@coolwallet/ada';

const ada = new ADA();
const acckey = await ada.getAccountPubKey(transport, appPrivateKey, appId);
const address = ada.getAddressByAccountKey(acckey, addressIndex);

const rawTx = {
  addrIndexes: [0],
  inputs: [{
    txId: '0x8561258e210352fba2ac0488afed67b3427a27ccf1d41ec030c98a8199bc22ec',
    index: 0,
  }],
  output: {
    address: 'addr1qxn5anyxv6dhtl57yvgvpp25emy0pc9wenqzzemxktyr94ahaaap0f0tn4wxaqsydnzty2m0y4gfeu39ckjvsjycs4nssxhc25',
    amount: 10523059,
  },
  change: {
    address: 'addr1q8wyqhxud34ejxjm5tyj74qeuttr7z9vnjuxy6upyn2w8ryau3fvcuaywgncvz89verfyy24vverl9pw2h5uwv30aq9qm6xj7s',
    amount: 360000,
  },
  ttl: '0x641a5',
};

const transferTxSize = await ada.getTransactionSize(rawTx);

const fee = a * transferTxSize + b;
const transaction = {
  fee,
  ...rawTx
};
const options = { transport, appPrivateKey, appId };

const signedTx = await ada.signTransaction(transaction, options);

Methods

getAccountPubKey

Arguments

| Arg | Description | Type | Required | |:-------------:|:--------------------------------------------:|:---------:|:---------:| | transport | Object to communicate with CoolWallet device | Transport | True | | appPrivateKey | Private key for the connected application | string | True | | appId | ID for the connected application | string | True |

Description

Cardano is using BIP32-Ed25519 and not standard BIP32. Because BIP32-Ed25519 has similar path structure to BIP32, we can still acquire the account public key and use it to generate addresses avoiding exposuring the private keys. Read CIP-1852 to understand the key deriving.

m / 1852' / 1815' / 0'

getAddressByAccountKey

Arguments

| Arg | Description | Type | Required | |:-------------:|:---------------------------------------:|:---------:|:---------:| | acckey | The account key from getAccountPubKey | string | True | | addressIndex | The address index | number | True |

Description

The Cardano address format is combined with different part. Payment part indicates the ownership of the funds associated with the address. Delegation part indicates the owner of the stake rights associated with the address. Read CIP-0019 to understand the address encoding.

Payment key: m / 1852' / 1815' / 0' / 0 / 0
Staking key: m / 1852' / 1815' / 0' / 2 / 0 <- index always be 0

getTransactionSize

Arguments

| Arg | Description | Type | Required | |:-------------:|:----------------------------------------:|:------------------:|:---------:| | transaction | Cardano transaction without fee | RawTransaction | True | | txType | Cardano transaction type | TxTypes | True |

export type Integer = string | number;

export enum TxTypes {
  Transfer,
  StakeRegister,
  StakeDelegate,
  StakeDeregister,
  StakeWithdraw,
  StakeRegisterAndDelegate,
}

export interface Input {
  txId: string;
  index: Integer;
}

export interface Output {
  address: string;
  amount: Integer;
}

export interface RawTransaction {
  addrIndexes: number[];
  inputs: Input[];
  change?: Output;
  ttl: Integer;
  output?: Output;
  poolKeyHash?: string;
  withdrawAmount?: Integer;
}

Description

Get Cardano Transaction size for ADA transfer. This method is for fee calculating. The a and b parameters can be fetched via Latest epoch protocol parameters API.

Fee = a * size(tx) + b

References:

• TTL (Time to live) : latest slot + N slots
• Get latest slot : https://cardano-mainnet.blockfrost.io/api/v0/blocks/latest
• https://iohk.io/en/blog/posts/2022/01/21/plutus-fee-estimator-find-out-the-cost-of-transacting-on-cardano/
• https://mantis.functionally.io/how-to/min-ada-value/
• https://docs.cardano.org/native-tokens/minimum-ada-value-requirement

signTransaction

Arguments

| Arg | Description | Type | Required | |:-----------:|:---------------------------------------------------------:|:--------:|:---------:| | transaction | Essential information/property for Cardano Transaction | Transfer | True | | options | Arguments for coolwallet communication and authentication | Options | True | | txType | Cardano transaction type | TxTypes | True |

export interface Options {
  transport: Transport;
  appPrivateKey: string;
  appId: string;
  confirmCB?: Function;
  authorizedCB?: Function;
}

export interface Transaction extends RawTransaction {
  fee: Integer;
}

Description

Sign Cardano Transaction for ADA transfer.

Error Messages

| Submit tx error messages | Description | |:---------------------------:|:------------------------------------------:| | ValueNotConservedUTxO | outputs and fee is not equal to utxos | | BadInputsUTxO | utxo not found | | FeeTooSmallUTxO | fee small than a * size + b | | OutsideValidityIntervalUTxO | ttl small than latest Slot | | OutputTooSmallUTxO | output amount less than 999978 | | MissingVKeyWitnessesUTXOW | signature verifying failure | | DelegsFailure | 沒有 Reward，但嘗試用 Withdraw 取值 |

Staking

Get account info by stake addresss

https://docs.blockfrost.io/#tag/Cardano-Accounts

{
  "stake_address": "stake1ux3g2c9dx2nhhehyrezyxpkstartcqmu9hk63qgfkccw5rqttygt7",
  "active": true,
  "active_epoch": 412,
  "controlled_amount": "619154618165",
  "rewards_sum": "319154618165",
  "withdrawals_sum": "12125369253",
  "reserves_sum": "319154618165",
  "treasury_sum": "12000000",
  "withdrawable_amount": "319154618165",
  "pool_id": "pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy"
}

State Diagram

stateDiagram-v2
    get_account_info --> active=false
    get_account_info --> pool_id
    get_account_info --> withdrawable_amount
    active=false --> active=true : Register
    active=true --> active=false : Deregister

    pool_id --> null
    pool_id --> has_value
    null --> new_pool_id : Delegate
    has_value --> new_pool_id : Delegate

    withdrawable_amount --> has_amount
    has_amount --> remaining_withdrawable_amount : Withdraw

Tx Interfaces Requirement

Transfer

interface RawTransaction {
  addrIndexes: number[];
  inputs: Input[];
  change?: Output;
  ttl: Integer;
  output: Output;
}

Stake Register

interface RawTransaction {
  addrIndexes: number[];
  inputs: Input[];
  change?: Output;
  ttl: Integer;
}

Stake Delegate

interface RawTransaction {
  addrIndexes: number[];
  inputs: Input[];
  change?: Output;
  ttl: Integer;
  poolKeyHash: string;
}

Stake Deregister

interface RawTransaction {
  addrIndexes: number[];
  inputs: Input[];
  change?: Output;
  ttl: Integer;
}

Stake Withdraw

interface RawTransaction {
  addrIndexes: number[];
  inputs: Input[];
  change: Output;
  ttl: Integer;
  withdrawAmount: Integer;
}