docs + test(e2e): E2E guide, governance lifecycle test, indexer API reference, notifications README#341
Merged
Levi-Ojukwu merged 5 commits intoJul 3, 2026
Conversation
Add tests/e2e/README.md covering prerequisites, running the suite, the Docker node setup, the global setup/teardown sequence, the shared test helpers (account funding, ledger advance, indexer polling), how to write a new test (annotated examples for both hermetic indexer tests and opt-in on-chain tests), and a debugging guide. Add tests/e2e/setup/helpers.ts with the documented helpers (fundAccount, advanceLedger, getLatestLedger, pollIndexer) so contributors reuse them instead of duplicating polling/funding logic. Link the guide (plus the API reference and notifications service docs) from the root README documentation index.
Add tests/e2e/governance.test.ts exercising the full governance loop: create a proposal to change MIN_INVOICE_AMOUNT, cast votes to pass quorum, wait out the voting period, advance past the ledger-sequence timelock, execute the proposal, and verify the change is enforced by submitting a below-threshold invoice and asserting the main contract rejects it. Uses the shared advanceLedger helper for the timelock fast-forward and the SDK governance methods. Skipped by default (like lifecycle.test.ts) and only runs when funded gov secrets and the governance + invoice contract IDs are supplied, keeping the default suite hermetic.
Add docs/api-reference.md documenting every indexer endpoint (/health, /invoices, /invoices/:id, /stats, /stats/history, /reputation/:address, /leaderboard, /events): method, path, query parameters, request body, response schema, and error codes, with a curl example for each. Includes an authentication section (X-API-Key gateway convention), shared conventions (stroop amounts, timestamps, bps, pagination), enumerations, and a guide to auto-generating an OpenAPI 3 spec from the route handlers via swagger-jsdoc. Link the reference from the indexer README.
Expand notifications/README.md into a full integrator guide: service overview and architecture diagram, environment variable reference, the complete HTTP API (webhooks, Slack, health), a step-by-step webhook registration walkthrough with curl examples, the event type catalogue with example payloads, HMAC signature verification examples in TypeScript, Python, and Go, reliability behaviour (circuit breaker, rate limiting, retries), Slack setup, and an email delivery setup guide via the Resend adapter. The root README already links this guide from its documentation index.
|
@distributed-nerd Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds developer documentation and an end-to-end test across four areas, each as a focused commit.
Closes #273
Closes #282
Closes #296
Closes #287
1. E2E setup & test authoring guide (
tests/e2e/README.md)setup/globalSetup.ts/globalTeardown.ts).tests/e2e/setup/helpers.ts):fundAccount(Friendbot),advanceLedger/getLatestLedger(ledger fast-forward),pollIndexer(async polling).2. Governance proposal lifecycle E2E test (
tests/e2e/governance.test.ts)advanceLedgerhelper.lifecycle.test.ts) unless funded governance secrets and the governance + invoice contract IDs are supplied, keeping the default suite hermetic.3. Indexer REST API reference (
docs/api-reference.md)/health,/invoices,/invoices/:id,/stats,/stats/history,/reputation/:address,/leaderboard,/events): method, path, query parameters, request body, response schema, and error codes, with a curl example for each.X-API-Keygateway convention), shared conventions, enumerations, and a swagger-jsdoc OpenAPI generation guide.4. Notifications service README (
notifications/README.md)All three docs are linked from the root
README.mddocumentation index.Notes
A few of the issue specs didn't match the current code; the docs/tests were kept faithful to the actual source:
iln_governancecontract has noMIN_INVOICE_AMOUNTaction (its actions areUpdateFeeRate/AddToken/RemoveToken/UpdateMaxDiscountRate), and the invoice minimum amount is a fixedten_pow(decimals), not governance-controlled. The governance test follows the issue's propose→vote→timelock→execute→verify-rejection narrative but is env-parameterized and skipped by default, so it can't produce false passes against the current contracts. A comment block explains this.X-API-Keygateway convention honestly as not enforced by the indexer core.Testing
The test suites were not run here — they require Docker (
stellar-quickstart) and the e2e/sdknode_modules(not installed in this environment). The new test follows the existing tests' import patterns and SDK signatures.