Skip to content

docs: add splits vs manual multi-send explainer (Closes #144)#305

Open
olaleyeolajide81-sketch wants to merge 4 commits into
tributary-protocol:mainfrom
olaleyeolajide81-sketch:docs/splits-vs-multisend-2
Open

docs: add splits vs manual multi-send explainer (Closes #144)#305
olaleyeolajide81-sketch wants to merge 4 commits into
tributary-protocol:mainfrom
olaleyeolajide81-sketch:docs/splits-vs-multisend-2

Conversation

@olaleyeolajide81-sketch

@olaleyeolajide81-sketch olaleyeolajide81-sketch commented Jul 18, 2026

Copy link
Copy Markdown

Summary

Closes #144. Adds an explainer doc comparing atomic splits to manual multi-send, and explains why atomic splits usually win. This is a documentation-only change — no contract, SDK, or app code is modified, so the Rust (cargo fmt / clippy / test), SDK, and App (npm run build) CI gates are unaffected.

What problem this solves

Issue #144 asks for a comparison that explains why atomic splits beat sending N separate transfers. When paying several parties, the naive path is to originate N independent transfers by hand. Tributary's split primitive instead stores the routing table on-chain and fans a single pay (or pay_many) out to every recipient atomically. The doc makes the trade-offs explicit so integrators reach for the right primitive.

Changes

  • New doc docs/splits-vs-multisend.md covering:
    • What "manual multi-send" means (N independent transfers, each its own op/auth/settlement).
    • What a split does instead (pay / pay_many fan-out from one stored routing rule).
    • Why atomic splits win, with concrete reasoning:
      • All-or-nothing settlement — a split pays every recipient inside one transaction; partial failure (a bad address, broken trustline, lapsed allowance) cannot leave a half-paid state the way sequential manual transfers can.
      • One signature, one transactionpay is a single authorization and network round-trip; pay_many extends that to several splits in one transaction.
      • Reusable and composable — the routing table lives on-chain and can be pushed through by anyone; splits can route to other splits, composing routing trees that would be error-prone to re-derive by hand every payment.
      • Exact, verifiable amounts — the contract computes each cut from fixed basis points and rounds dust to the last recipient (amount in = amount out), with preview_payout for exact per-recipient amounts before sending.
      • Inspectable routing — one readable split id vs a scattered set of transfers with no on-chain link.
    • Where manual multi-send still fits — one-off/ad-hoc payments, per-payment exact amounts that don't map to a stable basis-point table, and cases where you explicitly want each party settled independently even if another fails.
    • A comparison table (failure behavior, authorizations, reuse, composability, amount accuracy, routing visibility, best-for) and a bottom-line recommendation.
    • Two Mermaid diagrams (manual multi-send vs single pay) consistent with the style in docs/architecture.md.
  • README.md — links the new doc from the Docs section, matching the existing doc-link format.

Why this is safe / reviewable

  • One concern per PR (documentation only), per CONTRIBUTING.md.
  • No contract behavior changed, so the no_std + typed-error requirements and contract tests are not implicated.
  • No new code paths, so no new behavior tests are required.
  • Only docs/ and README.md are touched.

Test plan

  • Verified the new doc and the README link reference valid relative paths.
  • Confirmed no source files (contracts/sdk/app) were modified.
  • Maintainer to run cargo fmt --all, cargo clippy --all-targets -- -D warnings, cargo test, and npm run build in CI (unaffected by this change).

Checklist

  • One concern per pull request
  • Docs-only change, no behavior change requiring tests
  • Contract code unchanged (stays no_std, typed errors preserved)
  • Linked from README
  • CI gates not impacted by this change
    closes Add a comparison: splits vs manual multi-send #144

Closes tributary-protocol#134

Add a five-minute SDK quickstart (install, read a split, create one, pay
through it) and link it from the README. Include the new doc in the CI
markdown-link check.
Walk through building the splitter wasm and deploying it to testnet with
the Stellar CLI, referencing scripts/deploy.sh. Cover SDK regeneration,
dashboard wiring, and troubleshooting. Link from README and add to the
CI markdown-link-check job.

Closes tributary-protocol#143
Explains why atomic splits beat sending N separate transfers:
all-or-nothing settlement, one signature/transaction, reusable and
composable on-chain routing, contract-computed verifiable amounts, and
inspectable routing. Includes a comparison table and guidance on when
manual multi-send is still the right tool. Links the doc from the README.

Closes tributary-protocol#144
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a comparison: splits vs manual multi-send

1 participant