docs: add splits vs manual multi-send explainer (Closes #144)#305
Open
olaleyeolajide81-sketch wants to merge 4 commits into
Open
Conversation
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
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
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.
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(orpay_many) out to every recipient atomically. The doc makes the trade-offs explicit so integrators reach for the right primitive.Changes
docs/splits-vs-multisend.mdcovering:pay/pay_manyfan-out from one stored routing rule).payis a single authorization and network round-trip;pay_manyextends that to several splits in one transaction.preview_payoutfor exact per-recipient amounts before sending.pay) consistent with the style indocs/architecture.md.README.md— links the new doc from the Docs section, matching the existing doc-link format.Why this is safe / reviewable
no_std+ typed-error requirements and contract tests are not implicated.docs/andREADME.mdare touched.Test plan
cargo fmt --all,cargo clippy --all-targets -- -D warnings,cargo test, andnpm run buildin CI (unaffected by this change).Checklist
no_std, typed errors preserved)closes Add a comparison: splits vs manual multi-send #144