-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: main structure, modes of operation
- Loading branch information
Showing
8 changed files
with
286 additions
and
98 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,49 +1,50 @@ | ||
| { | ||
| "name": "clb-docs", | ||
| "version": "0.0.1", | ||
| "description": "CLB Docs", | ||
| "scripts": { | ||
| "lint": "eslint . --ext mdx --max-warnings 0 && pnpm spellcheck:lint", | ||
| "fix": "eslint . --ext mdx --fix && pnpm spellcheck:fix", | ||
| "spellcheck:lint": "cspell lint \"**/*.mdx\"", | ||
| "spellcheck:fix": "cspell --words-only --unique \"**/*.mdx\" | sort --ignore-case | uniq > words.txt", | ||
| "linkcheck": "lychee --config ./lychee.toml --quiet \"./pages\"", | ||
| "dev": "next dev", | ||
| "build": "next build", | ||
| "start": "next build && npx serve@latest out", | ||
| "postbuild": "next-sitemap" | ||
| }, | ||
| "dependencies": { | ||
| "@feelback/react": "latest", | ||
| "next": "latest", | ||
| "next-sitemap": "latest", | ||
| "nextra": "latest", | ||
| "nextra-theme-docs": "latest", | ||
| "react": "latest", | ||
| "react-dom": "latest" | ||
| }, | ||
| "devDependencies": { | ||
| "@double-great/remark-lint-alt-text": "latest", | ||
| "@types/node": "latest", | ||
| "cspell": "latest", | ||
| "eslint": "latest", | ||
| "eslint-plugin-mdx": "latest", | ||
| "ethers": "^5", | ||
| "remark": "latest", | ||
| "remark-code-import": "latest", | ||
| "remark-frontmatter": "latest", | ||
| "remark-gfm": "latest", | ||
| "remark-lint-frontmatter-schema": "latest", | ||
| "remark-lint-heading-style": "latest", | ||
| "remark-lint-list-item-indent": "latest", | ||
| "remark-lint-table-cell-padding": "latest", | ||
| "remark-lint-table-pipe-alignment": "latest", | ||
| "remark-lint-table-pipes": "latest", | ||
| "remark-lint-unordered-list-marker-style": "latest", | ||
| "remark-preset-lint-consistent": "latest", | ||
| "remark-preset-lint-recommended": "latest", | ||
| "typescript": "latest", | ||
| "unified-lint-rule": "latest", | ||
| "unist-util-visit": "latest" | ||
| } | ||
| } | ||
| { | ||
| "name": "clb-docs", | ||
| "version": "0.0.1", | ||
| "description": "CLB Docs", | ||
| "scripts": { | ||
| "lint": "eslint . --ext mdx --max-warnings 0 && pnpm spellcheck:lint", | ||
| "fix": "eslint . --ext mdx --fix && pnpm spellcheck:fix", | ||
| "spellcheck:lint": "cspell lint \"**/*.mdx\"", | ||
| "spellcheck:fix": "cspell --words-only --unique \"**/*.mdx\" | sort --ignore-case | uniq > words.txt", | ||
| "linkcheck": "lychee --config ./lychee.toml --quiet \"./pages\"", | ||
| "dev": "next dev", | ||
| "build": "next build", | ||
| "start": "next build && npx serve@latest out", | ||
| "postbuild": "next-sitemap" | ||
| }, | ||
| "dependencies": { | ||
| "@feelback/react": "latest", | ||
| "next": "latest", | ||
| "next-sitemap": "latest", | ||
| "nextra": "latest", | ||
| "nextra-theme-docs": "latest", | ||
| "react": "latest", | ||
| "react-dom": "latest" | ||
| }, | ||
| "devDependencies": { | ||
| "@double-great/remark-lint-alt-text": "latest", | ||
| "@types/node": "latest", | ||
| "@types/react": "19.0.2", | ||
| "cspell": "latest", | ||
| "eslint": "latest", | ||
| "eslint-plugin-mdx": "latest", | ||
| "ethers": "^5", | ||
| "remark": "latest", | ||
| "remark-code-import": "latest", | ||
| "remark-frontmatter": "latest", | ||
| "remark-gfm": "latest", | ||
| "remark-lint-frontmatter-schema": "latest", | ||
| "remark-lint-heading-style": "latest", | ||
| "remark-lint-list-item-indent": "latest", | ||
| "remark-lint-table-cell-padding": "latest", | ||
| "remark-lint-table-pipe-alignment": "latest", | ||
| "remark-lint-table-pipes": "latest", | ||
| "remark-lint-unordered-list-marker-style": "latest", | ||
| "remark-preset-lint-consistent": "latest", | ||
| "remark-preset-lint-recommended": "latest", | ||
| "typescript": "latest", | ||
| "unified-lint-rule": "latest", | ||
| "unist-util-visit": "latest" | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| title: Use CLB with Atlas | ||
| lang: en-US | ||
| description: How to pair CLB with Atlas and use higher-level API. | ||
| --- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| title: Building CLB | ||
| lang: en-US | ||
| description: How to use CLB in the node mode. | ||
| --- | ||
|
|
||
| # Building CLB | ||
|
|
||
| ## Building locally | ||
|
|
||
| ## Using CLB from CHaP | ||
|
|
||
| ## Using CLB executable with Nix |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| title: Bare CLB as a library | ||
| lang: en-US | ||
| description: Using CLB as a library. | ||
| --- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| title: Node mode | ||
| lang: en-US | ||
| description: How to use CLB in the node mode. | ||
| --- | ||
|
|
||
| > TODO: cardano-node compatibility matrix | ||
| > TODO: the number of nodes run by cardano-testnet | ||
| # Node emulator mode | ||
|
|
||
| For description of how this mode operates see a short | ||
| [introduction](/use#node-emulator-mode) | ||
| on the [Variants of use](/use) page. | ||
|
|
||
| ## Getting CLB executable | ||
|
|
||
| The executable `cardano-node-socket-emulator` to run CLB | ||
| is a separate cabal project located in the project repository under | ||
| [emulator](https://github.com/mlabs-haskell/clb/tree/master/emulator) folder. | ||
|
|
||
| Currently, no binary distribution is available so you have to include it into | ||
| your project using [Nix](/build#using-clb-with-nix) | ||
| or [build](/build#standalone-building) it separately. | ||
|
|
||
| ## Spinning up CLB instance | ||
|
|
||
| Almost like with a real `cardano-node` you have to provide a lot of things to the | ||
| binary to spin up an instance of emualator which is effectively a degenerated network | ||
| that consists of one only node which is in change of producing blokcs. | ||
|
|
||
| Whereas you can prepare all things manually, the recommended way is to use | ||
| [cardano-testnet](https://github.com/IntersectMBO/cardano-node/tree/master/cardano-testnet) from | ||
| [cardano-node](https://github.com/IntersectMBO/cardano-node) repository. | ||
|
|
||
| This tool is capable of generating network genesis and configuration | ||
| based on your preferences and running any executable that can understand it | ||
| by utilising `CARDANO_NODE` environment variable. | ||
|
|
||
| That way having `cardano-testnet` executable at hand you can do this | ||
| (pay attention that currently only text logging is supported): | ||
|
|
||
| ```bash | ||
| $ export CARDANO_NODE=/path/to/cardano-node-socket-emulator | ||
| $ cardano-testnet \ | ||
| cardano | ||
| --conway-era | ||
| --testnet-magic 764824073 | ||
| --nodeLoggingFormat text | ||
| ``` | ||
|
|
||
| Under the hood `cardano-testnet` generates a temporary folder which contains: | ||
| * configuration, topology and genesis files | ||
| * signing keys of genesis wallets | ||
| * IPC socket for the nodes | ||
| * logs | ||
|
|
||
| Then it runs the binary set in `CARDANO_NODE` with the following set of parameters | ||
| (listed here for informational purposes): | ||
|
|
||
| ```bash | ||
| $ cardano-node-socket-emulator run \ | ||
| --config /tmp/configuration.yaml | ||
| --topology /tmp/pools-keys/pool2/topology.json | ||
| --database-path /tmp/pools-keys/pool2/db | ||
| --shelley-kes-key /tmp/pools-keys/pool2/kes.skey | ||
| --shelley-vrf-key /tmp/pools-keys/pool2/vrf.skey | ||
| --byron-delegation-certificate /tmp/pools-keys/pool2/byron-delegation.cert | ||
| --byron-signing-key /tmp/pools-keys/pool2/byron-delegate.key | ||
| --shelley-operational-certificate /tmp/pools-keys/pool2/opcert.cert | ||
| --socket-path /tmp/socket/pool2/sock | ||
| --host-addr 127.0. 0.1 | ||
| --port 43159 | ||
| ``` | ||
|
|
||
| ## Example: CLB as backend for privnet tests in CTL | ||
|
|
||
| As a reference example you can use the way CLB is integrated with | ||
| [cardano-transaction-lib](https://github.com/Plutonomicon/cardano-transaction-lib) | ||
| as it's done in this [PR](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1655). | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| --- | ||
| title: Variants of use | ||
| lang: en-US | ||
| description: Describes different options how CLB can be used. | ||
| --- | ||
|
|
||
| # Variants of use | ||
|
|
||
| There are two basic ways to use CLB within a project. | ||
|
|
||
| The preferred way is to plug it as a Haskell library into your project. | ||
| Depending on your needs you can use low-level [CLB's bare API](/lib) | ||
| or use high-level API by pairing it with [Atlas capabilities](/atlas) | ||
| to build transactions and tests. | ||
|
|
||
| An alternative option is running CLB as a standalone node emulator. | ||
| This is the only option for non-haskell projects or in cases when | ||
| the functionality of the library is too lean for one's purposes. | ||
|
|
||
| ## Library mode | ||
|
|
||
| In the library mode CLB emulator just maintains the pure ledger in-memory state. | ||
| Neither is there notion of time, nor blocks. | ||
| The genesis is also absent and a user is expected | ||
| to provide initial fund distribution. | ||
|
|
||
| When a transaction comes in, it is validated against the state. | ||
| If it is valid then the state is immediately gets cranked, | ||
| moving into the next imaginary slot, | ||
| and the transaction is discarded. | ||
| The only information that is preserved is transaction's datums. | ||
| If the transaction happens to be invalid | ||
| a negative validation result with the reason is returned to the submitter. | ||
|
|
||
| TODO: links | ||
|
|
||
| ## Node emulator mode | ||
|
|
||
| In the [node emulator mode](/node) | ||
| (also can be reffered to as the socket mode or the node mode) | ||
| things get more entangled. | ||
| In contrast to the library mode when the emulator is just a pure state in the memory | ||
| in the node mode the emulator represents a standalone process | ||
| that mimics a full-fledged Cardano node behaviour to some extent. | ||
| The process maintains an IPC socket the way the node does, | ||
| so one can use Ouroboros mini-protocols direcrtly | ||
| or pull in Ogmios to get more usable API. | ||
|
|
||
| The following additional things come into play when CLB is run in the node mode: | ||
| * A separate thread to count slots which emulates time. | ||
| * A mempool that maintains its own so-called "cached" state. | ||
| * A trivial block producing procedure that forges blocks | ||
| from the content of the mempool. | ||
|
|
||
|
|
Oops, something went wrong.