# bitsim
> bitcoin node simulator controller
Latest version **0.0.15** (published 2020-06-25) · MIT license · 0 weekly downloads
## Install
```sh
npm install bitsim
pnpm add bitsim
yarn add bitsim
bun add bitsim
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.0.15 |
| Published | 2020-06-25 |
| First published | 2020-06-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 10.1 KB |
| Known vulnerabilities | 0 (+25 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | gw0lf3 |
| Keywords | bitcoin, forge, build |
## Links
- npm: https://www.npmjs.com/package/bitsim
- npm.io page: https://npm.io/package/bitsim
## Dependencies (3)
- [bsv](https://npm.io/package/bsv.md) ^1.5.3
- [axios](https://npm.io/package/axios.md) ^0.19.2
- [toychain](https://npm.io/package/toychain.md) 0.0.22
## Alternatives
- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads
## Recent versions
- 0.0.15 (latest) — 2020-06-25
- 0.0.14 — 2020-06-24
- 0.0.13 — 2020-06-13
- 0.0.12 — 2020-06-10
- 0.0.11 — 2020-06-10
- 0.0.10 — 2020-06-10
- 0.0.8 — 2020-06-10
- 0.0.7 — 2020-06-10
- 0.0.6 — 2020-06-10
- 0.0.5 — 2020-06-10
- 0.0.4 — 2020-06-10
- 0.0.3 — 2020-06-10
- 0.0.2 — 2020-06-10
- 0.0.1 — 2020-06-08
## README
## bitsim
bitcoin simulator
### about
bitsim is the controller for the your bitcoin simulation environment. it works with the bitsim docker image.
### prerequisites
- [docker](https://docs.docker.com/get-docker/)
- nodejs
### manual
#### installation
```
npm i --save bitsim
```
#### start the console
##### single-player mode
```
docker run --name bitsim -d -p 18332-18333:18332-18333 -p 18444:18444 planaria/bitsim:0.0.1
```
##### multi-player mode ( *COMING SOON* )
```
curl https://raw.githubusercontent.com/interplanaria/bitsim/master/docker-compose.yml > docker-compose.yml && docker-compose up -d
```
#### play the demo
##### 1) enter NodeJS REPL
```bash
node
```
> for more information on how to use NodeJS REPL, see the [docs](https://nodejs.org/api/repl.html)
> we will be using [`.then` syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) to read the callbacks in realtime without async scope. it's worht noting that ordinarily, you'd probably want to use async/await.
##### 2) initialize new Bitsim controller
```javascript
const Bitsim = require('bitsim')
const bitsim = new Bitsim()
```
##### 3) mine some blocks
```javascript
// mine a single block
bitsim.mine().then(r => console.log(r))
// mine 5 blocks
bitsim.mine(5).then(r => console.log(r))
// check status (most recent block header)
bitsim.last().then(r => console.log(r))
```
##### 4) submit transactions
```javascript
// initial fund step (more details below)
bitsim.init().then(r => console.log(r))
// add 10 "default" data transactions (more details below)
bitsim.add(10)
// add 1000 data transactions
bitsim.add(1000)
// add 100 custom data transaction
let dataOut = [ { "o0": "OP_0", "o1": "OP_RETURN", "s2": "Hello My Custom Transaction" } ]
bitsim.add(100, dataOut)
// check the mempool
bitsim.getMempoolInfo().then(r => console.log(r))
```
> NOTE: initial funding requires mining 100 blocks to make the coinbase bitcoin eligible for spending. this coinbase transaction is used to fund a local toychain which builds and submits to the Bitsim peer.
> NOTE: the term "default transaction" refers to the default prototype data out transaction provided by the Bitsim library.
##### 5) create a fork
```javascript
// get the last block header
let lastHeight;
bitsim.getLatestHeader().then(r => console.log(r); lastHeight = r.height; )
// create a fork 3 blocks back
bitsim.fork(lastHeight - 3)
// get the new last block header
let newHeight
bitsim.getLatestHeader().then(r => console.log(r); newHeight = r.height; )
```
#### learn the controls
##### initialize
```javascript
const Bitsim = require('bitsim')
const bitsim = new Bitsim()
```
##### core methods
```javascript
;(async()=>{
await bitsim.init()
// initializes and bootstraps toychain
// 1. funds toychain with coinbase tx
// 2. mines 100 blocks so those coin are spendable
// 3. bootstraps tx tree to avoid mempool limit
await bitsim.last()
// returns last block header from node
await bitsim.mine(n, address)
// mines `n` number of blocks to `address`
// parameters are optional. will use default if blank
await bitsim.add(n, prototype)
// adds `n` data-only transactions to mempool with prototype (output array)
await bitsim.fork(height)
// creates fork at given block `height` by invalidating `height + 1`
await bitsim.rpc(method, [params])
// return arbitrary rpc method response. accepts array of params or no params
})()
```
##### convenience methods
```javascript
;(async()=>{
await bitsim.getRandomBlock(max)
// provides random block height and hash from chain within limit
// useful for creating tests
await bitsim.getLatestHeader()
// wrapper for `getbestblockhash` rpc call
await bitsim.getBlockHeader()
// wrapper for `getblockheader` rpc call
await bitsim.getMempoolInfo()
// wrapper for `getmempoolinfo` rpc call
await bitsim.getRawMempool()
// wrapper for `getrawmempool` rpc call
await bitsim.getBlockHash()
// wrapper for `getblockhash` rpc call
await bitsim.invalidateBlock()
// wrapper for `invalidateBlock` rpc call
})()
```
### settings
pass configuration options to bitsim as an object on initialization:
```javascript
const bitsim = new Bitsim({
mine: 1,
delay: 1000,
rpc: 'http://root:bitcoin@127.0.0.1:18332',
xpriv: 'xprv9s21ZrQH143K2AUh9yj3SmnzFVpHFgfGh23tz9iQb6p86yee29B1CcUenjSvWUFtNQ6oBho8PwPZNPi758kTFvJnxs1SoYbtUbyZeTK9zBC'
})
```
> the above represent the default configuration, and need not be specified for most use cases.
---
_Source: https://npm.io/package/bitsim · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._