diff --git a/docs/v2/advanced/_meta.yaml b/docs/v2/advanced/_meta.yaml index 3068262e..f8d436e7 100644 --- a/docs/v2/advanced/_meta.yaml +++ b/docs/v2/advanced/_meta.yaml @@ -1,3 +1,3 @@ -label: Advanced Features -order: 70 +label: Configuration +order: 60 collapsed: true diff --git a/docs/v2/advanced/index.mdx b/docs/v2/advanced/index.mdx index f29b0e2d..7b4b5860 100644 --- a/docs/v2/advanced/index.mdx +++ b/docs/v2/advanced/index.mdx @@ -1,5 +1,5 @@ --- -title: Advanced Features +title: Configuration sidebar: label: Overview order: 0 diff --git a/docs/v2/examples/_meta.yaml b/docs/v2/examples/_meta.yaml index 1048fbb7..af001b8d 100644 --- a/docs/v2/examples/_meta.yaml +++ b/docs/v2/examples/_meta.yaml @@ -1,3 +1,3 @@ label: Examples -order: 75 +order: 80 collapsed: true diff --git a/docs/v2/examples/index.mdx b/docs/v2/examples/index.mdx index a9e3a616..a676dc45 100644 --- a/docs/v2/examples/index.mdx +++ b/docs/v2/examples/index.mdx @@ -1,11 +1,18 @@ --- -title: Examples +title: Runnable examples +sidebar: + order: 0 --- -The _Oura_ repository ships a collection of ready-to-run configurations under the +The _Oura_ repository ships a collection of ready-to-run example **projects** under the [`examples/`](https://github.com/txpipe/oura/tree/main/examples) directory. Each one is a -complete `daemon.toml` wiring a source, an optional filter chain, and a sink, so you can see -how the pieces fit together end-to-end rather than one component at a time. +complete `daemon.toml` wiring a source, an optional filter chain, and a sink — plus any +companion files — so you can clone the repo and run a full pipeline end-to-end. + +:::tip +Want a short config snippet to drop into your own `daemon.toml` rather than a whole project? +See **[Recipes](/oura/v2/examples/recipes)**. +::: ## Running an example @@ -93,106 +100,3 @@ The [`examples/lib`](https://github.com/txpipe/oura/tree/main/examples/lib) proj to embed _Oura_ in a Rust application with custom stages — a custom filter plus a custom sink that persists events into SQLite. See its README for the `sqlx-cli` setup, and the [Library usage](/oura/v2/usage/library) page for the API overview. - -## Selected recipes - -A few complete pipelines, taken verbatim from the examples above. - -### Select transactions by address - -`SplitBlock` breaks each block into individual transactions, `ParseCbor` decodes them, and -`Select` keeps only the ones touching a given address. See the -[Select filter](/oura/v2/filters/select). - -```toml -[source] -type = "N2N" -peers = ["backbone.mainnet.cardanofoundation.org:3001"] - -[intersect] -type = "Point" -value = [37225013, "65b3d40e6114e05b662ddde737da63bbab05b86d476148614e82cde98462a6f5"] - -[[filters]] -type = "SplitBlock" - -[[filters]] -type = "ParseCbor" - -[[filters]] -type = "Select" -skip_uncertain = true -predicate = "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x" - -[sink] -type = "Stdout" -``` - -### Stream parsed transactions to JSONL files - -`IntoJson` turns the parsed records into JSON, and the -[FileRotate sink](/oura/v2/sinks/file_rotate) writes them to rotated, compressed JSONL files -under `./output/`. - -```toml -[source] -type = "N2N" -peers = ["backbone.mainnet.cardanofoundation.org:3001"] - -[intersect] -type = "Point" -value = [4493860, "ce7f821d2140419fea1a7900cf71b0c0a0e94afbb1f814a6717cff071c3b6afc"] - -[[filters]] -type = "SplitBlock" - -[[filters]] -type = "ParseCbor" - -[[filters]] -type = "IntoJson" - -[sink] -type = "FileRotate" -max_total_files = 5 -output_format = "JSONL" -output_path = "./output/logs.jsonl" -max_bytes_per_file = 5_000_000 -compress_files = true -``` - -### Match a metadata label with a regex - -A [Select filter](/oura/v2/filters/select) predicate can match on transaction metadata — here, -label `674` whose text matches a regular expression. - -```toml -[chain] -type = "preprod" - -[source] -type = "N2N" -peers = ["preprod-node.world.dev.cardano.org:30000"] - -[intersect] -type = "Tip" - -[[filters]] -type = "SplitBlock" - -[[filters]] -type = "ParseCbor" - -[[filters]] -type = "Select" -skip_uncertain = false - -[filters.predicate.match.metadata] -label = 674 - -[filters.predicate.match.metadata.value.text] -regex = "Hello World" - -[sink] -type = "Stdout" -``` diff --git a/docs/v2/examples/recipes.mdx b/docs/v2/examples/recipes.mdx new file mode 100644 index 00000000..09b497b0 --- /dev/null +++ b/docs/v2/examples/recipes.mdx @@ -0,0 +1,107 @@ +--- +title: Recipes +sidebar: + order: 1 +--- + +Short, complete `daemon.toml` snippets you can copy into your own config and adapt. For full +example **projects** you can clone and run, see [Runnable examples](/oura/v2/examples). + +## Select transactions by address + +`SplitBlock` breaks each block into individual transactions, `ParseCbor` decodes them, and +`Select` keeps only the ones touching a given address. See the +[Select filter](/oura/v2/filters/select). + +```toml title="daemon.toml" +[source] +type = "N2N" +peers = ["backbone.mainnet.cardanofoundation.org:3001"] + +[intersect] +type = "Point" +value = [37225013, "65b3d40e6114e05b662ddde737da63bbab05b86d476148614e82cde98462a6f5"] + +[[filters]] +type = "SplitBlock" + +[[filters]] +type = "ParseCbor" + +[[filters]] +type = "Select" +skip_uncertain = true +predicate = "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x" + +[sink] +type = "Stdout" +``` + +## Stream parsed transactions to JSONL files + +`IntoJson` turns the parsed records into JSON, and the +[FileRotate sink](/oura/v2/sinks/file_rotate) writes them to rotated, compressed JSONL files +under `./output/`. + +```toml title="daemon.toml" +[source] +type = "N2N" +peers = ["backbone.mainnet.cardanofoundation.org:3001"] + +[intersect] +type = "Point" +value = [4493860, "ce7f821d2140419fea1a7900cf71b0c0a0e94afbb1f814a6717cff071c3b6afc"] + +[[filters]] +type = "SplitBlock" + +[[filters]] +type = "ParseCbor" + +[[filters]] +type = "IntoJson" + +[sink] +type = "FileRotate" +max_total_files = 5 +output_format = "JSONL" +output_path = "./output/logs.jsonl" +max_bytes_per_file = 5_000_000 +compress_files = true +``` + +## Match a metadata label with a regex + +A [Select filter](/oura/v2/filters/select) predicate can match on transaction metadata — here, +label `674` whose text matches a regular expression. + +```toml title="daemon.toml" +[chain] +type = "preprod" + +[source] +type = "N2N" +peers = ["preprod-node.world.dev.cardano.org:30000"] + +[intersect] +type = "Tip" + +[[filters]] +type = "SplitBlock" + +[[filters]] +type = "ParseCbor" + +[[filters]] +type = "Select" +skip_uncertain = false + +[filters.predicate.match.metadata] +label = 674 + +[filters.predicate.match.metadata.value.text] +regex = "Hello World" + +[sink] +type = "Stdout" +``` diff --git a/docs/v2/filters/_meta.yaml b/docs/v2/filters/_meta.yaml index 90df90c2..6192e21f 100644 --- a/docs/v2/filters/_meta.yaml +++ b/docs/v2/filters/_meta.yaml @@ -1,3 +1,3 @@ label: Filters -order: 30 +order: 40 collapsed: true diff --git a/docs/v2/guides/_meta.yaml b/docs/v2/guides/_meta.yaml index bbb5ae84..a09ff59c 100644 --- a/docs/v2/guides/_meta.yaml +++ b/docs/v2/guides/_meta.yaml @@ -1,3 +1,3 @@ label: Guides -order: 80 +order: 85 collapsed: true diff --git a/docs/v2/how_it_works.mdx b/docs/v2/how_it_works.mdx index 774c4107..da5bf03e 100644 --- a/docs/v2/how_it_works.mdx +++ b/docs/v2/how_it_works.mdx @@ -1,7 +1,7 @@ --- title: How it works sidebar: - order: 5 + order: 2 --- _Oura_ is a streaming pipeline. It connects to a Cardano node, reads the chain one block at a diff --git a/docs/v2/installation/binary_release.mdx b/docs/v2/installation/binary_release.mdx index 08ccc096..2f658cbe 100644 --- a/docs/v2/installation/binary_release.mdx +++ b/docs/v2/installation/binary_release.mdx @@ -1,5 +1,7 @@ --- title: Binary Releases +sidebar: + order: 1 --- import { Tabs, TabItem } from '@astrojs/starlight/components'; diff --git a/docs/v2/installation/docker.mdx b/docs/v2/installation/docker.mdx index 7b7dbbbe..fb83fe60 100644 --- a/docs/v2/installation/docker.mdx +++ b/docs/v2/installation/docker.mdx @@ -1,5 +1,7 @@ --- title: Docker +sidebar: + order: 2 --- _Oura_ provides already built public Docker images through Github Packages. To execute _Oura_ via Docker, use the following command: diff --git a/docs/v2/installation/from_source.mdx b/docs/v2/installation/from_source.mdx index 0c85c903..6510dbcb 100644 --- a/docs/v2/installation/from_source.mdx +++ b/docs/v2/installation/from_source.mdx @@ -1,5 +1,7 @@ --- title: From Source +sidebar: + order: 3 --- The following instructions show how to build and install _Oura_ from source code. diff --git a/docs/v2/installation/kubernetes.mdx b/docs/v2/installation/kubernetes.mdx index fe97be1e..b5ae7fd6 100644 --- a/docs/v2/installation/kubernetes.mdx +++ b/docs/v2/installation/kubernetes.mdx @@ -1,5 +1,7 @@ --- title: Kubernetes +sidebar: + order: 4 --- import { Tabs, TabItem } from '@astrojs/starlight/components'; diff --git a/docs/v2/quickstart.mdx b/docs/v2/quickstart.mdx index 875d2816..1106c632 100644 --- a/docs/v2/quickstart.mdx +++ b/docs/v2/quickstart.mdx @@ -1,10 +1,10 @@ --- title: Quick Start sidebar: - order: 15 + order: 3 --- -import { Steps } from '@astrojs/starlight/components'; +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; This page takes you from nothing to live Cardano data in a couple of minutes. You don't need your own node — the first step connects to a public relay. @@ -13,11 +13,30 @@ your own node — the first step connects to a public relay. 1. **Install Oura.** Grab the pre-built binary for your platform (no toolchain required): + + ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/txpipe/oura/releases/latest/download/oura-installer.sh | sh ``` + + + ```sh + powershell -c "irm https://github.com/txpipe/oura/releases/latest/download/oura-installer.ps1 | iex" + ``` + + + ```sh + brew install txpipe/tap/oura + ``` + + + ```sh + npm install -g @txpipe/oura + ``` + + - Other methods (Homebrew, npm, Windows, manual download) are on the + Manual downloads and details are on the [Binary Releases](/oura/v2/installation/binary_release) page. 2. **Watch live chain data.** Point `oura watch` at a public mainnet relay and see events scroll @@ -71,5 +90,5 @@ instead, change the `[intersect]` block — see [Intersect options](/oura/v2/adv page. Worth reading before you build a consumer. - **[Sinks](/oura/v2/sinks)** — send events to a file, message broker, database, or cloud service instead of stdout. -- **[Examples](/oura/v2/examples)** — ready-to-run configurations for every source, filter, and - sink. +- **[Runnable examples](/oura/v2/examples)** and **[Recipes](/oura/v2/examples/recipes)** — + ready-to-run projects and copy-paste configs for every source, filter, and sink. diff --git a/docs/v2/reference/_meta.yaml b/docs/v2/reference/_meta.yaml index 4e199869..216a8e28 100644 --- a/docs/v2/reference/_meta.yaml +++ b/docs/v2/reference/_meta.yaml @@ -1,3 +1,3 @@ label: Reference -order: 60 +order: 70 collapsed: true diff --git a/docs/v2/sources/_meta.yaml b/docs/v2/sources/_meta.yaml index 1394eed6..5aacf410 100644 --- a/docs/v2/sources/_meta.yaml +++ b/docs/v2/sources/_meta.yaml @@ -1,3 +1,3 @@ label: Sources -order: 40 +order: 30 collapsed: true diff --git a/docs/v2/usage/daemon.mdx b/docs/v2/usage/daemon.mdx index ebbc32d7..63f89875 100644 --- a/docs/v2/usage/daemon.mdx +++ b/docs/v2/usage/daemon.mdx @@ -1,5 +1,7 @@ --- title: Daemon +sidebar: + order: 3 --- import { Steps } from '@astrojs/starlight/components'; diff --git a/docs/v2/usage/dump.mdx b/docs/v2/usage/dump.mdx index 766a3608..f2680551 100644 --- a/docs/v2/usage/dump.mdx +++ b/docs/v2/usage/dump.mdx @@ -1,5 +1,7 @@ --- title: Dump +sidebar: + order: 2 --- The `dump` mode provides a quick way to tail the latest events from the blockchain and outputs raw data into stdout or the file system. It connects directly to a Cardano node using either node-to-client or node-to-node protocols. The output is formatted using JSONL (json, one-line per event). This command is intended mainly as quick persistence mechanism of blockchain data, such as keeping a log of blocks / transactions. It can also be used for "piping" stdout into other shell commands. diff --git a/docs/v2/usage/library.mdx b/docs/v2/usage/library.mdx index 891419ff..9d654a68 100644 --- a/docs/v2/usage/library.mdx +++ b/docs/v2/usage/library.mdx @@ -1,5 +1,7 @@ --- title: Library +sidebar: + order: 4 --- When the built-in filters and sinks don't fit your use-case, you can embed Oura as a Rust diff --git a/docs/v2/usage/watch.mdx b/docs/v2/usage/watch.mdx index ff8395b0..0cedd2ae 100644 --- a/docs/v2/usage/watch.mdx +++ b/docs/v2/usage/watch.mdx @@ -1,5 +1,7 @@ --- title: Watch +sidebar: + order: 1 --- The `watch` mode provides a quick way to tail the latest events from the blockchain. It connects directly to a Cardano node using either node-to-client or node-to-node protocols. The output is sent into the terminal in a human-readable fashion.