[Advanced] Generic Stellar Disbursement Platform (SDP) reconciliation adapter via Nirium's Audit Trail

[Eras256]

Difficulty: Advanced (senior · 7/10). ~14–20h. TypeScript, Stellar Horizon (operations/effects), IPFS.

Context

Stellar Disbursement Platform (SDP) is the SDF's own open-source, self-hostable bulk-payment platform, and it has no independent, cryptographically-anchored reconciliation trail of its own — a batch either succeeded or it didn't, with no third-party-verifiable proof pack. Providencia Onchain (VIIO + Climate Future) already built exactly this pattern by hand, for one case: linking every conservation-payout disbursement to its on-chain tx hash so sponsors and auditors can independently verify. That's real, working prior art — credit it, don't duplicate it. What doesn't exist is the generic, reusable version: a library any SDP self-hoster (or any Stellar disbursement product) could plug in, instead of building a bespoke dashboard per deployment.

Goal

An adapter under examples/sdp-audit-bridge/ that takes a completed disbursement batch (a list of tx hashes, or a source account + time window), independently re-verifies each payment on-chain via Horizon, builds one small aggregate record (recipient count, total amount, asset, tx hashes — never raw recipient PII), and anchors it via Nirium's anchorAuditRecord().

Scope / Deliverables

1. A function/script that takes a batch descriptor (tx hashes, or { sourceAccount, from, to }) and reads the actual payment operations from Horizon — don't trust an "it succeeded" flag from any upstream system, confirm on-chain.
2. Build the aggregate JSON record and anchor it with anchorAuditRecord({ record, agent }) — signed if an agent key is configured, per the domain-separated statement nirium-audit-v1:<content_sha256> (recomputed from the record, never trusted from a caller-supplied field — same forgery class already fixed on this repo in PR feat(cli): add standalone offline audit-CID and ed25519 agent-attestation verifier #60).
3. A separate verification script that, given only the resulting CID, fetches it from IPFS, recomputes the hash, and independently re-checks every cited tx hash against Horizon — so a third party (auditor, donor, grant funder) can verify without trusting Nirium or the batch operator.
4. README that explicitly credits Providencia Onchain's pattern and explains the generalization: a reusable library, not a competing bespoke dashboard.

Acceptance criteria

• Runs end-to-end against a real disbursement batch on testnet (≥3 real payment operations) — the resulting CID and at least one independently-verified tx hash go in the PR.
• The verification script re-derives the hash and re-checks Horizon itself — it does not just print what the anchored document claims.
• README's prior-art section is accurate: it names Providencia Onchain and states the actual difference (generic/reusable vs. one bespoke deployment), no overclaiming originality.

Pointers

• SDP: https://stellar.org/products-and-tools/disbursement-platform
• Providencia Onchain / VIIO: https://github.com/itrmachines/viio_poc — read the pattern, don't fork the code; this is deliberately a separate, generic library.
• Nirium: anchorAuditRecord() / getReportingExport() in packages/sdk/src/index.ts; POST /api/audit/log rejects an invalid agent signature with 400 and never anchors it — a broken signer fails loud.

Out of scope

• Building a full SDP fork or a hosted dashboard.
• Any custody of disbursement funds — this only reads and anchors, never moves money.
• Mainnet (testnet only, unless working against an already-public mainnet disbursement).

References

• Dev docs: https://nirium.xyz/developers
• This repo's README: https://github.com/nirium-protocol/nirium-sdk/blob/main/README.md
• Contributing guide (how the GrantFox apply/assign flow works here): https://github.com/nirium-protocol/nirium-sdk/blob/main/CONTRIBUTING.md
• TypeScript SDK (npm): https://www.npmjs.com/package/nirium
• CLI (npm): https://www.npmjs.com/package/nirium-cli
• MCP server (npm): https://www.npmjs.com/package/nirium-mcp
• Questions: comment directly on this issue — there's no separate community chat for this repo yet.

Reward

Eligibility is subject to GrantFox review under this campaign. Rewards are decided by GrantFox based on quality and available budget and are not guaranteed.

[Flames4fun]

Hey @Eras256 I spent some time reading through the reconciliation flow and PR #60 before asking for this one. I’d like to work on #71 if you’re comfortable assigning it to me.

There’s a strong overlap with work I’ve already had merged upstream. In Vero Audit Guard # 324 I implemented an audit verification path that recomputes a local SHA-256 digest and verifies the exact Stellar transaction/anchor instead of trusting locally reported evidence. I also recently worked on NBS Bond # 229, where settlement is rejected unless externally supplied balances reconcile exactly with the contract’s subscribed total, and on OWASP ASRH # 107, where a review led me to harden canonical evidence against an entire class of forged metadata rather than only the original example.

That background is a big part of why this issue caught my attention: the verifier here should be genuinely independent, not merely a second parser for a document produced by the first script.

My working hypothesis would be to make the Horizon-derived representation the canonical source of truth: resolve the supplied batch descriptor, fetch and validate the actual payment operations, normalize them into one deterministic aggregate record, then let anchorAuditRecord() commit to that record. The verifier would start from only the CID, recompute the record hash itself and independently resolve the cited transactions through Horizon before accepting anything. I’d also make sure transaction success alone isn’t treated as sufficient evidence when a transaction can contain multiple operations — the payment operation, asset, amount/source and inclusion need to agree with the record we are verifying.

I’ve also noted the nirium-audit-v1:<content_sha256> requirement and the forgery class fixed in #60; I would derive that value from the canonical record rather than ever accepting a caller-provided digest.

This one is large enough that I don’t want to give you an unrealistic 1–3 hour estimate. I’d budget roughly 14–18 focused hours for the complete PR, including the real testnet batch, IPFS CID, independently verified transaction evidence and README. If Horizon/IPFS setup is straightforward, I should have the core implementation substantially earlier.

I’d be glad to take ownership of it and keep the implementation narrowly within the reusable adapter/verifier scope described here.

[angelraph]

Hello maintainer I will like to work on #71. I like the idea of having a simple way to independently verify SDP payments instead of relying on the disbursement system’s own status.

I’ll build the Horizon verification, aggregate the payment data without exposing recipient PII, anchor the record through Nirium, and add the independent IPFS and transaction verification flow.

I’ll also test it with real Stellar testnet payments and keep the implementation focused.

[sebas11042]

Hi! I’m a software developer and open-source contributor with experience in backend development, Stellar-related payment flows, databases, reconciliation, and verifying financial state against an authoritative source rather than trusting application-level status flags. I’m especially interested in auditability and idempotent verification flows where a third party should be able to independently prove that a reported payment batch actually matches what happened on-chain.

For this issue, I’d build the SDP audit bridge so each referenced disbursement is independently resolved through Horizon, normalized into a deterministic aggregate record without recipient PII, and anchored through Nirium only after the content hash has been recomputed locally and, when configured, signed with the expected domain-separated Ed25519 statement. I’d also implement the standalone verification path from CID → IPFS document → content-hash recomputation → Horizon re-verification of every cited transaction, and include end-to-end testnet evidence with at least three real payment operations plus negative tests for tampered records, missing transactions, asset/amount mismatches, and invalid attestations.

[Eras256]

Assigned to @Flames4fun — this is the strongest application of the three, and it's verifiable, not just stated. Checked both cited PRs directly:

• Vero-protocol/vero-audit-guard#324 (merged 22-ago) — recomputes the hash locally, fetches the specific transaction from Horizon, and fails if the on-chain digest doesn't match. That's the exact discipline this issue needs: verify against the ledger, never trust a reported status.
• nbs-bond/nbs-bond-protocol#229 (merged 23-ago) — rejects settlement unless the accumulated balance reconciles exactly against the on-chain subscription total.

Both are real, merged, and match what's claimed. Go ahead and open the PR when ready — the acceptance criteria in the issue body stand as written (independent re-verification against Horizon, the Providencia Onchain credit in the README, no custody).

[grantfox-oss]

🦊 GrantFox — @Flames4fun has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #71)
2. Your PR will be reviewed by the nirium-protocol maintainers

Good luck! Track your progress on GrantFox.