Skip to main content
Dynamic Fee Sharing uses cumulative share accounting. Funding increases the value of each share, and each recipient stores a checkpoint for the share value they have already claimed.
The program performs integer arithmetic. This page shows the same formulas in product terms, with the important units and rounding behavior called out.

​
Units

​
Total Shares

The vault adds all recipient shares together. Total Share=∑iRecipient Sharei\text{Total Share} = \sum_i \text{Recipient Share}_i Each recipient’s expected proportion is: Recipient Proportion=Recipient ShareTotal Share\text{Recipient Proportion} = \frac{\text{Recipient Share}}{\text{Total Share}} Example: The total share is 100, so the shares map directly to percentages. The same split could also be represented as 5, 3, and 2 shares.

​
Manual Funding Amount

Manual funding takes max_amount, but the program never transfers more than the source token account currently holds: Transfer Amount=min⁡(max_amount,source token account balance)\text{Transfer Amount} = \min(\text{max\_amount}, \text{source token account balance}) If Transfer Amount = 0, the instruction fails. For standard SPL Token mints, the funded amount is the transfer amount: Funded Amount=Transfer Amount\text{Funded Amount} = \text{Transfer Amount} For supported Token 2022 transfer-fee mints, the program calculates the transfer fee for the current epoch and accounts for the amount excluding that fee: Funded Amount=Transfer Amount−Transfer Fee\text{Funded Amount} = \text{Transfer Amount} - \text{Transfer Fee} This prevents funding accounting from crediting more tokens than the token vault receives.

​
Claim-By-Integration Funding

When a PDA vault funds itself through fund_by_claiming_fee, the program measures the token vault balance before and after the whitelisted CPI. Claimed Amount=Token Vault Balance After−Token Vault Balance Before\text{Claimed Amount} = \text{Token Vault Balance After} - \text{Token Vault Balance Before} If Claimed Amount > 0, the vault adds that amount to fee accounting: Funded Amount=Claimed Amount\text{Funded Amount} = \text{Claimed Amount} If the balance does not increase, the program does not update fee accounting or emit a fund event.

​
Fee Per Share

Each time new fees enter the vault, the vault increases the cumulative fee-per-share value. Conceptually: Fee Per Share Increase=Funded AmountTotal Share\text{Fee Per Share Increase} = \frac{\text{Funded Amount}}{\text{Total Share}} In the program: Fee Per Share Increase=⌊Funded Amount×264Total Share⌋\text{Fee Per Share Increase} = \left\lfloor \frac{\text{Funded Amount} \times 2^{64}}{\text{Total Share}} \right\rfloor Then it updates the cumulative value: New Fee Per Share=Previous Fee Per Share+Fee Per Share Increase\text{New Fee Per Share} = \text{Previous Fee Per Share} + \text{Fee Per Share Increase} The vault also increases total_funded_fee: Total Funded Feenew=Total Funded Feeold+Funded Amount\text{Total Funded Fee}_{new} = \text{Total Funded Fee}_{old} + \text{Funded Amount}

​
Claimable Fee

Each recipient stores a checkpoint: the fee-per-share value they had already claimed up to. When the recipient claims, the vault calculates the difference between the current fee-per-share and that recipient’s checkpoint. Unclaimed Fee Per Share=Current Fee Per Share−Recipient Checkpoint\text{Unclaimed Fee Per Share} = \text{Current Fee Per Share} - \text{Recipient Checkpoint} Then the vault multiplies that delta by the recipient’s share: Claimable Fee=⌊Recipient Share×Unclaimed Fee Per Share264⌋\text{Claimable Fee} = \left\lfloor \frac{\text{Recipient Share} \times \text{Unclaimed Fee Per Share}}{2^{64}} \right\rfloor After the claim, the recipient’s checkpoint and total claimed amount are updated: Recipient Checkpoint=Current Fee Per Share\text{Recipient Checkpoint} = \text{Current Fee Per Share} Fee Claimednew=Fee Claimedold+Claimable Fee\text{Fee Claimed}_{new} = \text{Fee Claimed}_{old} + \text{Claimable Fee} This is how the vault prevents double-claiming while still allowing recipients to claim independently.
The checkpoint updates even when Claimable Fee rounds down to 0. For very small funding amounts or very large total-share values, claiming too early can round the user’s current entitlement to zero and advance their checkpoint.

​
Worked Example

Assume a vault has three recipients: Total share: 50+30+20=10050 + 30 + 20 = 100 A funder adds 1,000 USDC into the vault. The expected distribution is: Creator=1,000×50100=500\text{Creator} = 1{,}000 \times \frac{50}{100} = 500 Partner=1,000×30100=300\text{Partner} = 1{,}000 \times \frac{30}{100} = 300 Treasury=1,000×20100=200\text{Treasury} = 1{,}000 \times \frac{20}{100} = 200 If the creator claims first, the creator receives 500 USDC and the creator’s checkpoint updates. The partner and treasury can claim later; their balances remain claimable because their checkpoints have not moved.

​
Multiple Funding Events

Dynamic Fee Sharing supports repeated funding. Example: Total funded fee: Total Funded Fee=1,000+500+250=1,750\text{Total Funded Fee} = 1,000 + 500 + 250 = 1,750 A 30% recipient would be entitled to: 1,750×30%=525 USDC1{,}750 \times 30\% = 525 \text{ USDC} If that recipient already claimed 300 USDC after the first funding event, the next claim would be around 225 USDC, subject to integer rounding.

​
Remaining Vault Balance

For standard SPL Token mints, the token vault balance usually represents funded fees that have not yet been claimed, plus small rounding dust. Simplified formula: Remaining Vault Balance=Total Funded Fee−∑iTotal Claimed By Recipienti\text{Remaining Vault Balance} = \text{Total Funded Fee} - \sum_i \text{Total Claimed By Recipient}_i Because token amounts are integers and fee_per_share increments are floored, small dust can remain when funded amounts do not divide evenly across shares.

​
Transfer-Fee Token Claims

For supported Token 2022 transfer-fee mints, manual funding credits the net amount received by the token vault. Claims are different: the program calculates a gross Claimable Fee and transfers that amount from the token vault to the recipient token account. If the mint charges a transfer fee on that outgoing transfer, the recipient token account may receive less than the gross claimed amount. Net Received By Recipient=Claimable Fee−Outgoing Transfer Fee\text{Net Received By Recipient} = \text{Claimable Fee} - \text{Outgoing Transfer Fee} The program’s fee_claimed field tracks the gross claimed amount.

​
Rounding and Precision

The program uses high-precision fee-per-share accounting by scaling calculations with 2^64. This helps preserve precision for small funding amounts and large total-share values. The program includes a property test that checks small funded amounts still produce a non-zero fee_per_share even when total_share is u32::MAX. Even with high precision, final claim amounts are integer token amounts. If a funded amount cannot be split perfectly between recipients, dust can remain in the vault.
For product planning, choose share weights that are easy to communicate. Percent-style totals such as 100, 1,000, or 10,000 are usually easier for teams and recipients to reason about.