Skip to content
This repository was archived by the owner on Feb 8, 2025. It is now read-only.

Commit d9264f9

Browse files
fuxinglohfuxingloh
committed
consolidate contented-docs into contented-example
1 parent a64f808 commit d9264f9

File tree

13 files changed

+10781
-3191
lines changed

13 files changed

+10781
-3191
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
packages/contented-docs/01:overview.md
1+
packages/contented-example/docs/01:overview.md

‎package-lock.json

+10,492-3,162
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

+5-6
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,6 @@
1010
"lint": "eslint --fix . && prettier --write .",
1111
"prepare": "husky install"
1212
},
13-
"dependencies": {
14-
"@birthdayresearch/contented-preview": "0.0.0",
15-
"@birthdayresearch/contented-processor": "0.0.0"
16-
},
1713
"devDependencies": {
1814
"@types/lodash": "^4.14.182",
1915
"@types/node": "16.11.43",
@@ -30,7 +26,10 @@
3026
"typescript": "4.7.4"
3127
},
3228
"lint-staged": {
33-
"*.{js,jsx,ts,tsx}": "eslint --fix",
34-
"**/*": "prettier --write --ignore-unknown"
29+
"*.{js,jsx,ts,tsx}": [
30+
"eslint --fix",
31+
"prettier --write"
32+
],
33+
"!*.{js,jsx,ts,tsx}": "prettier --write --ignore-unknown"
3534
}
3635
}

‎packages/contented-docs/package.json

-9
This file was deleted.

‎packages/contented-docs/01:overview.md renamed to ‎packages/contented-example/docs/01:overview.md

File renamed without changes.

‎packages/contented-example/docs/03:Jellyfish/01-overview.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Overview
3+
---
4+
5+
## What is Full Node APIs?
6+
7+
DeFiChain Full Node APIs is an RPC is used by authenticated clients to connect to a running instance of `defid`. The
8+
clients issue commands to send transactions, get status, and a variety of other defi purposes.
9+
`@defichain/jellyfish-api-jsonrpc` implements `@defichain/jellyfish-api-core`
10+
with [`JSON-RPC 1.0`](https://www.jsonrpc.org/specification_v1) specification.
11+
12+
Written in TypeScript, `jellyfish-api-core` provides first-class citizen support for TypeScript with strongly typed
13+
interfaces of DeFi Blockchain RPC exchanges. Built using modern JavaScript approaches, it emphasises a
14+
**future-first developer experience** and backport for compatibility. The protocol-agnostic core enables independent
15+
communication protocols, allowing vendor-agnostic middleware adaptable to any needs.

‎packages/contented-example/docs/03:Jellyfish/02-design.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Design
3+
---
4+
5+
## Promise-based client
6+
7+
To prevent a "callback hell" structure where code gets nested and messy; making it harder to understand.
8+
A `Promise<?>` based design is used as async/await implementation are very mature today, it brings better quality of
9+
life to modern development.
10+
11+
```js
12+
import { JsonRpcClient } from "@defichain/jellyfish-api-jsonrpc";
13+
14+
const client = new JsonRpcClient("http://foo:bar@localhost:8554");
15+
const { blocks } = await client.mining.getMiningInfo();
16+
```
17+
18+
## IEEE-754 arbitrary precision
19+
20+
Due to the dynamic nature of the JavaScript language, it forces all number to be interpolated as IEEE-754 which can
21+
cause precision to be lost. [JellyfishSDK/jellyfish/issues/18](https://github.com/JellyfishSDK/jellyfish/issues/18)
22+
23+
```js
24+
it("lost precision converting DFI 😥", () => {
25+
const n = 1200000000.00000001;
26+
const a = JSON.parse(JSON.stringify(n)) * 1.0e8;
27+
expect(a.toString()).toStrictEqual("120000000000000001");
28+
});
29+
```
30+
31+
### JellyfishJSON
32+
33+
**api-core** implements `JellyfishJSON` that allows parsing of JSON with `'lossless'`, `'bignumber'` and
34+
`'number'` numeric precision.
35+
36+
- **'lossless'** uses LosslessJSON that parses numeric values as LosslessNumber. With LosslessNumber, one can perform
37+
regular numeric operations, and it will throw an error when this would result in losing information.
38+
- **'bignumber'** parse all numeric values as 'BigNumber' using bignumber.js library.
39+
- **'number'** parse all numeric values as 'Number' and precision will be loss if it exceeds IEEE-754 standard.
40+
- **'PrecisionPath'** provides path based precision mapping, specifying 'bignumber' will automatically map all Number in
41+
that path as 'bignumber'. Otherwise, it will default to number, This applies deeply.
42+
43+
As not all numbers parsed are significant in all context, (e.g. `mining.getMiningInfo()`), this allows jellyfish library
44+
users to use the `number` for non precision sensitive operation (e.g. `networkhashps`) and BigNumber for precision
45+
sensitive operations.
46+
47+
### ApiClient
48+
49+
As jellyfish is written in TypeScript, all RPC exchanges with a node are typed. BigNumber precision is used for all
50+
wallet or transaction related operations. While IEEE-754 number is used for all other arbitrary operations.
51+
52+
```ts {3}
53+
export class Wallet {
54+
async getBalance(
55+
minimumConfirmation: number = 0,
56+
includeWatchOnly: boolean = false
57+
): Promise<BigNumber> {
58+
return await this.client.call(
59+
"getbalance",
60+
["*", minimumConfirmation, includeWatchOnly],
61+
"bignumber"
62+
);
63+
}
64+
}
65+
```
66+
67+
```ts {2-3,9,13}
68+
export interface MiningInfo {
69+
blocks: number;
70+
currentblockweight?: number;
71+
//...
72+
}
73+
74+
export class Mining {
75+
async getNetworkHashPerSecond(
76+
nblocks: number = 120,
77+
height: number = -1
78+
): Promise<number> {
79+
return await this.client.call(
80+
"getnetworkhashps",
81+
[nblocks, height],
82+
"number"
83+
);
84+
}
85+
86+
async getMiningInfo(): Promise<MiningInfo> {
87+
return await this.client.call("getmininginfo", [], "number");
88+
}
89+
}
90+
```
91+
92+
## Protocol agnostic core
93+
94+
ApiClient in `api-core` is a protocol agnostic DeFiChain client implementation with APIs separated into
95+
their category. The protocol-agnostic core enables independent communication protocols, allowing
96+
vendor-agnostic middleware adaptable to any needs.
97+
98+
```ts
99+
export abstract class ApiClient {
100+
/**
101+
* A promise based procedure call handling
102+
*
103+
* @param method Name of the RPC method
104+
* @param params Array of params as RPC payload
105+
* @param precision
106+
* Numeric precision to parse RPC payload as 'lossless', 'bignumber' or 'number'.
107+
*
108+
* 'lossless' uses LosslessJSON that parses numeric values as LosslessNumber. With LosslessNumber, one can perform
109+
* regular numeric operations, and it will throw an error when this would result in losing information.
110+
*
111+
* 'bignumber' parse all numeric values as 'BigNumber' using bignumber.js library.
112+
*
113+
* 'number' parse all numeric values as 'Number' and precision will be loss if it exceeds IEEE-754 standard.
114+
*
115+
* @throws ApiError
116+
* @throws RpcApiError
117+
* @throws ClientApiError
118+
*/
119+
abstract call<T>(
120+
method: string,
121+
params: any[],
122+
precision: Precision
123+
): Promise<T>;
124+
}
125+
```

‎packages/contented-example/docs/03:Jellyfish/03-usage.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Usage
3+
---
4+
5+
## Installation
6+
7+
```shell
8+
npm i defichain @defichain/jellyfish-api-jsonrpc
9+
```
10+
11+
## JsonRpcClient
12+
13+
```ts
14+
import { JsonRpcClient } from "@defichain/jellyfish-api-jsonrpc";
15+
16+
const client = new JsonRpcClient("http://foo:bar@localhost:8554");
17+
```
18+
19+
## ApiClient
20+
21+
You can extend `ApiClient` with the `@defichain/jellyfish-api-core` package to create your own transport exchange specification.
22+
23+
```ts
24+
import { ApiClient } from "@defichain/jellyfish-api-core";
25+
26+
class SpecClient extends ApiClient {
27+
async call<T>(method: string, payload: any[]): Promise<T> {
28+
throw new ClientApiError("error from client");
29+
}
30+
}
31+
32+
const client = new SpecClient("http://localhost:8554");
33+
```
34+
35+
## `call` Method
36+
37+
You can use the `.call` method directly by specifying:
38+
39+
1. node rpc method name
40+
2. payload params
41+
3. number precision for parse
42+
43+
```ts
44+
const result = await client.call("methodname", ["p1", "p2"], "number");
45+
```

‎packages/contented-example/docs/05:introduction.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Introduction
3+
description: A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized finance on Bitcoin."
4+
---
5+
6+
## What is Jellyfish?
7+
8+
A collection of TypeScript + JavaScript tools and libraries for DeFi Blockchain developers to build decentralized
9+
finance on Bitcoin. Consisting of multiple packages with more to be added in the future, this JS library enables
10+
developers to create decentralized applications on top of DeFi Blockchain that are modern, easy to use and easy to
11+
test.
12+
13+
### Monorepo & packages
14+
15+
As with all modern JavaScript projects, jellyfish follows a monorepo structure with its concerns separated. All packages
16+
maintained in this repo are published with the same version tag and follows the `DeFiCh/ain` releases.
17+
18+
| Package | Description |
19+
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
20+
| `@defichain/jellyfish-address` | Provide address builder, parser, validator utility library for DeFi Blockchain. |
21+
| `@defichain/jellyfish-api-core` | A protocol agnostic DeFi Blockchain client interfaces, with a "foreign function interface" design. |
22+
| `@defichain/jellyfish-api-jsonrpc` | Implements the [JSON-RPC 1.0](https://www.jsonrpc.org/specification_v1) specification for api-core. |
23+
| `@defichain/jellyfish-block` | Stateless raw block composer for the DeFi Blockchain. |
24+
| `@defichain/jellyfish-buffer` | Buffer composer for jellyfish. |
25+
| `@defichain/jellyfish-crypto` | Cryptography operations for jellyfish, includes a simple 'secp256k1' EllipticPair. |
26+
| `@defichain/jellyfish-json` | Allows parsing of JSON with 'lossless', 'bignumber' and 'number' numeric precision. |
27+
| `@defichain/jellyfish-network` | Contains DeFi Blockchain various network configuration for mainnet, testnet and regtest. |
28+
| `@defichain/jellyfish-testing` | Provides many abstractions for various commonly used setup pattern for DeFi Blockchain. |
29+
| `@defichain/jellyfish-transaction` | Dead simple modern stateless raw transaction composer for the DeFi Blockchain. |
30+
| `@defichain/jellyfish-transaction-builder` | Provides a high-high level abstraction for constructing transaction ready to be broadcast for DeFi Blockchain. |
31+
| `@defichain/jellyfish-transaction-signature` | Stateless utility library to perform transaction signing. |
32+
| `@defichain/jellyfish-wallet` | Jellyfish wallet is a managed wallet, where account can get discovered from an HD seed. |
33+
| `@defichain/jellyfish-wallet-classic` | WalletClassic implements a simple, single elliptic pair wallet. |
34+
| `@defichain/jellyfish-wallet-encrypted` | Library to encrypt MnemonicHdNode as EncryptedMnemonicHdNode. Able to perform as MnemonicHdNode with passphrase known. |
35+
| `@defichain/jellyfish-wallet-mnemonic` | MnemonicHdNode implements the WalletHdNode from jellyfish-wallet; a CoinType-agnostic HD Wallet for noncustodial DeFi. |
36+
| `@defichain/testcontainers` | Provides a lightweight, throw away instances for DeFiD node provisioned automatically in a Docker container. |
37+
| ~~@defichain/testing~~ | (deprecated) ~~Provides rich test fixture setup functions for effective |
38+
| and effortless testing.~~ | |

‎packages/contented-example/docs/index.js

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { defineDocumentType } from '@birthdayresearch/contented-processor';
2+
import { computeLastEditedDate } from '@birthdayresearch/contented-processor/fields/date';
3+
import { computeContentHeadings } from '@birthdayresearch/contented-processor/fields/headings';
4+
import { computePath, computeSections } from '@birthdayresearch/contented-processor/fields/path';
5+
6+
export default defineDocumentType(() => ({
7+
name: 'Doc',
8+
filePathPattern: `docs/**/*.md`,
9+
fields: {
10+
title: {
11+
type: 'string',
12+
description: 'The title of the documentation.',
13+
required: true,
14+
default: 'Contented Documentation',
15+
},
16+
description: {
17+
type: 'string',
18+
required: false,
19+
},
20+
},
21+
computedFields: {
22+
path: computePath('/', /\d+:/g, ''),
23+
date: computeLastEditedDate('content'),
24+
sections: computeSections(/posts\/?/g, /\d+:/g, ''),
25+
contentHeadings: computeContentHeadings(),
26+
},
27+
}));

‎packages/contented-example/package.json

+20-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,24 @@
11
{
22
"name": "@birthdayresearch/contented-example",
33
"version": "0.0.0",
4-
"private": true,
5-
"dependencies": {}
4+
"files": [
5+
"dist"
6+
],
7+
"scripts": {
8+
"write": "contented-preview write",
9+
"generate": "contented-preview generate",
10+
"build": "contented-processor build"
11+
},
12+
"dependencies": {
13+
"@birthdayresearch/contented-preview": "0.0.0",
14+
"@birthdayresearch/contented-processor": "0.0.0"
15+
},
16+
"contented": {
17+
"url": "https://contented.dev",
18+
"name": "Contented Documentation",
19+
"github_url": "https://github.com/BirthdayResearch/contented",
20+
"types": [
21+
"./docs"
22+
]
23+
}
624
}

‎packages/contented-preview/package.json

+12-11
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,31 @@
22
"name": "@birthdayresearch/contented-preview",
33
"version": "0.0.0",
44
"private": false,
5+
"bin": {
6+
"contented-preview": "./cli.js"
7+
},
58
"scripts": {
6-
"dev": "next dev",
7-
"build": "next build",
8-
"postbuild": "next-sitemap",
9-
"start": "next start"
9+
"write": "next dev",
10+
"generate": "next build && next-sitemap"
1011
},
1112
"dependencies": {
1213
"@headlessui/react": "^1.6.6",
1314
"@heroicons/react": "^1.0.6",
14-
"clsx": "^1.2.1",
15-
"next": "12.2.1",
16-
"react": "18.2.0",
17-
"react-dom": "18.2.0",
18-
"react-schemaorg": "^2.0.0"
19-
},
20-
"devDependencies": {
2115
"@tailwindcss/line-clamp": "^0.4.0",
2216
"@tailwindcss/typography": "^0.5.3",
2317
"@types/react": "18.0.15",
2418
"@types/react-dom": "18.0.6",
2519
"autoprefixer": "^10.4.7",
20+
"clsx": "^1.2.1",
21+
"command-line-args": "^5.2.1",
2622
"eslint-config-next": "12.2.1",
23+
"next": "12.2.1",
24+
"next-contentlayer": "^0.2.6",
2725
"next-sitemap": "^3.1.10",
2826
"postcss": "^8.4.14",
27+
"react": "18.2.0",
28+
"react-dom": "18.2.0",
29+
"react-schemaorg": "^2.0.0",
2930
"tailwindcss": "^3.1.5"
3031
}
3132
}

‎tsconfig.json

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
},
2222
"include": [
2323
"next-env.d.ts",
24+
"**/*.js",
2425
"**/*.ts",
2526
"**/*.tsx",
2627
".contentlayer/generated"

0 commit comments

Comments
 (0)