mainnet-fork setup for backend

[nialexsan]

Closes: https://github.com/onflow/FlowYieldVaults-fe/issues/139

Description

build container with forked mainnet emulator for e2e tests in backend and frontend repos
successful build run https://github.com/onflow/FlowYieldVaults/actions/runs/24156458638/job/70496636491

---

For contributor use:

• Targeted PR against master branch
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the standards mentioned here.
• Updated relevant documentation
• Re-reviewed Files changed in the Github PR explorer
• Added appropriate labels

[nialexsan]

@claude

[claude]

Claude finished @nialexsan's task in 1m 54s —— View job

---

Code Review

• Read CLAUDE.md for repo guidelines
• Review changed files
• Provide feedback

---

Good PR overall — the architecture is clean and the test coverage is solid. A few items worth addressing:

---

Potential Issues

1. COPY . ${APP_HOME} may bake private key into Docker image (Dockerfile.mainnet-fork)

The Dockerfile copies the entire repo into the image, which includes local/emulator-account.pkey (referenced in flow.json). Even though fork mode disables signature validation, shipping a private key file in a published Docker image is a bad practice that could cause confusion or trigger secret-scanning alerts.

Fix: add a .dockerignore to exclude the key (and other local secrets).

# .dockerignore
local/emulator-account.pkey
local/*.pkey

Fix this →

---

2. SIGPIPE inconsistency in setup_oracle_threshold (local/mainnet_fork_common.sh:767)

_check_sealed documents that it avoids pipes specifically to prevent SIGPIPE under set -o pipefail. But setup_oracle_threshold uses echo "$result" | grep -q, which reintroduces the same issue:

# Current (line 767) — has SIGPIPE risk
if ! echo "$result" | grep -q "SEALED" || echo "$result" | grep -q "Transaction Error"; then

This should use [[ ]] matching like _check_sealed does, or simply call _check_sealed "$desc" "$result".

Fix this →

---

3. contents: write is overly broad for the test job (.github/workflows/build-flow-emulator.yml:40)

The test job only runs flow deps install and a shell script — it doesn't push or write to the repo. contents: read is sufficient.

# test job should be:
permissions:
  contents: read

---

4. Fragile vault ID parsing in get_latest_vault_id (local/e2e_mainnet_fork.sh:433-436)

echo "$result" | grep -oE '\b[0-9]+\b' | sort -n | tail -1

This extracts every number from the script output and takes the largest. If the script output format changes (e.g., prints a timestamp or block height), this silently returns the wrong ID and the test continues without error. Consider having the script print the vault ID on a dedicated line with a known prefix and parsing that instead.

---

5. debian:stable-slim is not pinned (Dockerfile.mainnet-fork:1)

stable resolves to whatever Debian considers current, which can change between builds. Pin to a specific release (e.g., debian:bookworm-slim) for reproducible builds.

---

Minor Observations

• setup_ft_vault.cdc metadata capability type (cadence/tests/transactions/setup_ft_vault.cdc:217): Both receiverCap and metadataCap are issued as <&{FungibleToken.Vault}>. The metadata path typically expects a type that includes ViewResolver.Resolver/balance capabilities. For fork tests this probably works (callers may just need the receiver), but it won't expose metadata views.

• sleep 3 between steps (local/e2e_mainnet_fork.sh:538,568): Fixed sleeps slow down CI. Not a blocker, but a poll-until-confirmed approach would be more robust.

• remove_fork_accounts only removes $PYUSD0_DONOR (local/e2e_mainnet_fork.sh:423-427): The function name implies it removes all fork accounts added by the script, but only the donor is removed. If add_fork_account is ever called for additional accounts, the cleanup won't be symmetric. The implementation is correct for the current usage, but the name is slightly misleading.

• pull_request trigger removed: The workflow no longer runs on PRs — tests only run on push to v0. Intentional?

---

What's Working Well

• The _check_sealed fallback (querying by tx ID when the CLI times out) is thoughtful and handles a real-world race condition.
• Sharing setup logic between the Docker script and the local e2e script via mainnet_fork_common.sh is clean.
• Flow CLI version is pinned identically in both the workflow and Dockerfile — good for reproducibility.
• The _host_args() pattern for optional --host injection is a clean way to support both local and Docker networking.
• Removal of MockOracle/MockSwapper in favor of real mainnet-fork state is the right direction.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!