feat: add streaming dividends example (DividendTreasury + StreamingShare) - #59
Draft
tiero wants to merge 1 commit into
Draft
feat: add streaming dividends example (DividendTreasury + StreamingShare)#59tiero wants to merge 1 commit into
tiero wants to merge 1 commit into
Conversation
Add examples/dividend_stream/: a two-contract corporate dividend rail where the dividend accrues continuously at one-second granularity (tx.offchainTime), fixed in USD cents per unit-year, paid in sats at an oracle-attested BTC/USD price. Motivated by a hypothetical pilot for a listed Bitcoin treasury company: batch dividend rails cap ambition at monthly payouts and need record dates, transfer agents and distribution runs; continuous accrual removes the batch entirely (see dividend_stream.md). - DividendTreasury: singleton BTC reserve. Permissionless topUp (reserve only grows — public recurring-cash-flow time series), permissionless service of one claim per co-spend (recomputes accrual, pays the holder, and requires the position re-created with lastClaim = now so the same second is never paid twice), issuer-gated recall, CSV unilateral exit. - StreamingShare: per-holder position (units, lastClaim). claim co-spends the treasury (cross-input scriptPubKey binding via this.activeInputIndex, bonds-style); transfer is a pure key swap that carries accrual with the position (no ex-dividend cliff, no record date); split keeps lastClaim so it is exactly accrual-fair; CSV unilateral exit. - Accrual: units × annualDividendCents × elapsed / 31536000, int64-safe for realistic sizes; accruedCents > 0 guards basis-advance griefing; 330-sat dust floor on claims. - Tests: 13 behavioral tests (oracle message reconstruction, cross-input inspection, permissionless topUp/service, issuer-gated recall, key-swap purity, basis-advance recreation placeholders, CSV exits, synthesized cooperative leaves, shared constructor schema) + 2 roundtrip entries. Full suite green, cargo fmt clean. - Playground: Streaming Dividends project registered in main.js. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CmsjJ5rEDp6DE42kvauYD2
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Playground PreviewA live preview of this PR's playground is available at:
|
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
2 participants
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
Adds a complete streaming-dividend program demonstrating continuous per-second accrual of fixed USD-cent dividends paid in sats at an oracle-attested BTC/USD price. The program consists of two covenants that co-spend in claim transactions:
DividendTreasury(singleton reserve) andStreamingShare(per-holder position).Key Changes
New contracts:
examples/dividend_stream/dividend_treasury.ark— issuer-funded reserve withtopUp(permissionless),service(permissionless claim servicing),recall(issuer-gated withdrawal), and CSV unilateral exitexamples/dividend_stream/streaming_share.ark— per-holder position withclaim(holder-signed dividend settlement),transfer(key swap),split(accrual-fair division), and CSV unilateral exitexamples/dividend_stream/dividend_stream.md— design documentation covering accrual mechanics, claim transaction layout, oracle model, trust model, and relation to other examplesNew test suite (
tests/examples/dividend_stream.rs):Integration test updates (
tests/examples/compilation_roundtrip.rs): roundtrip compilation tests for both contractsPlayground registration (
playground/main.js):dividend_streamproject with name and descriptionTest module registration (
tests/examples.rs):dividend_streammodule added to the suiteImplementation Details
The program demonstrates several Arkade patterns:
serviceandclaimfunctions in separate contracts verify each other's scriptPubKey via witness-declared statetx.offchainTimefor one-second granularity; accrual formula:units × annualDividendCents × elapsed / 31536000transferandsplitpreservelastClaim, so accrued-but-unclaimed dividends travel with the positionaccruedCents > 0guardThe test suite validates the complete specification: oracle attestation paths, accrual math bounds, permission gates, position state advancement, and output routing. Full
cargo testgreen (357 tests),cargo fmt --checkclean.🤖 Generated with Claude Code
https://claude.ai/code/session_01CmsjJ5rEDp6DE42kvauYD2
Generated by Claude Code