Esure

Test with confidence. Build on Stellar.

Esure is an open-source testing and simulation toolkit that helps developers validate Stellar payment flows before integrating them into production applications. It turns multi-step Testnet operations into repeatable scenarios with structured reports, transaction links, balance changes, and readable failure explanations.

Important

Esure is an MVP built exclusively for Stellar Testnet. It must not be used for Mainnet transactions or real-value assets.

Live services

Service	URL
Web dashboard	esure-testnet.vercel.app
Backend health	esure.onrender.com/health
OpenAPI document	esure.onrender.com/openapi.json

The Render free service may sleep after inactivity, so its first response can take longer than subsequent requests.

MVP capabilities

• Run predefined XLM payment, issued-asset payment, and expected-failure flows.
• Create and fund isolated accounts on Stellar Testnet.
• Establish trustlines and submit classic asset payments.
• Track execution steps and verify transaction outcomes and balances.
• Produce sanitized reports without exposing account secrets.
• Validate bounded declarative JSON and YAML scenario definitions.
• Optionally persist the published scenario catalogue in PostgreSQL.

See the MVP specification for the complete product scope.

Why Esure

A realistic Stellar payment test spans account creation, Friendbot funding, trustline configuration, transaction submission, ledger confirmation, and balance verification. Rebuilding that flow manually makes failures difficult to reproduce and easy to misdiagnose. Esure packages the full process into versioned scenarios that can be executed repeatedly and inspected through one consistent report format.

Esure is useful for:

• payment and remittance teams validating integration assumptions;
• wallet developers testing asset and trustline behavior;
• educators demonstrating common Stellar transaction flows;
• contributors reproducing protocol-level failures safely on Testnet; and
• CI workflows that need deterministic validation without storing secret keys.

Included scenarios

Scenario	Purpose	Expected result
xlm-payment	Fund two accounts, transfer 5 XLM, and verify the recipient balance change	Pass
issued-asset-payment	Create a TESTUSD trustline, issue 100 TESTUSD, and verify the final balance	Pass
missing-trustline	Attempt an issued-asset payment without a recipient trustline	Controlled op_no_trust failure

Each run generates fresh Testnet accounts, so repeated executions remain isolated from previous runs.

How a run works

1. The dashboard requests the published scenario catalogue from the backend.
2. The user selects a scenario and starts a run through the same-origin proxy.
3. The backend validates the bounded scenario definition before generating any accounts or making network requests.
4. The runner creates isolated accounts, obtains Testnet funds, and executes each declared operation in order.
5. Assertions compare the observed transaction result or balance with the scenario expectation.
6. The frontend polls the run endpoint and renders progress, transaction links, assertions, and sanitized failures.
7. The final structured report is available from the report endpoint.

Architecture

Browser
   |
   v
Next.js dashboard and same-origin proxy
   |
   v
Fastify API and scenario runner
   |----------------------|
   v                      v
Stellar Testnet      PostgreSQL (optional)

Directory	Responsibility
esure-frontend	Next.js dashboard and browser-facing API proxy
esure-backend	Fastify API, validation, reporting, and Testnet execution
esure-docs	Product, API, architecture, scenario, and persistence documentation
esure-contracts	Design space for post-MVP Soroban fixtures
.github	CI, issue templates, contribution guidance, and security policy

For deeper technical context, read the architecture documentation.

Quick start

Prerequisites

• Git
• Node.js 20 or newer
• npm
• Network access to Stellar Testnet for live runs

1. Clone and install

git clone https://github.com/Esureorg/Esure.git
cd Esure

cd esure-backend
npm ci
cd ../esure-frontend
npm ci
cd ..

2. Configure the applications

macOS and Linux:

cp esure-backend/.env.example esure-backend/.env
cp esure-frontend/.env.example esure-frontend/.env.local

Windows PowerShell:

Copy-Item esure-backend/.env.example esure-backend/.env
Copy-Item esure-frontend/.env.example esure-frontend/.env.local

The frontend defaults to a backend at http://127.0.0.1:3001. To use another backend, set ESURE_BACKEND_URL in esure-frontend/.env.local.

3. Start the backend

In the first terminal:

cd esure-backend
npm run dev

Verify the API:

curl http://127.0.0.1:3001/health
curl http://127.0.0.1:3001/api/v1/scenarios

4. Start the frontend

In a second terminal:

cd esure-frontend
npm run dev

Open http://localhost:3000.

5. Run a scenario from the API

curl -X POST http://127.0.0.1:3001/api/v1/runs \
  -H "content-type: application/json" \
  -d '{"scenarioId":"issued-asset-payment","inputs":{}}'

The response contains a run ID. Use it to retrieve progress and the final report:

curl http://127.0.0.1:3001/api/v1/runs/RUN_ID
curl http://127.0.0.1:3001/api/v1/runs/RUN_ID/report

API overview

Method	Endpoint	Purpose
GET	/health	Confirm the API process is available
GET	/ready	Confirm dependencies are ready
GET	/api/v1/scenarios	List available scenarios
POST	/api/v1/scenarios/validate	Validate a scenario definition
POST	/api/v1/runs	Start a bundled scenario
GET	/api/v1/runs/:runId	Read current run state
GET	/api/v1/runs/:runId/report	Download a structured report

The complete contract is available from the deployed OpenAPI document and the API documentation.

Configuration reference

Frontend

Variable	Default	Description
ESURE_BACKEND_URL	http://127.0.0.1:3001	Server-only backend origin used by the Next.js proxy

Backend

Variable	Default	Description
HOST	127.0.0.1	Bind address; use 0.0.0.0 on Render
PORT	3001	HTTP port; Render supplies this automatically
LOG_LEVEL	info	Fastify application log level
RUN_TIMEOUT_MS	120000	Maximum duration of a complete run
STEP_TIMEOUT_MS	30000	Maximum duration of one scenario step
MAX_CONCURRENT_RUNS	2	Maximum simultaneous executions
MAX_STORED_RUNS	500	Hard limit for retained in-memory runs
RUN_RETENTION_MS	3600000	Retention time for terminal in-memory runs
RATE_LIMIT_MAX	120	General request limit per rate-limit window
RUN_RATE_LIMIT_MAX	10	Stricter run-creation limit per window
PERSISTENCE_MODE	disabled	Use published only after configuring PostgreSQL
DATABASE_URL	unset	Runtime application connection for published persistence

Review esure-backend/.env.example for every supported setting and its safe default.

Development and testing

Run the same deterministic checks used by CI:

cd esure-backend
npm run check
npm run build

cd ../esure-frontend
npm run check

Normal automated tests do not submit real transactions. The opt-in Testnet smoke test is documented in the backend README.

Persistence

The default PERSISTENCE_MODE=disabled configuration keeps runtime state in memory. Published scenario catalogue persistence can be enabled with PostgreSQL after applying the checked migrations and configuring the required database roles. See the persistence guide before enabling it.

Deployment

Component	Platform	Root directory
Frontend	Vercel	esure-frontend
Backend	Render	esure-backend
Database	PostgreSQL provider	Not applicable

Set ESURE_BACKEND_URL in Vercel to the public Render backend origin. Keep secrets and migration credentials in the hosting provider environment settings; never commit them to the repository.

Current MVP status

Area	Status
Declarative scenario validation	Implemented
XLM and issued-asset Testnet execution	Implemented
Expected-failure reporting	Implemented
Dashboard and report rendering	Implemented
Unit and API test suite	Implemented
Monorepo CI	Implemented
Published scenario PostgreSQL catalogue	Optional foundation implemented
Persistent run execution and evidence	Planned
Automated primary browser journey	Planned

Active work is tracked in GitHub Issues.

Troubleshooting

The deployed dashboard takes a long time to load

The free Render backend can sleep after inactivity. Wait for the first request to wake the service, then retry. Check the health endpoint if the delay continues.

The frontend cannot reach the backend

Confirm that ESURE_BACKEND_URL contains the backend origin without a trailing API path, for example https://esure.onrender.com, and redeploy the frontend after changing a Vercel environment variable.

The backend fails readiness in published mode

Published mode fails closed when DATABASE_URL is missing or migrations are stale. Apply the role bootstrap, migrations, and fixture reconciliation from the persistence guide, or return to PERSISTENCE_MODE=disabled while developing without PostgreSQL.

A live Testnet run fails during funding

Friendbot and Horizon are external Testnet services and can be temporarily unavailable or rate limited. Inspect the sanitized run error, wait briefly, and retry with a new isolated run.

Security

Esure rejects secret seeds, raw XDR, scripts, arbitrary URLs, unresolved references, unknown scenario properties, and Mainnet configuration. Generated Testnet secrets remain only in process memory during execution and are excluded from API responses, logs, and reports.

Please report vulnerabilities according to the security policy. Do not disclose sensitive findings in a public issue.

Contributing

Contributions are welcome. Before opening a pull request:

1. Read the contribution guide.
2. Choose or open a focused GitHub issue.
3. Keep changes within the documented Testnet-only safety boundary.
4. Run the relevant checks locally.
5. Link the pull request to its issue.

License

Esure is released under the MIT License.