Skip to content

docs(core-loop): expand with testnet contract deploy + env + on-chain verification#54

Open
ale-helper-bot wants to merge 1 commit into
StellarRoute:mainfrom
ale-helper-bot:docs/testnet-core-loop
Open

docs(core-loop): expand with testnet contract deploy + env + on-chain verification#54
ale-helper-bot wants to merge 1 commit into
StellarRoute:mainfrom
ale-helper-bot:docs/testnet-core-loop

Conversation

@ale-helper-bot

Copy link
Copy Markdown

Closes #40

What

Expands docs/core-loop.md with a "Testnet sequence" section covering the
full merge → on-chain payout loop that the existing "Local sequence" stops
short of.

Sections added

  • Step 7-8: install WASM target + build escrow contract + deploy/initialize with both the scripts/deploy-contract.sh entry point and the underlying soroban CLI calls, including expected explorer URL pattern.
  • Step 9: configure gateway with live testnet credentials showing the SOROBAN_RPC_URL, NETWORK_PASSPHRASE, ESCROW_CONTRACT_ID, GATEWAY_SECRET_KEY env block that flips submit_attestation out of dry-run mode (no more simulated-tx-* placeholders).
  • Step 10-11: register live testnet program and trigger a real merge with the on-chain program_id semantics (admin API takes the u64 from the contract, not the Postgres UUID).
  • Step 12: verify on-chain payout with both the audit API path and a direct soroban contract invoke ... get_payout query, plus the expected match between the two.
  • Step 13: idempotency and replay safety documenting the webhook_events.delivery_id unique constraint and the payouts.(program_id, pr_number) unique constraint, plus the off-chain balance tracking in load_reward_per_point + increment_milestone_spent.
  • Step 14: common testnet pitfalls (network passphrase, signer funding, contract not initialized, stale contract id, WASM size budget).

Why

The current core-loop.md ends at the contract test
(cargo test -p waveflow-escrow record_merge_pays_contributor) which covers
fund → register → record_merge without external services. A new contributor
cannot follow a testnet merge → payout end-to-end without reading
scripts/deploy-contract.sh, .env.example, and
crates/gateway/src/attestation.rs separately. This consolidation lowers the
bar for first-time Wave bounty participants and gives maintainers a single
document to link from docs/PRD.md Section 6 (operational flow).

Acceptance criteria coverage

  • Testnet section covers contract deploy and initialize
  • Gateway env vars documented with example values
  • End-to-end merge payout verifiable on testnet (API + on-chain query)
  • Cross-links attestation RPC implementation issue ([gateway] Implement real Soroban RPC record_merge submission #6) and the
    simulated-vs-real hash behaviour in attestation.rs::submit_attestation

Notes

  • No code changes; documentation only.
  • The expanded section preserves the existing "Local sequence" verbatim and
    uses soroban CLI commands identical to the actual test setup described
    in scripts/deploy-contract.sh and .env.example.
  • All identifiers, file paths, function names, and labels match the current
    main branch (commit fetches cleanly with git fetch upstream).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[documentation] Expand core-loop.md with testnet contract deploy steps

1 participant