Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@coolwallets/devices

CoolBitX-Technology117Apache-2.00.0.12TypeScript support: included

devices layer for coolwallets.

readme

CoolWallet Javascript SDK

JavaScript SDK to communicate with CoolWallet.

This is the monorepo of all the packages you need to build your own app with CoolWallet hardware wallet.

Quick Start

1. Define your transport layer

Depending on your platform, you may choose different transport object to use in your application.

2. Register and setup hardware wallet.

To register your application with the wallet, take a look at the wallet module in core package. This guide you through the process of registration and seed generation.

3. Build your Application

Take a look at all the supported modules at Coin Apps. Used the keys generated in the previous step to initiate coin instances, then you can sign transactions, message with different coin instances.

Packages

Transport

Connect to a CoolWallet device by specifying the transport: bluetooth or nfc.

Package Version Description
@coolwallet/transport-web-ble version Web Bluetooth transport
@coolwallet/transport-react-native-ble version React-Native Bluetooth transport
@coolwallet/transport-react-native-nfc version React-Native NFC transport

Core

Package Version Description
@coolwallet/core version APDU commands, default encryptions and keypair generation for other SDKs.

Coin Apps

Used to sign transactions of different cryptocurrencies.

Package Version Coin Name
@coolwallet/ada version Cardano
@coolwallet/aptos version Aptos
@coolwallet/atom version Cosmos
@coolwallet/bch version Bitcoin Cash
@coolwallet/bsc version Binance Smart Chain
@coolwallet/btc version Bitcoin/USDT
@coolwallet/cro version Crypto.org
@coolwallet/cronos version Cronos
@coolwallet/doge version Doge
@coolwallet/dot version Polkadot/Kusama
@coolwallet/etc version Ethereum Classic
@coolwallet/eth version Ethereum
@coolwallet/evm version Some EVM coins
@coolwallet/icx version Icon
@coolwallet/kas version Kaspa
@coolwallet/ltc version LiteCoin
@coolwallet/sol version Solana
@coolwallet/sui version Sui
@coolwallet/terra version Terra
@coolwallet/ton version The Open Network
@coolwallet/trx version Tron
@coolwallet/xlm version Stellar/Kinesis
@coolwallet/xrp version Ripple
@coolwallet/xtz version Tezos
@coolwallet/zen version Zen Cash

Examples: Connect to CoolWallet and Build ETH App

To communicate with a CoolWallet device, you must choose one transport method depending on your platform and device model:

  • Web BLE (CoolWallet Pro on web browsers)

  • React Native BLE (CoolWallet Pro on mobile apps)

  • React Native NFC (CoolWallet Go on mobile apps)

Each method allows you to connect to the card and retrieve the Card Name or Card ID and SE Public Key.

Option 1: Web BLE (CoolWallet Pro on Web)

npm install @coolwallet/core
npm install @coolwallet/transport-web-ble
import WebBleTransport from "@coolwallet/transport-web-ble";
import * as core from "@coolwallet/core";

connect = async () => {
WebBleTransport.listen(async (error, device) => {
    const cardName = device.name;
    const transport = await WebBleTransport.connect(device);
    const SEPublicKey = await core.config.getSEPublicKey(transport);
    this.setState({ transport, cardName, SEPublicKey });
    localStorage.setItem('cardName', cardName)
    localStorage.setItem('SEPublicKey', SEPublicKey)
  });
};

disconnect = () => {
  WebBleTransport.disconnect(this.state.transport.device.id);
  this.setState({ transport: undefined, cardName: "" });
};

Option 2: React Native BLE (CoolWallet Pro on Mobile)

npm install @coolwallet/core
npm install @coolwallet/transport-react-native-ble
import RNBleTransport from '@coolwallet/transport-react-native-ble'
import { confing, info } from '@coolwallet/core';

const transport =  RNBleTransport.connect(deviceOrId);
const cardId = await info.getCardId(transport);
const SEPublicKey = await core.config.getSEPublicKey(transport);

Option 3: React Native NFC (CoolWallet Go on Mobile)

npm install @coolwallet/core
npm install @coolwallet/transport-react-native-nfc
import NFCTransport from '@coolwallet/transport-react-native-nfc';
import { confing, info } from '@coolwallet/core';

const transport = new NfcTransport();
const cardId = await info.getCardId(transport);
const SEPublicKey = await core.config.getSEPublicKey(transport);

Notes

  • transport: The communication bridge between your app and the CoolWallet device.
  • SEPublicKey: The Secure Element's public key, used for card authentication.
  • cardName or cardId: The identifier of the connected card.

Register application with CoolWallet Device

Obtain app key pairs.

const keyPair = crypto.key.generateKeyPair()
localStorage.setItem('appPublicKey', keyPair.publicKey)
localStorage.setItem('appPrivateKey', keyPair.privateKey)
  • keyPair: The keys use to check your app.

Register card and obtain the appId.

const name = 'your app name'
const SEPublicKey = localStorage.getItem('SEPublicKey')
const appId = await apdu.pair.register(transport, appPublicKey, password, name, SEPublicKey);
  • password: Pairing password for the app to establish the connection with CoolWallet Device. The password could be supplied by the user (max length: 8).

NOTE: A single CoolWallet Device could only be paired to 3 apps.

Create / Recover the wallet

Use function setSeed to create or recover your wallet.

const seedHex = bip39.mnemonicToSeedSync(mnemonic).toString('hex');
await apdu.wallet.setSeed(transport, appId, appPrivateKey, seedHex, SEPublicKey)

If you want to create seed by card, you can use function createSeedByCard. And also choose the length of seed(12, 18, 24).

await apdu.wallet.createSeedByCard(transport, appId, appPrivateKey, 12);

Use coin app

npm install @coolwallet/eth
import cwsETH from '@coolwallet/eth'

const ETH = new cwsETH();

Get Address

const address = await ETH.getAddress(
  transport,
  appPrivateKey,
  appId,
  addressIdx
); 

The address generated is compatible to BIP44 with account and change set to 0, which means calling getAddress(i) will get the address of following BIP44 path:

m/44'/60'/0'/0/{i}

In the design of current hardware, we only support path m/44'/60'/0'/0/{i} for speed optimization. This might change in the future and we will then open a more general interface to deal with custom path.

If you have accountPublicKey and accountChainCode, you can use the function ETH.getAddressByAccountKey() to get the address.

const address = await ETH.getAddressByAccountKey(
  accountPublicKey,
  accountChainCode,
  addressIndex
);

Sign Transaction

The signedTx is signed by CoolWallet, which can be sent directly.

const transaction = {
    nonce: "0x21d",
    gasPrice: "0x59682f00",
    gasLimit: "0x5208",
    to: "0x81bb32e4A7e4d0500d11A52F3a5F60c9A6Ef126C",
    value: "0x5af3107a4000",
    data: "0x00",
    chainId: 1
};
const signTxData = {
  transport,
  appPrivateKey,
  appId,
  transaction,
  addressIndex,
};

const signedTx = await ETH.signTransaction(signTxData);

Scripts

  • bootstrap: Initialize monorepo environment with lerna.
  • build: Build all packages.
  • clean: Remove all packages's node_modules.
  • ci: Script for CI.
  • update:lock: Update package-lock.json information.

Contributing

If you're interested to develop new coin for CoolWallet Device, please see CONTRIBUTING for more information.