Local-Koinos

Local-Koinos is a set of scripts and tools that will help you spin up a devnet on your local machine in minutes.

Install Docker (and Docker-Compose)

You will need to install Docker on MacOS, Linux or Windows first. You can follow their instructions for installation here. Docker desktop comes with a recent version of docker-compose, but make sure it's at least docker-compose v2.

Installation

# with npm
npm install -g @roamin/local-koinos

# with yarn
yarn global add @roamin/local-koinos

Usage as CLI

# start a local Koinos devnet (default mode is "auto")
# there are 3 modes available:
# - auto: produces a block every time you submit a transaction to the mempool
# - interval: creates a block every X seconds with all transactions available in the mempool (default is every 3 seconds)
# - manual: awaits for blocks to be manually submitted to the chain
# a local JSON RPC service will be available by default at http://127.0.0.1:8080
local-koinos start

# stop the node
local-koinos stop

Example of programmatic usage using JavaScript/TypeScript

import { LocalKoinos, Token, Signer } from '@roamin/local-koinos';

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore 
import * as abi from './calculator-abi.json';

// @ts-ignore koilib_types is needed when using koilib
abi.koilib_types = abi.types

const localKoinos = new LocalKoinos();

// start local-koinos node
await localKoinos.startNode();
// start block production in auto mode (a block gets produced every time you submit a transaction)
await localKoinos.startBlockProduction();

// deploy the Koin contract
await localKoinos.deployKoinContract();

// mint 50,000 Koin tokens to 10 accounts
await localKoinos.mintKoinDefaultAccounts();

// get the accounts initialized with `mintKoinDefaultAccounts`
const [genesis, koin, acct1] = localKoinos.getAccounts();

// deploy a contract to the devnet (returns an instance of a Koilib Contract)
const contract = await localKoinos.deployContract(acct1.wif, './calculator-contract.wasm', abi);

// call your contract functions
const { result } = await contract.functions.add({ x: '4', y: '5' });
expect(result!.value).toBe('9');

// stop local-koinos node
await localKoinos.stopNode();

Example of programmatic usage using Jest

local-koinos/tests/tests.spec.ts

Lines 1 to 59 in 0ddc2bf

	import { LocalKoinos, Token, Signer } from '../lib';
	// eslint-disable-next-line @typescript-eslint/ban-ts-comment
	// @ts-ignore
	import * as abi from './calculator-abi.json';
	// @ts-ignore koilib_types is needed when using koilib
	abi.koilib_types = abi.types
	jest.setTimeout(600000);
	const localKoinos = new LocalKoinos();
	beforeAll(async () => {
	// start local-koinos node
	await localKoinos.startNode();
	await localKoinos.startBlockProduction();
	await localKoinos.deployKoinContract();
	await localKoinos.mintKoinDefaultAccounts();
	});
	afterAll(async () => {
	// stop local-koinos node
	await localKoinos.stopNode();
	});
	test("test1", async () => {
	const [genesis, koin, acct1] = localKoinos.getAccounts();
	// @ts-ignore abi provided here is compatible with Koilib
	const contract = await localKoinos.deployContract(acct1.wif, './tests/calculator-contract.wasm', abi);
	const { result } = await contract.functions.add({ x: '4', y: '5' });
	expect(result!.value).toBe('9');
	const signer = Signer.fromWif('L59UtJcTdNBnrH2QSBA5beSUhRufRu3g6tScDTite6Msuj7U93tM');
	signer.provider = localKoinos.getProvider();
	let tkn = new Token(localKoinos.koin.address(), signer);
	try {
	await tkn.mint(signer.address, 40);
	} catch (error) {
	// @ts-ignore
	expect(error.message).toContain('can only mint token with contract authority');
	}
	try {
	const signer2 = Signer.fromWif('5KL5GNq42Syr52dUUi4UhQ5cANwNr9xgxKivF9YjtGdM7BBjuks');
	signer2.provider = localKoinos.getProvider();
	tkn = new Token(localKoinos.koin.address(), signer2);
	const { transaction, receipt } = await tkn.transfer(signer2.address, signer.address, 40000000000000000);
	await transaction!.wait();
	} catch (error) {
	// @ts-ignore
	expect(error.message).toContain("account 'from' has insufficient balance");
	}
	});