Example of how to use with Synapse

[BigLep]

Done Criteria

There is documentation or an example of how a user defines a foc-localnet and then hooks it up to Synapse so they they can do adhoc testing, automated testing, etc.

Old Done Criteria

Note: this done criteria assumed a solution/implementation too much. The spirit of this issue is about showing a developer how they can hook foc-localnet into their workflow of testing / validating FOC through Synapse.

• There is a clear extension mechanism for adding new “scenarios” on top of the running DevNet, e.g.:
  • Scripts/commands that can be added under a scenarios/ directory.
  • Or a pluggable runner that can invoke multiple flows.
• At least two additional flows beyond the basic deal+retrieval are implemented, e.g.:
  • Filecoin Pin “add” followed by retrieval.
  • A basic settlement / payment-related flow (or another high-value path).
• Scenarios can be:
  • Run after the DevNet is up, via a single command per scenario or a scenario selector.
• Documentation:
  • How to add a new scenario (step-by-step, including where to put code/config).
  • How to run each included scenario.

Why Important

• Moves foc-localnet from a single happy-path demo to a general-purpose test harness.
• Enables targeted regression tests for critical workflows (pinning, settlements, etc.).

User/Customer

• Primary: Engineers using FOC stack features beyond the core deal path.
• Secondary: Product/solutions engineers (e.g., Path) needing reproducible flows for demos/validation.

Notes

• Start with very lightweight scenario scaffolding.

[redpanda-f]

Thoughts on Adding "Scenarios" to foc-localnet

Before jumping into implementation, I think we should step back and ask: what should foc-localnet actually be responsible for?

What foc-localnet Already Does

At its core, foc-localnet sets up and manages a local network for dev/testing. And honestly, it already juggles a lot:

• Managing dependencies across multiple repos (lotus, curio, filecoin-services, synapse-sdk)
• Dealing with different commits and branches for each
• Handling all the possible combinations that come from that

That's already pretty complex.

Why I Think Scenarios Should Stay External

Everyone Needs Different Things

People use this tool in wildly different ways:

• Some need functional testing
• Others want stress testing
• Some care about latency
• Others need integration or performance benchmarks

The reality is, we can't predict every scenario people will want. And honestly, it's unrealistic to expect the maintainers here to know and support all of them.

It Makes the Tool Do Too Much

If we add scenarios, we're now responsible for:

• ❌ Managing repo dependencies AND defining test scenarios
• ❌ Infrastructure setup AND test logic
• ✅ Better idea: Just focus on being great at the infrastructure part

The Maintenance Problem

Think about what built-in scenarios would mean:

• We'd need to maintain a stable API for scenario definitions
• Support scenario features as people's needs change
• Debug issues that span both infrastructure and test code
• Keep scenario code from going stale (spoiler: it will)

That's a lot of ongoing work for something that's not the core purpose of the tool.

It's Asking Too Much

We'd basically be assuming that maintainers:

• Know every possible use case
• Are experts in all testing domains
• Can support these workflows forever

That's just not realistic or fair.

What I'd Recommend Instead

Keep foc-localnet lean. Let it be really good at one thing.

Here's how this could work:

foc-localnet: Export Everything People Need

The tool should make it easy for external tools to hook in:

• Config files (network params, topology, etc.)
• Credentials and keys
• Contract addresses and endpoints
• Port mappings
• Health checks

We already do most of this in v1.0, which is great. If something more is needed on this, feel free to propose 😄

Let People Build Their Own Scenario Tools

Instead of baking scenarios in, let users create their own testing tools that:

• Depend on foc-localnet being set up first
• Read the configs it exports
• Do whatever custom testing they need
• Can change and evolve independently

Maybe Provide Some Examples

If we see common patterns emerging, we could:

• Add an examples/ directory with sample implementations
• Point to community-built scenario tools
• Document best practices

But these would be examples, not core features.

Why This Approach Is Better

• Mix and match - Use foc-localnet with any testing framework you want
• No constraints - Build scenarios however makes sense for your use case
• Stays maintainable - The core tool doesn't get bloated
• Easy to extend - New scenarios don't need PRs to foc-localnet
• Stable foundation - Infrastructure stays solid while scenario tools can experiment

Bottom Line

I think foc-localnet should stay focused on what it does well: giving you a reliable, configurable local network to work with.

Testing scenarios should be separate tools that plug into what foc-localnet provides. This keeps things maintainable and gives everyone the flexibility they need.

Curious what others think about this approach!

P.S.: I am closing this issue as not to be done, but feel free to reopen with specific request scenarios if that seems necessary to do in this codebase.

[BigLep]

@redpanda-f : In retrospect, I can see how this issue was being too prescriptive with its idea of "scenarios". I was guessing at how this would work, but I should have been more abstract. I agree that foc-localnet should stay focused on a reliable local network.

That said, we still have the need for demonstrating how someone would use foc to satsify testing other scenarios. Basically, I'd like to make sure we have examples of how could accomplish FilOzone/filecoin-services#118 using foc-localnet under the hood.

As a result, I think we still need an issue that captures how someone would configure synapse or filecoin-pin to use their foc-localnet instance. From there, someone should be good to go to write whatever other scenarios they want to test.

Does that make sense?

I have:

1. Reopened the issue
2. Changed the title
3. Simplified the done criteria.

Sound good?

[redpanda-f]

makes perfect sense. However, can we stablize V1 before we move into scenarios, please?