@iov/core
@iov/core is the main entrypoint into the monorepo, exposing high-level functionality
to easily build blockchain clients. It uses the keymanagement functionality of UserProfile
,
and the generic blockchain connection of BlockchainConnection
, and pulls them together into one
MultiChainSigner
, which can query state and sign transactions on multiple blockchains.
The examples below show a basic usage of the core library. You may also want to experiment
with @iov/cli
as a developer tool to familiarize yourself with this functionality.
Full Api Docs
Full API Docs from the latest release are hosted at: https://iov-one.github.io/iov-core-docs/
If you want to generate documentation for a development branch, please run yarn docs
in the
current directory and go to docs/index.html.
Examples
Here are some example use cases. They all build on each other and assume
all imports from above. I also use await
syntax here, which works inside of async
functions and experimentally in the @iov/cli REPL.
(All imports are done for you in the REPL as well, so you can skip the import
statements. They are provided for guidance when integrating into your own codebase).
Before starting, either run from source in ../iov-cli
via yarn build && ./bin/iov-cli
or install from npm via npm install -g @iov/cli; iov-cli
.
Inside the cli the remaining code should work verbatim.
Key Management
Create a random mnemonic:
import { Bip39, Random } from '@iov/crypto';
// 16 bytes -> 12 word phrase
const entropy16 = await Random.getBytes(16);
const mnemonic12 = Bip39.encode(entropy16).toString();
console.log(mnemonic12);
// 32 bytes -> 24 word phrase
const entropy32 = await Random.getBytes(32);
const mnemonic24 = Bip39.encode(entropy32).toString();
console.log(mnemonic24);
Create a new profile with two wallets:
import { Ed25519HdWallet, UserProfile } from '@iov/keycontrol';
const profile = new UserProfile();
const wallet1 = profile.addWallet(Ed25519HdWallet.fromMnemonic(mnemonic12));
const wallet2 = profile.addWallet(Ed25519HdWallet.fromMnemonic(mnemonic24));
Inspect the profile:
// look at profile (value reads current state)
console.log(profile.wallets.value);
// listen to the profile (stream of updates, good for reactive UI)
const sub = profile.wallets.updates.subscribe({ next: wallets => console.log(wallets) });
profile.setWalletLabel(wallet1.id, "12 words");
profile.setWalletLabel(wallet2.id, "24 words");
Create identies on the two wallets:
import { ChainId } from '@iov/bcp';
import { HdPaths } from '@iov/keycontrol';
import { Encoding } from '@iov/encoding';
const { fromHex, toHex } = Encoding;
const chainId = 'bov-hugnet' as ChainId;
// this creates two different public key identities, generated from the
// first mnemonic using two different SLIP-0010 paths
const id1a = await profile.createIdentity(wallet1.id, chainId, HdPaths.iov(0));
const id1b = await profile.createIdentity(wallet1.id, chainId, HdPaths.iov(1));
console.log(id1a);
console.log(id1a.pubkey.algo, toHex(id1a.pubkey.data))
console.log(id1b.pubkey.algo, toHex(id1b.pubkey.data))
// this creates a different key from the second mnemonic,
// this uses the same HD path as id1a, but different seed.
const id2 = await profile.createIdentity(wallet2.id, chainId, HdPaths.iov(0));
console.log(id2.pubkey.algo, toHex(id2.pubkey.data));
// we can also add labels to the individual identies
profile.setIdentityLabel(id1a, 'main account');
console.log(profile.getIdentities(wallet1.id));
Save and reload keyring:
const levelup = require('levelup');
// this is for local leveldb in node
const leveldown = require('leveldown');
// use this for indexdb storage in browser
// const browsedown = require('browsedown');
const db = levelup(leveldown('./my_secret_keys'));
// const db = levelup(browsedown('keystore'));
const passphrase = "is seven words enough for the checker?"
await profile.storeIn(db, passphrase);
// this throws an error:
// await UserProfile.loadFrom(db, "garbage");
const loaded = await UserProfile.loadFrom(db, passphrase);
// and we have the same data
console.log(loaded.wallets.value);
const ids = profile.getIdentities(loaded.wallets.value[0].id);
console.log(ids);
console.log(toHex(ids[0].pubkey.data));
console.log(toHex(id1a.pubkey.data));
Interacting with BCP Blockchain
The main use of private keypairs is not just to generate and organize them,
but to actually sign transactions (or encrypt/decrypt messages... not there yet).
To demonstrate this part, we need a working blockchain. If you are ambitious,
you can check out bcp-demo, and build
the bov
and tendermint
binaries, construct your genesis file and run
the client against your one-node "dev net"...
But, if you just want to see how the client works, let's run against iov's testnet and use the faucet to get some tokens. As of February 27, 2019, the current testnet is located at https://bov.hugnet.iov.one/.
To connect, you need to know the address of the rpc server (above).
It is also helpful to know the chainId
of the chain.
You can find that quite easily by looking
at the genesis file under
.result.genesis.chain_id
. In our case this is bov-hugnet
.
Executing the commands
Discover the address for your identity. This is chain-dependent, so we need
to use the chain-dependent TxCodec
to generate it. In our case, bnsCodec:
import { bnsCodec } from '@iov/bns';
const addr = bnsCodec.identityToAddress(id1a);
console.log(addr);
If you are running your own "dev-net" give that address plenty of tokens
in the genesis file, by running bov init IOV $ADDR
.
Now, connect to the network:
import { bnsConnector, MultiChainSigner } from '@iov/core';
const signer = new MultiChainSigner(profile);
await signer.addChain(bnsConnector('wss://bov.hugnet.iov.one/'));
console.log(signer.chainIds()[0]); // is this what you got yourself?
List the tokens on the network:
const connection = signer.connection(chainId);
const tokens = await connection.getAllTokens();
console.log(tokens);
Query the testnet for some existing genesis accounts:
// this is pulled from the genesis account
import { Address } from "@iov/bcp"
const bert = "tiov1u29wnfhtjn7g3de7kl9adwrmlyltn0hsjckecc" as Address;
const acct = await connection.getAccount({ address: bert });
console.log(acct);
If you are running the testnet faucet, just ask for some free money.
import { TokenTicker } from "@iov/bcp";
import { IovFaucet } from "@iov/faucets";
const faucet = new IovFaucet("https://bov-faucet.hugnet.iov.one/");
await faucet.credit(addr, "ALT" as TokenTicker);
Then query your account:
const mine = await connection.getAccount({ address: addr });
console.log(mine); // should show non-empty array for balance
console.log(mine.balance[0]);
const addr2 = bnsCodec.identityToAddress(id2);
console.log(addr2);
let yours = await connection.getAccount({ address: addr2 });
console.log(yours); // should be undefined
Send a transaction to second id:
import { SendTransaction, TokenTicker } from "@iov/bcp"
const sendTx: SendTransaction = {
kind: "bcp/send",
creator: id1a, // this account must have money
recipient: addr2,
memo: "My first transaction",
amount: { // 10.11 ALT (9 sig figs in tx codec)
quantity: '10110000000',
fractionalDigits: 9,
tokenTicker: "ALT" as TokenTicker,
},
};
// we must have the private key for the transaction creator (id1a)
await signer.signAndPost(sendTx);
// and we have a balance on the recipient now
yours = await connection.getAccount({ address: addr2 });
console.log(yours); // should show non-empty array for balance
console.log(yours.balance[0]);
Now, query the transaction history:
const history = await connection.searchTx({ sentFromOrTo: addr2 });
console.log(history);
const first = history[0].transaction as SendTransaction;
console.log(first.amount);
// address of recipient
console.log(toHex(first.recipient));
// public key of sender
console.log(toHex(first.signer.data));
// address of sender
const sender = bnsCodec.identityToAddress(first);
console.log(sender);
Reactive Clients
If you query, the data can get stale, and you may be tempted to start polling the blockchain. Don't! Instead we offer event streams for anyone wishing to generate a reactive application. You can simply log these values, or feed them into a reducer to capture their value.
// these are helpers for consuming streams
// lastValue will always store the last value,
// asArray will append to an array with list of all tx that were streamed
import { asArray, lastValue } from '@iov/stream';
const liveHeight = lastValue(client.watchBlockHeaders().map(header => header.height));
// if you wait a few seconds, you should see the block-height increase
console.log(liveHeight.value());
console.log(liveHeight.value());
console.log(liveHeight.value());
// you can also watch an account balance
const liveBalance = lastValue(client.watchAccount({address: addr}));
console.log(liveBalance.value());
// or a list of all transactions that touch this account
const liveTx = asArray(client.liveTx({address: addr}));
console.log(liveTx.value());
Now, go ahead, send some tokens to this account in another window, and read the value of the account and tx again, watch them grow.
License
This package is part of the IOV-Core repository, licensed under the Apache License 2.0 (see NOTICE and LICENSE).