render_example_test.gno

 1package pullpaymentdemo
 2
 3// ExampleRender pins the realm's Render output as a testable example.
 4func ExampleRender() {
 5	print(Render(""))
 6	// Output:
 7	// # Pull Payment
 8	//
 9	// Credit and let recipients withdraw, demoing the [`p/moul/x/daily/pullpayment`](/p/nym-moultest123/x/daily/pullpayment/v0) library.
10	//
11	// ## Why not just send?
12	//
13	// Pushing value hands control to the recipient in the middle of your state transition, and a hostile recipient re-enters before you have finished updating. Pulling inverts it: you record a debt, and the recipient's own withdrawal is the only state being touched.
14	//
15	// ## A split, credited
16	//
17	// | payee | owed |
18	// |---|---|
19	// | `alice` | 500 |
20	// | `bob` | 300 |
21	// | `carol` | 200 |
22	//
23	// The holding realm must keep `1000` in reserve — that is what `TotalOwed` is for.
24	//
25	// ## Bob claims
26	//
27	// `Withdraw("bob")` → `300`, and the ledger is updated **before** the caller transfers anything:
28	//
29	// | payee | owed |
30	// |---|---|
31	// | `alice` | 500 |
32	// | `carol` | 200 |
33	//
34	// Reserve is now `700`.
35	//
36	// ## The reentrancy attempt
37	//
38	// Bob's handler calls straight back in, before the transfer completes:
39	//
40	// - second `Withdraw("bob")` → `0`, error: `pullpayment: nothing to withdraw`
41	//
42	// Nothing left to take. The balance was deleted before control left the function — checks, effects, *then* interactions. Lifetime withdrawn is still `300`, not double.
43	//
44	// ## Credits accumulate
45	//
46	// `Credit("alice", 100)` on top of her existing balance:
47	//
48	// | payee | owed |
49	// |---|---|
50	// | `alice` | 600 |
51	// | `carol` | 200 |
52	//
53	// One withdrawal collects the lot — no dust left behind.
54	//
55	// ## Batch credits are all-or-nothing
56	//
57	// A split that is partly invalid applies **none** of itself; a ledger half-agreeing with the funds it guards is worse than a rejected call:
58	//
59	// - `CreditMany([dave, eve], [10, -1])` → `pullpayment: amount must be positive`
60	// - total owed before: `800`, after: `800` — unchanged, and `dave` was not credited
61}