feat: Cardano spec by sotskov-do · Pull Request #2241 · lavanet/lava

sotskov-do · 2026-03-18T15:26:30Z

User description

Description

Closes: #XXXX

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

read the contribution guide
included the correct type prefix in the PR title, you can find examples of the prefixes below:
confirmed ! in the type prefix if API or client breaking change
targeted the main branch
provided a link to the relevant issue or specification
reviewed "Files changed" and left comments if necessary
included the necessary unit and integration tests
updated the relevant documentation or specification, including comments for documenting Go code
confirmed all CI checks have passed

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

confirmed the correct type prefix in the PR title
confirmed all author checklist items have been addressed
reviewed state machine logic, API design and naming, documentation is accurate, tests and test coverage

Generated description

Below is a concise technical summary of the changes proposed in this PR:
Add Cardano API specs to the governance proposals by populating specs/testnet-2/specs/cardano.json with ADA/ADAT/ADAPRE flows, API collections, verifications, and parsing directives for Blockfrost-backed nodes. Automate the Cardano-only test environment by introducing scripts/pre_setups/init_cardano_only_with_node.sh to submit specs/plans proposals, stake providers, and launch provider/consumer screens alongside a Blockfrost-authenticated provider example config.

Topic Details

Cardano Setup

Automate Cardano-only environment provisioning by scripting specs/plans submission, staking, and provider/consumer screen setup plus a Blockfrost-authenticated provider example.

Modified files (2)

config/provider_examples/cardano_example.yml
scripts/pre_setups/init_cardano_only_with_node.sh

Latest Contributors(0)

User	Commit	Date

Cardano Specs

Document Cardano mainnet, preprod, and preview flows by adding API collections, headers, verifications, and parse directives in the new cardano.json spec proposal to cover Blockfrost-backed endpoints.

Modified files (1)

specs/testnet-2/specs/cardano.json

Latest Contributors(0)

User	Commit	Date

This pull request is reviewed by Baz. Review like a pro on (Baz).

qodo-code-review · 2026-03-18T15:26:54Z

Review Summary by Qodo

Add Cardano blockchain specification and provider configuration

✨ Enhancement

Walkthroughs

Description

• Add comprehensive Cardano blockchain specification with three networks
• Define 100+ REST API endpoints for Cardano data querying
• Include provider configuration example for Blockfrost API integration
• Create test setup script for Cardano node and provider initialization

Diagram

flowchart LR
  A["Cardano Spec Definition"] -->|"ADA, ADAT, ADAPRE"| B["API Collections"]
  B -->|"GET/POST endpoints"| C["REST Interface"]
  C -->|"Blockfrost API"| D["Provider Config"]
  A -->|"Test Setup"| E["Init Script"]
  E -->|"Node + Provider"| F["Local Environment"]

File Changes

1. specs/testnet-2/specs/cardano.json ✨ Enhancement +2164/-0

Comprehensive Cardano blockchain API specification

• Added complete Cardano specification with three chain variants: ADA (mainnet), ADAT (preprod
 testnet), ADAPRE (preview testnet)
• Defined 100+ REST API endpoints covering accounts, addresses, assets, blocks, epochs, governance,
 pools, scripts, transactions, and utilities
• Configured compute units for each endpoint ranging from 10-20 units
• Set up verification for chain-id using genesis endpoint with network magic values
• Included POST endpoints for transaction submission and evaluation
• Added archive extension with 5x compute unit multiplier for historical data

specs/testnet-2/specs/cardano.json

2. config/provider_examples/cardano_example.yml ⚙️ Configuration changes +28/-0

Cardano provider configuration with Blockfrost API

• Created provider configuration template for three Cardano networks
• Configured REST endpoints for ADA (mainnet), ADAT (preprod), and ADAPRE (preview)
• Set up Blockfrost API authentication using project_id header
• Defined network addresses for local provider listening on port 2221

config/provider_examples/cardano_example.yml

3. scripts/pre_setups/init_cardano_only_with_node.sh ⚙️ Configuration changes +76/-0

Cardano test environment initialization script

• Created bash setup script for Cardano test environment initialization
• Installs binaries and starts Lava node with governance proposals
• Submits Cardano spec proposal and votes on it
• Sets up provider and consumer screens with proper logging
• Configures provider with Blockfrost API authentication headers
• Includes proper wait mechanisms for block finalization and epoch transitions

scripts/pre_setups/init_cardano_only_with_node.sh

qodo-code-review · 2026-03-18T15:26:55Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. ~~Undocumented project_id and port~~ ☑ 📘 Rule violation ⚙ Maintainability

Description

config/provider_examples/cardano_example.yml introduces a non-default local port
(127.0.0.1:2221) and a required auth header key (project_id) without any inline documentation
explaining why they differ from defaults or how to configure them safely. This increases
deployment/config drift risk and violates the requirement to document non-default ports/keys in
config/*.yml.

Code

config/provider_examples/cardano_example.yml[R4-10]

+    network-address:
+      address: "127.0.0.1:2221"
+    node-urls:
+      - url: "https://cardano-mainnet.blockfrost.io/api/v0"
+        auth-config:
+          auth-headers:
+            project_id: <YOUR_PROJECT_ID>

Evidence

PR Compliance ID 8 requires non-default ports/keys in config/*.yml to be explicitly documented
alongside the change. The new example config sets address: 127.0.0.1:2221 and includes an auth
header project_id without any accompanying comments/documentation in the file.

AGENTS.md
config/provider_examples/cardano_example.yml[4-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`config/provider_examples/cardano_example.yml` adds a non-default port (`2221`) and a required config key (`auth-headers.project_id`) without documenting what they are for, whether they are defaults, and how users should set them.
## Issue Context
The compliance checklist requires that any non-default ports/keys introduced in `config/*.yml` are explicitly documented alongside the change to prevent configuration drift and unsafe setup.
## Fix Focus Areas
- config/provider_examples/cardano_example.yml[1-28]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ~~Broken metrics arg quoting~~ ☑ 🐞 Bug ✓ Correctness

Description

In init_cardano_only_with_node.sh, the screen ... bash -c "..." command strings contain an
unescaped quoted value for --metrics-listen-address, which prematurely terminates the bash string
and breaks the command so provider/consumer screens won’t start.

Code

scripts/pre_setups/init_cardano_only_with_node.sh[R65-73]

+screen -d -m -S provider1 bash -c "source ~/.bashrc; lavap rpcprovider \
+cardano_provider \
+$EXTRA_PROVIDER_FLAGS --geolocation 1 --log_level debug --from servicer1 --chain-id lava --metrics-listen-address ":7776" 2>&1 | tee $LOGS_DIR/PROVIDER1.log" && sleep 0.25
+
+wait_next_block
+
+screen -d -m -S consumers bash -c "source ~/.bashrc; lavap rpcconsumer \
+127.0.0.1:3360 ADAT rest \
+$EXTRA_PORTAL_FLAGS --geolocation 1 --optimizer-qos-listen --log_level debug --from user1 --chain-id lava --add-api-method-metrics --limit-parallel-websocket-connections-per-ip 1 --allow-insecure-provider-dialing --metrics-listen-address ":7779" 2>&1 | tee $LOGS_DIR/CONSUMERS.log" && sleep 0.25

Evidence

The new script embeds --metrics-listen-address ":7776"/":7779"-style values inside a larger
double-quoted bash -c "..." string, but does not escape the inner quotes, making the shell parse
invalid. Another existing init script shows the intended escaping pattern for this flag.

scripts/pre_setups/init_cardano_only_with_node.sh[65-73]
scripts/pre_setups/init_sonic_main_with_addons.sh[58-60]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`scripts/pre_setups/init_cardano_only_with_node.sh` starts provider/consumer via `screen ... bash -c &quot;...&quot;`, but passes `--metrics-listen-address &quot;:7776&quot;` / `&quot;:7779&quot;` without escaping the inner quotes. This breaks shell parsing and prevents the `screen` commands from executing.
### Issue Context
Other init scripts in this repo escape the quotes (or avoid nested quotes) for the same flag.
### Fix Focus Areas
- scripts/pre_setups/init_cardano_only_with_node.sh[65-73]
### Suggested change
Within the `bash -c &quot;...&quot;` string, change:
- `--metrics-listen-address &quot;:7776&quot;` to `--metrics-listen-address \&quot;\:7776\&quot;` (or `--metrics-listen-address &#x27;:7776&#x27;`)
- `--metrics-listen-address &quot;:7779&quot;` to `--metrics-listen-address \&quot;\:7779\&quot;` (or `--metrics-listen-address &#x27;:7779&#x27;`)
Keep the outer `bash -c &quot;...&quot;` quoting intact.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

ⓘ The new review experience is currently in Beta. Learn more

codecov · 2026-03-18T15:32:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
consensus	`8.71% <ø> (ø)`
protocol	`33.38% <ø> (-0.05%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

github-actions · 2026-03-18T15:44:14Z

Test Results

0 tests ±0 0 ✅ ±0 0s ⏱️ ±0s
0 suites ±0 0 💤 ±0
7 files ±0 0 ❌ ±0

Results for commit 324e98f. ± Comparison against base commit 86ddfe8.

♻️ This comment has been updated with latest results.

baz-reviewer · 2026-03-18T16:04:39Z

+echo "[Test Setup] installing all binaries"
+make install-all
+
+echo "[Test Setup] setting up a new lava node"
+screen -d -m -S node bash -c "./scripts/start_env_dev.sh"


Lines 13‑35 replicate the exact lava-node bootstrap that already lives in scripts such as scripts/pre_setups/init_btc_only_with_node.sh (lines 13‑57) and most other init_*_only_with_node.sh helpers (log cleanup, install, node startup, spec/plan submissions, vote). Every time the shared workflow needs updating (e.g. adjusting the spec-add proposal or plan deployment) you now have to edit a dozen copies. Can we factor the common setup (logs, make install-all, start_env_dev.sh, spec/plan proposals, vote, staking, screen start) into a shared helper or parameterized wrapper so the Cardano script only supplies the spec list/provider-specific calls? That would keep this logic in one place and avoid divergence when we tweak the onboarding sequence.

_{Finding type: Code Dedup and Conventions | Severity: 🟢 Low}

Want Baz to fix this for you? Activate Fixer

Tomelia1999 · 2026-03-22T13:10:02Z

+                                "name": "content-type",
+                                "kind": "pass_override",
+                                "value": "application/cbor"
+                            },


Why did you set that header's "kind" as "pass_override"

Because for these POST endpoints (according Blockfrost documentation) data should be sent specifically as application/cbor. So this kind will override any other value which was passed.
Example from Blockfrost documentation - https://docs.blockfrost.io/#tag/cardano--transactions/POST/tx/submit

We don't want to enforce anyone's relay to include such header (not everybody use blockfrost), you better use "pass_send" which means only if the user provided such header, we forward it to the node.

Tomelia1999 · 2026-03-22T13:29:25Z

+            },
+            {
+                "index": "ADAPRE",
+                "name": "cardano preview testnet",


Consult with Yuval wether that chain should be included or we can drop it

Done. Removed preview testnet

added cardano spec

cec3112

sotskov-do added the C:specs label Mar 18, 2026

pull-request-size Bot added the size/XXL label Mar 18, 2026

qodo-code-review Bot reviewed Mar 18, 2026

View reviewed changes

Comment thread config/provider_examples/cardano_example.yml Outdated

Comment thread scripts/pre_setups/init_cardano_only_with_node.sh Outdated

baz-reviewer Bot reviewed Mar 18, 2026

View reviewed changes

sotskov-do requested a review from Tomelia1999 March 19, 2026 09:22

Tomelia1999 reviewed Mar 22, 2026

View reviewed changes

Comment thread specs/testnet-2/specs/cardano.json

Tomelia1999 reviewed Mar 22, 2026

View reviewed changes

sotskov-do added 4 commits March 23, 2026 12:11

changed content-type header to pass_send

b9647e8

fixed undocumented project_id, port and broken metrics arg quoting

31300a5

validating cardano specific variables

b4f14c9

removed preview testnet, validated spec

b662d75

sotskov-do requested a review from Tomelia1999 March 23, 2026 15:34

Tomelia1999 approved these changes Mar 25, 2026

View reviewed changes

Merge branch 'main' into cardano-specs

324e98f

nimrod-teich merged commit 5efe92d into main Mar 25, 2026
30 checks passed

nimrod-teich deleted the cardano-specs branch March 25, 2026 11:04

Conversation

sotskov-do commented Mar 18, 2026 • edited by baz-reviewer Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Description

Author Checklist

Reviewers Checklist

Generated description

Uh oh!

qodo-code-review Bot commented Mar 18, 2026

Review Summary by Qodo

Walkthroughs

File Changes

Uh oh!

qodo-code-review Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

baz-reviewer Bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Tomelia1999 Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

sotskov-do Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Tomelia1999 Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

sotskov-do Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Tomelia1999 Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

sotskov-do Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sotskov-do commented Mar 18, 2026 •

edited by baz-reviewer Bot

Loading

qodo-code-review Bot commented Mar 18, 2026 •

edited

Loading

codecov Bot commented Mar 18, 2026 •

edited

Loading

github-actions Bot commented Mar 18, 2026 •

edited

Loading