Feature/my work

[SHEROSE0]

#closes #15

feat(stellar): 1-to-N stealth payment splitter contract

Overview

Implements a new Soroban contract module contracts/stellar/stealth-splitter/ introducing a 1-to-N weighted stealth payment splitter.

A single funded deposit is distributed across multiple beneficiaries according to predefined weights, while preserving stealth address unlinkability and keeping recipient-level payout details off-chain.

This primitive is intended for DAO distributions, revenue sharing, royalties, and batch payout systems where allocation rules are public but execution outputs remain private.

Changes

Split creation

• create_split(beneficiaries, asset, salt) -> SplitId

• Supports up to 25 beneficiaries

• Each beneficiary is (meta_address, weight)

• SplitId is deterministically derived from:

  • beneficiary set
  • asset
  • salt

• Immutable after creation (no updates allowed)

Funding + distribution

• fund_split(split_id, amount)

• Distributes funds proportionally based on weights

• Executes all transfers in a single atomic flow:

  • failure → full rollback

• Each payout:

  • generates ephemeral stealth transfer data
  • emits standard stealth announcement event for scanning

Split query

• get_split(split_id) -> SplitDetails

• Returns:

  • beneficiaries
  • weights
  • total funded amount

• Does not expose stealth addresses or execution-level payout data

Design notes

• Immutability: Split configuration is fixed at creation to guarantee deterministic payout behavior.
• Ephemeral execution: stealth outputs are generated during execution only and not persisted in contract state.
• Rounding strategy: integer remainder is assigned to the first beneficiary to ensure deterministic handling of dust.
• Resource constraint: capped at 25 beneficiaries to stay within Soroban execution/storage limits.
• Atomicity: full rollback enforced on any intermediate failure during distribution.

Tests

• Unit tests for:

  • split creation
  • funding flow
  • split retrieval

• Property-based validation for weight proportionality

• Adversarial cases:

  • invalid beneficiary input
  • overflow / rounding edge cases
  • replay / double funding attempts

• Atomicity test ensuring full rollback on mid-execution failure

Notes for reviewers

• This contract is intentionally stateless with respect to payout execution results.
• All sensitive routing (stealth address generation) is handled ephemerally during execution.
• Designed to be paired with batch sender (stealth-batch-sender Soroban contract #9) for complementary payout workflows.

#closes

[drips-wave]

@SHEROSE0 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! 🚀

Learn more about application limits

[truthixify]

The splitter design lands cleanly: immutable split definitions, deterministic SplitId = sha256(beneficiaries || asset || salt), atomic distribution via Soroban transaction semantics, weighted shares with dust-to-first-beneficiary, max-25-beneficiaries cap, and checked_add for weight overflow. The caller pre-computes stealth addresses off-chain and passes them in alongside ephemeral keys, which is the right call (contracts can't generate randomness for ephemeral keys).

Two small things worth tightening in a follow-up (not blocking):

1. In fund_split you return SplitterError::SplitNotFound when the input vector lengths do not match num_beneficiaries, and you have a comment acknowledging it. Add an explicit SplitterError::LengthMismatch variant and use it. Sloppy errors make debugging the SDK harder.
2. The 4 doc files (DESIGN, README, TESTING_GUIDE, VERIFICATION) are great content but overlap a lot. Consider folding them into one README.md plus a short DESIGN.md rationale doc. Easier for future contributors to find the canonical source.

Could you also file the SDK follow-up issue for the buildSplitDeposit builder and the demo follow-up for the "Split a payment among N recipients" UI? Those were called out in the issue spec and will let downstream contributors pick this up immediately.

Thanks @SHEROSE0, real work.