We hatch odd little apps in Saigon. Now: 6pm, an iPhone expense tracker you never type into. Code: github.com/at6pm/6pm · X: @OddEggsStudio · oddeggs.studio
Same lesson from our budgeting app: the only division that really matters is free money ÷ days left, and we put the floor to whole thousands of đồng in the function's name so nobody has to guess. The leftover isn't lost either, it stays in the month and turns up in tomorrow's line when it's recomputed.
Senior full-stack engineer, no agency layer. I design, ship, and run payments, crypto rails, marketplaces, and LLM pipelines. Ten years in production; crypto since 2018.
That’s a great example of why the rounding policy should be explicit. I especially like that the remainder isn’t discarded but carried forward into the next calculation.
One subtle distinction is that rounding down a daily budget and allocating money across recipients are different operations. In your case, recalculating from the remaining balance each day preserves the leftover naturally. For payments or payouts, though, explicitly allocating the remainder can be important to ensure the individual shares always add up to the original amount.
We hatch odd little apps in Saigon. Now: 6pm, an iPhone expense tracker you never type into. Code: github.com/at6pm/6pm · X: @OddEggsStudio · oddeggs.studio
Good distinction. Recomputing from what's left means the rounding never piles up for us, but with a split you're right: someone has to own the leftover đồng or the shares won't add back to the total.
Senior full-stack engineer, no agency layer. I design, ship, and run payments, crypto rails, marketplaces, and LLM pipelines. Ten years in production; crypto since 2018.
The owner is positional in allocate: the remainder goes out one base unit at a time to the earliest shares with a nonzero weight, and a zero weight stays at zero. split(parts) is just allocate([1] * parts), so the first entries in the list soak it up. That makes the leftover deterministic instead of fair. Pass recipients in the same order every period and the same share keeps picking up the extra unit, and rotating that is on the caller, since a Money holds no state between calls. I think that asymmetry belongs in the docstring rather than in a strategy parameter, and writing it down goes on the list.
One detail that matters for payouts specifically: allocate sizes the shares from the magnitude and puts the sign back at the end, so a negative total splits as -4, -3, -3 instead of the -4, -4, -4 that floor division gives you. A refund is the same operation as a payout as far as the type cares, which is what you want when a reversal has to clear exactly as much as went out and not a unit more.
Your recompute model is the closed case: the leftover never leaves the balance you read again the next day, so there is nothing to assign. divide is the open one, where a unit really does end up outside the result. That is the whole reason divide takes a mandatory rounding while split and allocate refuse one at all.
We hatch odd little apps in Saigon. Now: 6pm, an iPhone expense tracker you never type into. Code: github.com/at6pm/6pm · X: @OddEggsStudio · oddeggs.studio
The sign handling is the part I hadn't thought through: -4, -4, -4 clears 12 on a 10 refund, and that's exactly the kind of bug nobody notices until reconciliation. Agree on the docstring over a strategy parameter, "earliest shares soak up the remainder" is easy to work around once it's written down.
Senior full-stack engineer, no agency layer. I design, ship, and run payments, crypto rails, marketplaces, and LLM pipelines. Ten years in production; crypto since 2018.
The sign asymmetry doesn't stop at allocate. It changes what a rounding mode means, and that's the part that took me longest to internalize. decimal's modes are defined relative to zero, not relative to minus infinity: ROUND_DOWN truncates toward zero, ROUND_UP moves away from it, so on a negative total divide(3, rounding=ROUND_DOWN) of -10 satoshi gives you -3 per share and ROUND_UP gives -4. The names read like smaller and larger. They mean less magnitude and more magnitude.
So allocate agrees with six of the eight modes: both are symmetric about zero, so negating the input negates the result element by element. ROUND_FLOOR and ROUND_CEILING are the two that aren't, and they're the ones that reproduce integer floor division on a refund. That bears on the boundary I argued for at the end of the post. A service that fixes one mode per direction of flow, fees one way and payouts the other, has fixed it while looking at a positive amount, and the same constant handed to a reversal rounds the other way in value unless the mode happens to be a symmetric one.
I wouldn't have the type refuse ROUND_FLOOR. It's the right mode when you want a bound rather than a share. But the docstring note I owe you now has a second half: allocate sizes the shares from the magnitude and puts the sign back, divide rounds relative to zero, and those two directional modes are where a negative amount stops mirroring a positive one. A case in tests/test_precision_edges.py pinning divide on a negative total across both of them goes on the list with it.
The refund example makes me wonder about recipient order. If the caller rotates that order between payouts, negating the total and allocating again could put the extra unit against a different person. I'd keep the original per-recipient allocation and reverse those amounts. The total balancing is one check; each person getting the right reversal is another.
Senior full-stack engineer, no agency layer. I design, ship, and run payments, crypto rails, marketplaces, and LLM pipelines. Ten years in production; crypto since 2018.
Order is the part you have right. allocate takes weights, not recipients, so a share lands on a person purely by its position in the list, and the remainder goes to the earliest shares. Reverse it by negating the amounts you already handed out, one per recipient, instead of re-deriving them.
One correction: negating the total and allocating again is exact as long as the weights and their order are identical. split(3) on -10 satoshi gives -4, -3, -3, the mirror of 4, 3, 3. The bug sits in the rotation, and the negation is fine. I'll write the positional correspondence into the allocate docstring and add a test in tests/test_round_trips.py: the negated allocation equals each share negated.
Senior full-stack engineer, no agency layer. I design, ship, and run payments, crypto rails, marketplaces, and LLM pipelines. Ten years in production; crypto since 2018.
The negation case is pinned down in the cryptomoney repository now: there is a test asserting that allocating a negated amount returns every share negated, so the same weights in the same order give you an exact per-recipient reversal, not just a matching total. That assertion came out of your comment.
The docs also state the share order and where the remainder lands, which is what lets a caller rely on "same order" instead of reading allocate to find out.
We're a place where coders share, stay up-to-date and grow their careers.
Same lesson from our budgeting app: the only division that really matters is free money ÷ days left, and we put the floor to whole thousands of đồng in the function's name so nobody has to guess. The leftover isn't lost either, it stays in the month and turns up in tomorrow's line when it's recomputed.
That’s a great example of why the rounding policy should be explicit. I especially like that the remainder isn’t discarded but carried forward into the next calculation.
One subtle distinction is that rounding down a daily budget and allocating money across recipients are different operations. In your case, recalculating from the remaining balance each day preserves the leftover naturally. For payments or payouts, though, explicitly allocating the remainder can be important to ensure the individual shares always add up to the original amount.
Thanks for sharing a real-world example!
Good distinction. Recomputing from what's left means the rounding never piles up for us, but with a split you're right: someone has to own the leftover đồng or the shares won't add back to the total.
The owner is positional in
allocate: the remainder goes out one base unit at a time to the earliest shares with a nonzero weight, and a zero weight stays at zero.split(parts)is justallocate([1] * parts), so the first entries in the list soak it up. That makes the leftover deterministic instead of fair. Pass recipients in the same order every period and the same share keeps picking up the extra unit, and rotating that is on the caller, since aMoneyholds no state between calls. I think that asymmetry belongs in the docstring rather than in a strategy parameter, and writing it down goes on the list.One detail that matters for payouts specifically:
allocatesizes the shares from the magnitude and puts the sign back at the end, so a negative total splits as -4, -3, -3 instead of the -4, -4, -4 that floor division gives you. A refund is the same operation as a payout as far as the type cares, which is what you want when a reversal has to clear exactly as much as went out and not a unit more.Your recompute model is the closed case: the leftover never leaves the balance you read again the next day, so there is nothing to assign.
divideis the open one, where a unit really does end up outside the result. That is the whole reasondividetakes a mandatoryroundingwhilesplitandallocaterefuse one at all.The sign handling is the part I hadn't thought through: -4, -4, -4 clears 12 on a 10 refund, and that's exactly the kind of bug nobody notices until reconciliation. Agree on the docstring over a strategy parameter, "earliest shares soak up the remainder" is easy to work around once it's written down.
The sign asymmetry doesn't stop at
allocate. It changes what a rounding mode means, and that's the part that took me longest to internalize.decimal's modes are defined relative to zero, not relative to minus infinity:ROUND_DOWNtruncates toward zero,ROUND_UPmoves away from it, so on a negative totaldivide(3, rounding=ROUND_DOWN)of -10 satoshi gives you -3 per share andROUND_UPgives -4. The names read like smaller and larger. They mean less magnitude and more magnitude.So
allocateagrees with six of the eight modes: both are symmetric about zero, so negating the input negates the result element by element.ROUND_FLOORandROUND_CEILINGare the two that aren't, and they're the ones that reproduce integer floor division on a refund. That bears on the boundary I argued for at the end of the post. A service that fixes one mode per direction of flow, fees one way and payouts the other, has fixed it while looking at a positive amount, and the same constant handed to a reversal rounds the other way in value unless the mode happens to be a symmetric one.I wouldn't have the type refuse
ROUND_FLOOR. It's the right mode when you want a bound rather than a share. But the docstring note I owe you now has a second half:allocatesizes the shares from the magnitude and puts the sign back,dividerounds relative to zero, and those two directional modes are where a negative amount stops mirroring a positive one. A case intests/test_precision_edges.pypinningdivideon a negative total across both of them goes on the list with it.The refund example makes me wonder about recipient order. If the caller rotates that order between payouts, negating the total and allocating again could put the extra unit against a different person. I'd keep the original per-recipient allocation and reverse those amounts. The total balancing is one check; each person getting the right reversal is another.
Order is the part you have right.
allocatetakes weights, not recipients, so a share lands on a person purely by its position in the list, and the remainder goes to the earliest shares. Reverse it by negating the amounts you already handed out, one per recipient, instead of re-deriving them.One correction: negating the total and allocating again is exact as long as the weights and their order are identical.
split(3)on -10 satoshi gives -4, -3, -3, the mirror of 4, 3, 3. The bug sits in the rotation, and the negation is fine. I'll write the positional correspondence into theallocatedocstring and add a test intests/test_round_trips.py: the negated allocation equals each share negated.The negation case is pinned down in the cryptomoney repository now: there is a test asserting that allocating a negated amount returns every share negated, so the same weights in the same order give you an exact per-recipient reversal, not just a matching total. That assertion came out of your comment.
The docs also state the share order and where the remainder lands, which is what lets a caller rely on "same order" instead of reading
allocateto find out.