feat(contract): add preview_payout_deep for recursive leaf resolution

[MarcusDavidG]

Closes #265

What this does

Adds preview_payout_deep(id, amount) -> Result<Vec<(Address, i128)>, Error> to the splitter contract. This is the deep variant of preview_payout that resolves every Recipient::Split child recursively down to leaf Recipient::Account addresses.

Contract (contracts/splitter/src/lib.rs)

New public method: preview_payout_deep

pub fn preview_payout_deep(env: Env, id: u64, amount: i128) -> Result<Vec<(Address, i128)>, Error>

• Returns (Address, i128) pairs — leaf address alongside its final amount. No more positional-zip against get_split.
• Recurses through Recipient::Split children by loading each child split and applying amounts() at each level.
• Same rounding as pay: uses the existing amounts() helper at every level, so dust-to-last-recipient behaviour is bit-for-bit identical to an actual payment.
• Aggregates duplicates: if the same address appears as a leaf under multiple branches, amounts are summed into a single entry.
• Depth-bounded: new constant MAX_PREVIEW_DEPTH = 8. Calls that would exceed the cap return Error::BadChildSplit. At 32 recipients per split that covers trees with millions of theoretical leaf slots — far more than any real-world routing tree.

New private helper: resolve_deep

Recursive implementation with an injected depth counter. Separated from the public entry point so the guard and accumulation logic stay readable.

SDK (sdk/src/index.ts)

• preview_payout_deep added to the Client interface with return type Result<Array<readonly [string, i128]>>.
• Added to the fromJSON map.

App (app/src/lib/tributary.ts)

• previewPayoutDeep(id, amount) helper wraps the SDK call and returns { address: string; amount: bigint }[] for easy consumption by the Pay tab and the tree visualisation (Add a nested-split tree visualization #75).

Docs (README.md)

Added preview_payout_deep row to the Contract API table.

Tests (8 new, all pass — 49 total)

Test	What it verifies
deep_preview_flat_split_matches_shallow_preview	Flat split returns same numbers as preview_payout, paired with addresses
deep_preview_two_level_tree	2-level tree resolves correctly; preview matches actual pay + distribute
deep_preview_three_level_tree	3-level tree resolves correctly; preview matches actual pay + distribute chain
deep_preview_aggregates_shared_leaf_address	Same address under two branches → single aggregated entry
deep_preview_dust_rounding_matches_actual_pay	Tricky 3-way dust share at child level — preview matches real payout exactly
deep_preview_rejects_non_positive_amount	InvalidAmount for 0 and negative inputs
deep_preview_rejects_unknown_split	SplitNotFound for non-existent split id
deep_preview_depth_cap_is_enforced	9-deep chain returns BadChildSplit; 8-deep succeeds and sums to input amount

Acceptance criteria

Criteria	Status
Deep preview resolves nested splits to leaf accounts with exact final amounts	✅
Leaf amounts sum to the input amount	✅ tested at 2-level, 3-level, dust cases
Preview matches what an actual payment produces	✅ two-level and three-level verified
Recursion is depth-bounded and the bound is documented	✅ MAX_PREVIEW_DEPTH = 8 in lib.rs doc-comment
#69 and #75 can be built on it	✅ previewPayoutDeep app helper ready to use

[Spagero763]

contract fails on cargo fmt --all --check (diff starting around contracts/splitter/src/test.rs:1466) — no logic issue, just needs a formatting pass. Run cargo fmt --all locally and push.