Feat/indexer escrow funded - #84
Open
Olorunfemi20 wants to merge 2 commits into
Open
Conversation
Add an Escrow model to track funds locked in Soroban escrow contracts per delivery. The schema records the on-chain contract id, amount, asset, lock status lifecycle (pending, locked, released, refunded), and an append-only list of associated transaction hashes with type and ledger metadata. A unique index on contractId prevents duplicate escrow records, and a sparse unique index on transactions.hash guards against an indexer recording the same on-chain transaction twice. Covered by tests/escrow.model.test.ts using mongodb-memory-server against a real in-process MongoDB instance.
Add the escrow_funded indexer handler that syncs escrow funding from the Stellar Soroban smart contract into MongoDB, built on the Escrow schema. - src/indexer/escrowHandlers.ts parses the escrow_funded contract event (topics/value) into a typed payload and hands it to the service layer. A syncEscrowFundedEvents helper polls the configured Soroban RPC node via getEvents for new events on the escrow contract, since Soroban has no push/webhook mechanism. - src/services/escrow.service.ts creates or updates the Escrow document for the funded contract, appends the on-chain transaction hash, and updates the related Delivery status to funded. Processing is idempotent: replaying an already-recorded transaction hash is a no-op, so a re-run over an overlapping ledger range is safe. - src/controllers/escrow.controller.ts and src/routes/escrow.routes.ts expose the versioned endpoints GET /api/v1/escrow/delivery/:deliveryId, GET /api/v1/escrow/contract/:contractId, and POST /api/v1/escrow/sync (manual trigger for the indexer poll), following the existing controller -> service -> model layering used elsewhere in the app. - Delivery.status gains a FUNDED value. - ESCROW_CONTRACT_ID / ESCROW_FUNDED_EVENT_TOPIC added to config and .env.example. Covered by tests/escrow.service.test.ts and tests/escrowHandlers.test.ts using mongodb-memory-server against a real in-process MongoDB instance, with contract events built via the real stellar-sdk XDR encoder rather than hardcoded fixtures.
|
@Olorunfemi20 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
1 participant
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.
Closes #38
Depends on #37 (Escrow schema) — this branch is stacked on
feat/escrow-schema, please merge that first or set it as the base
branch for this PR.
Summary
Implements the indexer handler that syncs escrow funding from the
Stellar Soroban smart contract into MongoDB.
src/indexer/escrowHandlers.ts— parses theescrow_fundedcontractevent (topics/value) into a typed payload, and a
syncEscrowFundedEventshelper that polls the configured Soroban RPC node via
getEventsfornew events (Soroban has no push/webhook mechanism).
src/services/escrow.service.ts— creates or updates the Escrowdocument, appends the on-chain transaction hash, and updates the
related Delivery status to
funded. Idempotent: replaying analready-recorded transaction hash is a no-op.
src/controllers/escrow.controller.ts+src/routes/escrow.routes.ts— versioned endpoints following the existing controller -> service ->
model pattern:
GET /api/v1/escrow/delivery/:deliveryIdGET /api/v1/escrow/contract/:contractIdPOST /api/v1/escrow/sync(manually trigger an indexer poll)Delivery.statusgains afundedvalue.ESCROW_CONTRACT_ID/ESCROW_FUNDED_EVENT_TOPICadded to configand
.env.example.Work done
New: escrowHandlers.ts, escrow.service.ts, escrow.controller.ts,
escrow.routes.ts, config/escrow.ts, escrow.service.test.ts,
escrowHandlers.test.ts.
Modified: models/Delivery.ts (FUNDED status), routes/index.ts (mount
/v1/escrow), .env.example.
Test plan
npx jest tests/escrow.service.test.ts tests/escrowHandlers.test.ts—21 passed, using mongodb-memory-server against a real in-process
MongoDB instance (no mocked DB) and contract events built with the
real stellar-sdk XDR encoder rather than hardcoded fixtures
npx tsc --noEmit— no new type errorsnpx eslinton all new files — cleanNotes for reviewers
The exact field names inside the
escrow_fundedevent data map(
amount,asset,funded_by) are documented assumptions about thecompanion SwiftChain_SmartContract's event shape, since that contract's
source isn't in this repo — happy to adjust to match the actual ABI.