feat: external API support, JS reference example implementation, symlink issue fix for "latest" #45

redpanda-f · 2026-01-27T08:35:40Z

Add External API for DevNet Info Export

Summary

Implements a versioned, stable JSON schema for exporting DevNet state to external tools and scripts. After a successful foc-devnet start, a devnet-info.json file is created containing all necessary information to interact with the running cluster.

Changes

New Module: src/external_api/

VersionedDevnetInfo with schema version tracking
DevnetInfoV1 containing:
- Run metadata (run_id, start_time, startup_duration)
- User accounts (addresses, balances, private keys)
- Contract addresses (MockUSDFC, Multicall3, FOC contracts including endorsements)
- Service endpoints (Lotus RPC, Curio PDP, YugabyteDB)

Integration

Export triggered automatically on successful startup
File written to ~/.foc-devnet/run/<run_id>/devnet-info.json
Also accessible via symlink at ~/.foc-devnet/state/latest/devnet-info.json

Examples

examples/read-devnet-info.js - Reads and displays DevNet info
examples/check-balances.js - Queries on-chain balances using ethers.js
Both examples demonstrate consuming the stable JSON schema

CI Validation

Verify devnet-info.json is created after successful start
Validate schema version and required fields
Run read-devnet-info.js to ensure examples work

Output Example

{
  "version": 1,
  "info": {
    "run_id": "26jan20-1622_GoofyNubs",
    "start_time": "2026-01-27T...",
    "users": [{"name": "USER_1", "evm_addr": "0x...", ...}],
    "contracts": {"mockusdfc_addr": "0x...", "endorsements_addr": "0x...", ...},
    "lotus": {"host_rpc_url": "http://localhost:5701/rpc/v1", ...}
  }
}

Copilot

Pull request overview

This pull request adds external API support for exporting DevNet information to a stable JSON schema, along with JavaScript reference implementations for consuming this data. The primary goal is to provide a machine-readable interface for external tools and scripts to interact with a running FOC DevNet instance.

Changes:

Introduced a versioned external API module that exports DevNet state (users, contracts, services) to devnet-info.json
Added JavaScript examples demonstrating how to read DevNet info and check balances using ethers.js
Modified step execution flow to return SetupContext for data extraction after successful cluster startup
Added CI validation to verify the exported JSON file exists, has correct schema, and is parseable by the JavaScript examples

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/external_api/mod.rs	New module defining public API and schema version constant
src/external_api/devnet_info.rs	Data structures for versioned DevNet information schema
src/external_api/export.rs	Logic to extract DevNet state from SetupContext and export to JSON
src/paths.rs	Added `devnet_info_file()` helper function for consistent path handling
src/lib.rs	Registered new external_api module
src/commands/start/mod.rs	Modified to return SetupContext and call export_devnet_info on success
src/commands/start/step/mod.rs	Changed execute_steps functions to return SetupContext instead of ()
examples/read-devnet-info.js	JavaScript example showing how to parse and display DevNet info
examples/check-balances.js	JavaScript example demonstrating balance queries using ethers.js
examples/package.json	NPM package configuration with ethers.js dependency
examples/README.md	Documentation for using the JavaScript examples
examples/.gitignore	Ignore node_modules and package-lock.json
.github/workflows/ci.yml	Added validation steps to verify devnet-info.json export and JavaScript examples

src/external_api/export.rs

examples/README.md

src/external_api/export.rs

examples/check-balances.js

src/external_api/export.rs

rvagg · 2026-01-27T08:54:28Z

This looks like a duplication of existing data that's already in latest, do we need to duplicate? can you remove old stuff, like contract_addresses.json?

redpanda-f · 2026-01-27T11:42:46Z

@rvagg the difference is intent of what's meant by each of the files. My defense against contract_addresses.json's removal is that that file is not bound by a "stable external facing schema". Same goes for a lot of other files as well. Hence, this looks duplicate but really is not.

Or, only this file devnet-info.json is externally facing, versioned and schema bound for others to use. All others can change.

rvagg · 2026-01-28T02:34:20Z

only this file devnet-info.json is externally facing

fair enough, as long as we clearly document it that way then that seems fine to me

.github/workflows/ci.yml

Co-authored-by: Rod Vagg <[email protected]>

Copilot · 2026-01-28T04:05:10Z

@redpanda-f I've opened a new pull request, #46, to work on those changes. Once the pull request is ready, I'll request review from you.

* Initial plan * Extract magic number 3 to USER_ACCOUNT_COUNT constant Co-authored-by: redpanda-f <[email protected]> * Improve USER_ACCOUNT_COUNT constant documentation Co-authored-by: redpanda-f <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: redpanda-f <[email protected]>

.github/workflows/ci.yml

redpanda-f · 2026-01-29T05:19:39Z

@copilot can you respond to rvagg's comments based on the new commits that were added by me?

Copilot · 2026-01-29T05:19:48Z

@redpanda-f I've opened a new pull request, #49, to work on those changes. Once the pull request is ready, I'll request review from you.

examples/read-devnet-info.js

src/commands/start/mod.rs

Co-authored-by: Rod Vagg <[email protected]>

examples/package.json

rvagg · 2026-01-29T12:08:18Z

examples/.eslintrc.json

rm this file

rvagg

lgtm pending removal of that one file

Added usage instructions and examples section to README.

BigLep

I haven't gone through all the the comments to the PR, so maybe everything I've said here was already covered, if so feel free to ignore.

I also updated the top level README with link to the examples: cf31642

.github/workflows/ci.yml

examples/package.json

examples/README.md

BigLep · 2026-01-29T17:23:37Z

examples/README.md

+
+This directory contains examples demonstrating how to interact with a running FOC DevNet instance using the exported `devnet-info.json` file.
+
+## Files


I realize the building blocks are here, but is there a reason we don't have an exmaple of starting up synapse using the content from read-devnet-info.js (per #7 ) as that is a common usecase?

I think that's part of a larger chunk of task, that in my opinion can be separated from this.

In any case, this API-providing PR has to be (by git workflow) merged into main separate from the actual use of it.

Would not want to do synapse work in this PR since now endorsements are part of mainline foc-devnet and synapse is in flux w.r.t endorsements.

What I would be able to agree to, is whether #7 should be closed by this PR or not (which it is only getting unblocked by, not being closed)

Ok, I agree this PR unblocks #7 but doesn't close it. I'll reopen #7 since the done criteria haven't been met.

add: external api reference implementation

e6b4318

Copilot AI review requested due to automatic review settings January 27, 2026 08:35

FilOzzy added this to FOC Jan 27, 2026

github-project-automation bot moved this to 📌 Triage in FOC Jan 27, 2026

Copilot started reviewing on behalf of redpanda-f January 27, 2026 08:35 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

rvagg reviewed Jan 27, 2026

View reviewed changes

examples/check-balances.js Outdated Show resolved Hide resolved

rvagg reviewed Jan 27, 2026

View reviewed changes

src/external_api/export.rs Show resolved Hide resolved

This was linked to issues Jan 27, 2026

Example of how to use with Synapse #7

Open

Canonicalize foc-devnet SetupContext, ContractAddresses and Wallet keys #36

Closed

redpanda-f added 3 commits January 27, 2026 16:16

fix: issues

8770c76

fix: CI issues

3584ef1

makehappy: fmt

55872bc

fixes: CI

4385d00

redpanda-f changed the title ~~feat: external api support and JS reference implementation~~ feat: external API support and JS reference implementation for devnet usage Jan 27, 2026

stablize: symlinks for /state/latest, simplify CI check

ff98c00

BigLep moved this from 📌 Triage to ⌨️ In Progress in FOC Jan 27, 2026

BigLep assigned redpanda-f Jan 27, 2026

add: nodejs 20 installation

fd96904

rvagg reviewed Jan 28, 2026

View reviewed changes

.github/workflows/ci.yml Show resolved Hide resolved

redpanda-f linked an issue Jan 28, 2026 that may be closed by this pull request

Fix issues with latest symlinks #37

Closed

redpanda-f changed the title ~~feat: external API support and JS reference implementation for devnet usage~~ feat: external API support, JS reference example implementation, symlink issue fix for "latest" Jan 28, 2026

Update .github/workflows/ci.yml, use nodejs LTS

6bba3f0

Co-authored-by: Rod Vagg <[email protected]>

Copilot AI mentioned this pull request Jan 28, 2026

Extract magic number for user account count to constant #46

Merged

rvagg reviewed Jan 28, 2026

View reviewed changes

.github/workflows/ci.yml Show resolved Hide resolved

fix: remove unnecessary to_string calls

9baab25

Copilot AI mentioned this pull request Jan 29, 2026

Respond to PR review feedback with status summary #49

Closed

rvagg reviewed Jan 29, 2026

View reviewed changes

examples/read-devnet-info.js Outdated Show resolved Hide resolved

rvagg reviewed Jan 29, 2026

View reviewed changes

examples/read-devnet-info.js Show resolved Hide resolved

rvagg reviewed Jan 29, 2026

View reviewed changes

src/commands/start/mod.rs Outdated Show resolved Hide resolved

redpanda-f and others added 9 commits January 29, 2026 12:33

fixes: schema validation

2d8163b

makehappy: fmt

7ac9dea

Update examples/read-devnet-info.js

ff1a487

Co-authored-by: Rod Vagg <[email protected]>

Update examples/read-devnet-info.js

0e50ebe

Co-authored-by: Rod Vagg <[email protected]>

fix: warn message

2aac53f

fix: use expect() for yugabyte

3ebe2eb

add: expect()

2677791

fix: export

c970eae

fix: examples README

f79cc5c

rjan90 moved this from ⌨️ In Progress to 🔎 Awaiting review in FOC Jan 29, 2026

rvagg reviewed Jan 29, 2026

View reviewed changes

examples/package.json Outdated Show resolved Hide resolved

remove: eslint

415de9c

rvagg reviewed Jan 29, 2026

View reviewed changes

examples/.eslintrc.json

Copy link

Contributor

rvagg Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rm this file

rvagg approved these changes Jan 29, 2026

View reviewed changes

github-project-automation bot moved this from 🔎 Awaiting review to ✔️ Approved by reviewer in FOC Jan 29, 2026

docs: enhance README with link to examples

cf31642

Added usage instructions and examples section to README.

BigLep reviewed Jan 29, 2026

View reviewed changes

redpanda-f added 2 commits January 30, 2026 11:30

feat: linkify README

3f5cb81

update: examples

9d9ed2d

redpanda-f merged commit f64767e into main Jan 30, 2026
2 checks passed

github-project-automation bot moved this from ✔️ Approved by reviewer to 🎉 Done in FOC Jan 30, 2026

redpanda-f deleted the feat/redpanda/external-api branch January 30, 2026 06:13

BigLep mentioned this pull request Jan 30, 2026

Example of how to use with Synapse #7

Open


		This directory contains examples demonstrating how to interact with a running FOC DevNet instance using the exported `devnet-info.json` file.

		## Files

feat: external API support, JS reference example implementation, symlink issue fix for "latest" #45

feat: external API support, JS reference example implementation, symlink issue fix for "latest" #45

Uh oh!

Conversation

redpanda-f commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add External API for DevNet Info Export

Summary

Changes

Output Example

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rvagg commented Jan 27, 2026

Uh oh!

redpanda-f commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rvagg commented Jan 28, 2026

Uh oh!

Uh oh!

Copilot AI commented Jan 28, 2026

Uh oh!

Uh oh!

redpanda-f commented Jan 29, 2026

Uh oh!

Copilot AI commented Jan 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rvagg Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

rvagg left a comment

Choose a reason for hiding this comment

Uh oh!

BigLep left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BigLep Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

redpanda-f Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

BigLep Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

redpanda-f commented Jan 27, 2026 •

edited

Loading

redpanda-f commented Jan 27, 2026 •

edited

Loading