VERSION v0.0.1-alpha.5The BitcoinToken library consists of three classes: BitcoinWallet, BitcoinDb, and BitcoinToken. Below we describe each class and the functions it exposes.
BitcoinWallet is an easy to use wallet that allows you to receive, store, and send Bitcoin Cash.
BitcoinWallet object stores a BIP32 extended private key. This key can be used to generate a private public key pair and a Bitcoin Cash address. Users can send Bitcoin Cash to the address to fund the wallet. The wallet object can compute the balance of the address as well as send bitcoin from it.
In addition, a BitcoinWallet can generate 232 (>4 billion) child BitcoinWallet objects. The child derivation process is recursive and can generate an infinite number of identities. As the process is deterministic, all identities can be recomputed from a single HdPrivateKey.
The functions of a BitcoinWallet object are listed below.
Returns a new BitcoinWallet object with a randomly generated extended private key.
const Bitcoin = require('bitcointoken')
const BitcoinWallet = Bitcoin.Wallet
const randomWallet = new BitcoinWallet()
Generates a string encoding of a hd private key securely from random.
const hdPrivateKey = wallet.getHdPrivateKey()
Type: getHdPrivateKey(): string
Generates a new wallet from a string encoded hd private key. Note that fromHdPrivateKey is static.
const wallet = BitcoinWallet.fromHdPrivateKey(hdPrivateKey)
Type: static fromHdPrivateKey(hdPrivateKey: string): BitcoinWallet
Returns the private key.
const privateKey = wallet.getPrivateKey()
Type: getPrivateKey(): string
Returns the public key.
const publicKey = wallet.getPublicKey()
Type: getPublicKey(): string
Returns the address in cashaddr format. The parameter is optional. If provided, it must be either legacy, bitpay, or cashaddr to indicate the address type.
const address = wallet.getAddress()
Type: getAddress(format: ?('legacy' | 'bitpay' | 'cashaddr')): string
Returns the current balance in satoshi.
const balance = wallet.getBalance()
console.log(`Current balance: ${balance/1e8} bitcoin)
Type: getBalance(): number
Sends bitcoin. The first parameter is the amount to send in satoshi, the second is the recipients address, and the third paramater (which is optional) is the change address. If no change address is provided, the address of the wallet is used.
const address = randomWallet.getAddress()
const id = await wallet.send(15000, address)
Type: async send(amount: number, toAddress: string, changeAddress: ?string): OutputId where outputId is the type {| txId: string, outputNumber: number |}
Deterministically derives a new wallet given an index. The second optional parameter determines if the wallet if hardened or not. Read more about hardened wallets here.
const derivedWallet = wallet.derive(4)
Type: derive(index: ?number = 0, hardened: ?boolean = true): BitcoinWallet
BitcoinDb objects can store data in json format on the Bitcoin Cash blockchain, as well as read and update then.
The storage model of BitcoinDb is designed to work as similar to Bitcoin as possible. In Bitcoin, the current state is stored in the unspent transaction output (utxo) set. The state is updated when a Bitcoin transaction is broadcast. The outputs representing the old state are removed from the utxo set and replaced by the outputs of the transaction that represent the new state.
Similarly, BitcoinDb stores data is unspent transaction outputs. When data is updated, the outputs representing the old state are spent and outputs representing the new state are created. The convention is that the i-th output represents the new state of the i-th input being spent. This leads to a natural notion of data ownership where the data is owned by the users(s) that can spend and thereby update the output that contains the data.
The location on the blockchain where data is stored is captured by an OutputId object, which contains two keys txId and outputNumber (that is an OutputId object has type {| txId: string, outputNumber: number |}) in flow type notation).
Returns a new BitcoinDb object that stores a randomly generated BitcoinWallet object. The wallet is used to pay for fees when storing data on the blockchain.
const Bitcoin = require('bitcointoken')
const BitcoinDb = Bitcoin.Db
const randomDb = new BitcoinDb()
BitcoinDb object from an existing BitcoinWallet object.
const Bitcoin = require('bitcointoken')
const wallet = new Bitcoin.Wallet()
const db = new Bitcoin.Db(wallet)
Generates a new BitcoinDb object from a string encoded hd private key. This essentially calls fromHdPrivateKey on the associated BitcoinWallet.
const db = BitcoinDb.fromHdPrivateKey(hdPrivateKey)
Type: static fromHdPrivateKey(hdPrivateKey: string): BitcoinDb
Stores a json object on the Bitcoin Cash blockchain. The simplest way to use it is to pass in a json object:
const id = await db.put({ key: 'string value'})
The data is encoded and stored in a data output script. The user(s) that can spend the output is the only person that can update that data. We call those user(s) the owner(s) of the data. By default the user to issue the command is the owner, to designate a different owner, pass in that users public key as the second argument.
const publicKey = randomWallet.getPublicKey()
const id = await db.put({ key: 'string value'}, [publicKey])
The third argument is an amount of satoshi that will be stored in the output containing the data. For example, to store 1 Bitcoin with the data you could use
const publicKey = randomWallet.getPublicKey()
const id = await db.put({ key: 'string value'}, [publicKey], 1 * 1e8)
The return value is a promise that resolves to an OutputId of flow type {| txId: string, outputNumber: number |}. For example, the return value id will be structured like this:
{
txId: '00000000c686665a0976be01c4ebebbc1043be27edcaed014c6ba123c49e1c73',
outputNumber: 0
}
Type: async put(data: object, owners?: Array<string>, amount?: number = DEFAULT_FEE): Promise<OutputId>
Note: We currently only support storing objects that have string keys and string values of flow type { [string]: string }. Also the strings much be relatively short (around 300 characters). Please let us know if your application needs to store bigger documents and we will add support for that.
Retrieves a json object from the Bitcoin Cash blockchain given an OutputId object that specifies a location on the blockchain.
const id = BitcoinDb.put({ key: 'value' })
const data = BitcoinDb.get(id)
The return value is of type OutputData which is an object with three keys: data containing the data stored at the provided OutputId, data containing a list of string encoded public keys that correspond to the owners, and amount which is the number of satoshis stored in that output.
Type: async get(outputId: OutputId): Promise<OutputData> where OutputData is of type {| data: object, owners: Array<string>, amount: number |}
Updates an object stored on the blockchain. To do so it spends the output containing the data into a new output containing the updated data. The first parameter is the OutputId of the output containing the data that is to be updates, the second parameter is the new data. The return value resolves to the OutputId of the new output being created.
const id1 = BitcoinDb.put({ old: 'value' })
const id2 = await BitcoinDb.update(id1, { new: 'value'})
There are two optional parameters "owners" and "amount" that act just like the optional parameters of db.put.
const publicKey = randomWallet.getPublicKey()
const id1 = BitcoinDb.put({ old: 'value' })
const id2 = await BitcoinDb.update(id, { new: 'value'}, [publicKey], 1 * 1e8)
Type: async update(outputId: OutputId, data: object, owners: Array<string>, amount?: number = DEFAULT_FEE): Promise<OutputId>
BitcoinToken objects can issue a token and send them to another user. It can also return the current balance in tokens.
Returns a new BitcoinToken object that stores a randomly generated BitcoinDb object. The wallet is used to pay for fees when storing data on the blockchain.
const Bitcoin = require('bitcointoken')
const BitcoinDb = Bitcoin.Db
const randomDb = new BitcoinDb()
BitcoinToken object from an existing BitcoinDb object.
const Bitcoin = require('bitcointoken')
const BitcoinDb = Bitcoin.Db.fromHdPrivateKey(hdPrivateKey)
const randomDb = new BitcoinDb()
const token = new BitcoinToken(db)
Generates a new BitcoinToken object from a string encoded hd private key. This essentially calls fromHdPrivateKey on the associated BitcoinDb.
const token = BitcoinToken.fromHdPrivateKey(hdPrivateKey)
Type: static fromHdPrivateKey(hdPrivateKey: string): BitcoinToken
Issues a new fungible token, similar to ERC20 tokens on Ethereum. The parameter must be an object that can be passes into BitcoinDb.put. That is a json object with string keys and string values. It must have one key balance whose value indicates the initial number of tokens.
const tokenId = await token.create({
balance: '10',
name: 'my-token',
url: 'www.mytoken.com',
})
Type: async create(data: { [string]: string }): Promise<OutputId>
Joins an existing token. This means that the balance will be calculated with respect to the token being joined.
const tokenAlice = new Token()
const tokenBob = new Token()
const tokenId = await tokenAlice.create({ balance: '10' })
tokenBob.join(id)
Type: join(id: OutputId): void
Sends tokens to another user. The first parameter is the number of tokens to send and the second is the public key of the receipient
const Bitcoin = require('bitcointoken')
const tokenAlice = new Bitcoin.Token()
const walletBob = new Bitcoin.Wallet()
const dbBob = new Bitcoin.Db(walletBob)
const tokenBob = new Bitcoin.Token(dbBob)
const publicKeyBob = walletBob.getPublicKey()
const tokenId = await tokenAlice.create({ balance: '10' })
tokenBob.join(tokenId)
tokenAlice.send(1, publicKeyBob)
Type: send(amount: number, publicKey: string): Promise<Array<OutputId>>