documentation website setup

.github/dependabot.yml

@@ -7,6 +7,13 @@ updates:
     labels:
       - "kind/dependencies"
 
+  - package-ecosystem: 'npm'
+    directory: '/website'
+    schedule:
+      interval: 'monthly'
+    labels:
+      - "kind/dependencies"
+
   - package-ecosystem: 'npm'
     directory: '/packages/jellyfish'
     schedule:

README.md

@@ -6,7 +6,7 @@
 
 # @defichain/jellyfish
 
-A collection of TypeScript + JavaScript tools and libraries for DeFiChain to build decentralized finance on Bitcoin.
+A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin.
 
 > 🚧 Work in progress, `3/193` rpc completed.
 
@@ -83,10 +83,10 @@ Documentation can be found at `https://jellyfish.defichain.com`?
 
 |package|@latest|@next|
 |---|---|---|
-|`@defichain/jellyfish`|![npm](https://img.shields.io/npm/v/@defichain/jellyfish)|![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)|
-|`@defichain/jellyfish-core`|![npm](https://img.shields.io/npm/v/@defichain/jellyfish-core)|![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-core/next)|
-|`@defichain/jellyfish-jsonrpc`|![npm](https://img.shields.io/npm/v/@defichain/jellyfish-jsonrpc)|![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-jsonrpc/next)|
-|`@defichain/testcontainers`|![npm](https://img.shields.io/npm/v/@defichain/testcontainers)|![npm@next](https://img.shields.io/npm/v/@defichain/testcontainers/next)|
+|`@defichain/jellyfish`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish)](https://www.npmjs.com/package/@defichain/jellyfish/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)](https://www.npmjs.com/package/@defichain/jellyfish/v/next)|
+|`@defichain/jellyfish-core`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-core)](https://www.npmjs.com/package/@defichain/jellyfish-core/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-core/next)](https://www.npmjs.com/package/@defichain/jellyfish-core/v/next)|
+|`@defichain/jellyfish-jsonrpc`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-jsonrpc)](https://www.npmjs.com/package/@defichain/jellyfish-jsonrpc/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-jsonrpc/next)](https://www.npmjs.com/package/@defichain/jellyfish-jsonrpc/v/next)|
+|`@defichain/testcontainers`|[![npm](https://img.shields.io/npm/v/@defichain/testcontainers)](https://www.npmjs.com/package/@defichain/testcontainers/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/testcontainers/next)](https://www.npmjs.com/package/@defichain/testcontainers/v/next)|
 
 ## Developing & Contributing
 

packages/jellyfish-core/src/category/wallet.ts

@@ -11,10 +11,10 @@ export class Wallet {
   }
 
   /**
-   * Returns the total available balance.
+   * Returns the total available balance in wallet.
    *
-   * @param minimumConfirmation
-   * @param includeWatchOnly
+   * @param minimumConfirmation to include transactions confirmed at least this many times
+   * @param includeWatchOnly for watch-only wallets
    * @return Promise<number>
    */
   async getBalance (minimumConfirmation: number = 0, includeWatchOnly: boolean = false): Promise<BigNumber> {

packages/testcontainers/README.md

@@ -26,27 +26,22 @@ Use your favourite jest runner and start building dApps!
 
 ```js
 import { RegTestDocker } from '@defichain/testcontainers'
-import { getClient } from 'somewhere'
 
-describe('reg test', () => {
-  const node = new RegTestDocker()
+describe('reg test container', () => {
+  const container = new RegTestContainer()
 
   beforeEach(async () => {
-    await node.start({
-      user: 'foo',
-      password: 'bar',
-    })
-    await node.ready()
+    await container.start()
+    await container.waitForReady()
   })
 
   afterEach(async () => {
-    await node.stop()
+    await container.stop()
   })
 
   it('should getmintinginfo and chain should be regtest', async () => {
-    const url = await node.getRpcUrl()
-    const client = getClient(url)
-    const result = await client.call('getmintinginfo', [])
+    // Using node.call('method', []), the built-in minimalistic rpc call
+    const result = await container.call('getmintinginfo', [])
     expect(result.chain).toBe('regtest')
   })
 })

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,25 @@
+# jellyfish/website
+
+> This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+npm i
+```
+
+## Local Development
+
+```console
+npm run start
+```
+
+This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')]
+}

website/docs/introduction.md

@@ -0,0 +1,30 @@
+---
+id: introduction
+title: Introduction
+sidebar_label: Introduction
+slug: /
+---
+
+A collection of TypeScript + JavaScript tools and libraries for DeFiChain developers to build decentralized finance on Bitcoin.
+Consisting of 4 packages with more to be added in the future, the jellyfish project allow DeFiChain developers to build decentralized apps that are modern, easy to use and easy to test.
+
+Jellyfish follows a monorepo methodology, all maintained packages are in the same repo and published with the same version tag.
+
+## Packages
+
+* `@defichain/jellyfish` bundled usage entrypoint with conventional defaults for 4 bundles: umd, esm, cjs
+  and d.ts
+* `@defichain/jellyfish-core` is a protocol agnostic DeFiChain client interfaces, with a "foreign function interface"
+  design.
+* `@defichain/jellyfish-jsonrpc` implements the [JSON-RPC 1.0](https://www.jsonrpc.org/specification_v1) specification.
+* `@defichain/testcontainers` provides a lightweight, throw away instances for DeFiD node provisioned automatically in
+  Docker container.
+
+### Latest releases
+
+|package|@latest|@next|
+|---|---|---|
+|`@defichain/jellyfish`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish)](https://www.npmjs.com/package/@defichain/jellyfish/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish/next)](https://www.npmjs.com/package/@defichain/jellyfish/v/next)|
+|`@defichain/jellyfish-core`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-core)](https://www.npmjs.com/package/@defichain/jellyfish-core/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-core/next)](https://www.npmjs.com/package/@defichain/jellyfish-core/v/next)|
+|`@defichain/jellyfish-jsonrpc`|[![npm](https://img.shields.io/npm/v/@defichain/jellyfish-jsonrpc)](https://www.npmjs.com/package/@defichain/jellyfish-jsonrpc/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/jellyfish-jsonrpc/next)](https://www.npmjs.com/package/@defichain/jellyfish-jsonrpc/v/next)|
+|`@defichain/testcontainers`|[![npm](https://img.shields.io/npm/v/@defichain/testcontainers)](https://www.npmjs.com/package/@defichain/testcontainers/v/latest)|[![npm@next](https://img.shields.io/npm/v/@defichain/testcontainers/next)](https://www.npmjs.com/package/@defichain/testcontainers/v/next)|

website/docs/jellyfish/api/mining.md

@@ -0,0 +1,41 @@
+---
+id: mining
+title: Mining API
+sidebar_label: Mining API
+slug: /jellyfish/api/mining
+---
+
+## getNetworkHashPerSecond
+
+Returns the estimated network hashes per second.
+- `nblocks` to estimate since last difficulty change.
+- `height` to estimate at the time of the given height.
+
+```ts
+getNetworkHashPerSecond (nblocks: number = 120, height: number = -1): Promise<number>
+```
+
+## getMintingInfo
+
+Get minting-related information.
+
+```ts
+interface MintingInfo {
+  blocks: number
+  currentblockweight?: number
+  currentblocktx?: number
+  difficulty: string
+  isoperator: boolean
+  masternodeid?: string
+  masternodeoperator?: string
+  masternodestate?: 'PRE_ENABLED' | 'ENABLED' | 'PRE_RESIGNED' | 'RESIGNED' | 'PRE_BANNED' | 'BANNED'
+  generate?: boolean
+  mintedblocks?: number
+  networkhashps: number
+  pooledtx: number
+  chain: 'main' | 'test' | 'regtest' | string
+  warnings: string
+}
+
+getMintingInfo (): Promise<MintingInfo>
+```

website/docs/jellyfish/api/wallet.md

@@ -0,0 +1,17 @@
+---
+id: wallet
+title: Wallet API
+sidebar_label: Wallet API
+slug: /jellyfish/api/wallet
+---
+
+## getBalance
+
+Returns the total available balance in wallet.
+- `minimumConfirmation` to include transactions confirmed at least this many times.
+- `includeWatchOnly` for watch-only wallets, otherwise
+  - Include balance in watch-only addresses (see `importAddress`)
+
+```ts
+getBalance (minimumConfirmation: number = 0, includeWatchOnly: boolean = false): Promise<BigNumber>
+```

website/docs/jellyfish/design.md

@@ -0,0 +1,126 @@
+---
+id: design
+title: Jellyfish Design
+sidebar_label: Jellyfish Design
+slug: /jellyfish/design
+---
+
+## Conventional defaults
+
+`@defichain/jellyfish` package provides conventional defaults and bundle all code required for dApps building. 
+
+```js
+import { Client, HttpProvider } from '@defichain/jellyfish'
+
+// Coventional Defaults
+let client = new Client()
+
+// Explicit Configuration
+client = new Client(new HttpProvider('http://foo:bar@localhost:8554'), {
+    timeout: 30000
+})
+```
+
+## Promise-based client
+
+To prevent a "callback hell" structure where code get nested and messy; making it harder to understand.
+A `Promise<?>` based design is used as async/await implementation are very mature today, it brings better quality of 
+life to modern development.
+
+```js
+import {Client} from '@defichain/jellyfish'
+
+const client = new Client()
+const {blocks} = await client.mining.getMintingInfo()
+```
+
+## IEEE-754 arbitrary precision
+
+Due to the dynamic nature of the JavaScript language, it forces all number to be interpolated as IEEE-754 which can 
+cause precision to be lost. [DeFiCh/jellyfish/issues/18](https://github.com/DeFiCh/jellyfish/issues/18)
+
+```js
+it('lost precision converting DFI 😥', () => {
+  const n = 1200000000.00000001
+  const a = JSON.parse(JSON.stringify(n)) * 1.0e8
+  expect(a.toString()).toBe("120000000000000001")
+});
+```
+
+### `JellyfishJSON`
+
+**jellyfish-core** implements `JellyfishJSON` that allows parsing of JSON with `'lossless'`, `'bignumber'` and 
+`'number'` numeric precision.
+
+* **'lossless'** uses LosslessJSON that parses numeric values as LosslessNumber. With LosslessNumber, one can perform
+  regular numeric operations, and it will throw an error when this would result in losing information.
+* **'bignumber'** parse all numeric values as 'BigNumber' using bignumber.js library.
+* **'number'** parse all numeric values as 'Number' and precision will be loss if it exceeds IEEE-754 standard.
+
+
+As not all number parsed are significant in all context, (e.g. `mining.getMintingInfo()`), this allows jellyfish library 
+users to use the `number` for non precision sensitive operation (e.g. `networkhashps`) and BigNumber for precision 
+sensitive operations.
+
+### `JellyfishClient`
+
+As jellyfish is written in TypeScript, all RPC exchanges with a node are typed. BigNumber precision is used for all 
+wallet or transaction related operations. While IEEE-754 number is used for all other arbitrary operations.
+
+```ts {3}
+export class Wallet {
+  async getBalance (minimumConfirmation: number = 0, includeWatchOnly: boolean = false): Promise<BigNumber> {
+    return await this.client.call('getbalance', ['*', minimumConfirmation, includeWatchOnly], 'bignumber')
+  }
+}
+
+```
+
+```ts {2-3,9,13}
+export interface MintingInfo {
+  blocks: number
+  currentblockweight?: number
+  //...
+}
+
+export class Mining {
+  async getNetworkHashPerSecond (nblocks: number = 120, height: number = -1): Promise<number> {
+    return await this.client.call('getnetworkhashps', [nblocks, height], 'number')
+  }
+
+  async getMintingInfo (): Promise<MintingInfo> {
+    return await this.client.call('getmintinginfo', [], 'number')
+  }
+}
+```
+
+## Protocol agnostic core
+
+JellyfishClient in `jellyfish-core` is a protocol agnostic DeFiChain client implementation with APIs separated into 
+their category. The protocol-agnostic core enable independent communication protocols, allowing
+vendor-agnostic middleware adaptable to any needs.
+
+```ts
+export abstract class JellyfishClient {
+  /**
+   * A promise based procedure call handling
+   *
+   * @param method Name of the RPC method
+   * @param params Array of params as RPC payload
+   * @param precision
+   * Numeric precision to parse RPC payload as 'lossless', 'bignumber' or 'number'.
+   *
+   * 'lossless' uses LosslessJSON that parses numeric values as LosslessNumber. With LosslessNumber, one can perform
+   * regular numeric operations, and it will throw an error when this would result in losing information.
+   *
+   * 'bignumber' parse all numeric values as 'BigNumber' using bignumber.js library.
+   *
+   * 'number' parse all numeric values as 'Number' and precision will be loss if it exceeds IEEE-754 standard.
+   *
+   * @throws JellyfishError
+   * @throws JellyfishRPCError
+   * @throws JellyfishClientError
+   */
+  abstract call<T> (method: string, params: any[], precision: Precision): Promise<T>
+}
+```

website/docs/jellyfish/overview.md

@@ -0,0 +1,23 @@
+---
+id: overview
+title: Jellyfish Overview
+sidebar_label: Jellyfish Overview
+slug: /jellyfish
+---
+
+## What is jellyfish?
+
+Jellyfish is a JS library written to enable developers to develop decentralized applications on top of DeFiChain. As
+with all modern JavaScript projects, jellyfish follows a monorepo structure with its concerns separated. All packages
+maintained in this repo are published with the same version tag and follows the `DeFiCh/ain` releases.
+
+- **jellyfish** is the entrypoint for most dApps developer as it bundles and create 4 types of JavaScript modules:
+  cjs, esm, umd and d.ts.
+- **jellyfish-core** represents a protocol agnostic interface of DeFiChain client with APIs separated into their
+  category.
+- **jellyfish-jsonrpc** implements the jellyfish-core with the JSON-RPC 1.0 specification.
+
+Written in TypeScript, jellyfish provides first-class citizen support for TypeScript with strongly typed interfaces of
+DeFiChain rpc exchanges. Built using modern JavaScript approaches, it emphasises a **future-first developer experience** 
+and backport for compatibility. The protocol-agnostic core enable independent communication protocols, allowing
+vendor-agnostic middleware adaptable to any needs.