Definitions and fields used across the Mean Protocol
The treasury pool represents a pool of SPL tokens used as the funding source for one or more money streams (see below). All amounts pending distribution are Locked in Treasury Pools across the Money Streaming Protocol.
treasury_address: The unique identifier for the treasury account. This address is shared across all streams created by the same treasurer for this address. The MSP is the owner of the treasury account, and therefore, the only one that can debit from it.
treasury_estimated_depletion_utc: The estimated UTC time when the balance of the treasury_address will reach $0, provided no additional funds are added between now and then. This value will change if additional funds are added to the treasury by contributors or if the beneficiary stream(s) are updated (i.e., rate change, new beneficiaries added/removed, etc.).
The treasurer is the person or account address setting up a treasury pool to distribute funds from.
treasurer_address: The address creating a money streaming contract. This address also must be the one that created the treasury (owned by the program) funding the contract. Only one treasurer exists for a treasury account.
A beneficiary is the person or account address that will benefit from a specific treasury pool.
beneficiary_withdrawal_address: The address of the account that will have exclusive withdrawal rights over the money stream. Only one beneficiary can ever exist for a stream. Only the beneficiary of a stream can update the stream to CHANGE the beneficiary.
A contributor is the person or account address that contributes SPL tokens into a specific treasury pool.
Defines a set of enforceable terms for a money stream. Each beneficiary can have different terms in their money streams, i.e. two employees with different salaries using the same Company Payroll Treasury Pool.
rate_interval_in_seconds: The amount of time over which a certain amount of money (see below rate_amount) must be streamed to the beneficiary. This is expressed in seconds and approximated to multiples of 400ms by the program. Where:
- 1 hour = 3,600 seconds = ~9,000 blocks
- 1 day = 86,400 seconds = ~216,000 blocks
- 1 week = 7 days = 604,800 seconds = ~1,512,000 blocks
- 1 month = ~30 days = 2,592,000 seconds = ~6,486,000 blocks
- 1 year = ~365 days = 31,536,000 seconds = ~78,840,000 blocks
- CUSTOM = X seconds = ~(X / 0.4) blocks
rate_amount: The amount of money streamed every rate_interval_in_seconds to the beneficiary.
rate: The rate at which the beneficiary is able to withdraw money from the stream based on its ongoing solvency. That is rate_amount every rate_interval_in_seconds.
- Example: 1000 USDT per month (updated every ~400ms)
rate_cliff_in_seconds (OPTIONAL): A period of time (calculated from start_utc) where the rate will not apply (as in, no distribution). That means that the rate will only become effective at:
start_utc + rate_cliff_in_seconds. This is useful for company stock vesting schedules, which almost always include a "test" period/cliff (like a 90 day test period) for new employees.
cliff_vest_amount (OPTIONAL): A fixed amount of money that will be distributed to the beneficiary ONCE when the cliff ends, irrespective of the rate.
cliff_vest_percent (OPTIONAL): Same as the cliff_distribution_amount, but expressed as a percent of the funds in the stream at the time of the cliff.
auto_pause_in_seconds (OPTIONAL & INTERNAL): Can be set manually (optional) or automatically (always). This is calculated every time the treasury funds increase or decrease, and is calculated as the number of seconds that will take for the funds to run out.
The on-chain terms for a specific tuple in the form of <Treasury, Beneficiary, Terms>, which determines the rate of money that is streaming from the Treasury to the Beneficiary.
stream_id: The unique identifier for a money stream. This corresponds to the account address used to store the stream data for a specific beneficiary.
stream_name: A friendly name given by the treasurer to the stream.
start_utc: The time at which the stream should begin. It cannot be set in the past. If not specified at creation, it will start at the following block (aka NOW).
escrow_token_address: The address of the SPL token that the beneficiary PREFERS to use to withdraw funds from the escrow account. This is the way a beneficiary CHOOSES their form of payment (USDC vs. ETH vs. SOL vs. USDT). Only the beneficiary can change this field on the stream if they wish to SWAP their preferred withdrawal currency. This can be done unilaterally and without consensus. Changing this field on a stream will atomically:
- 1.Distribute escrow_vested_amount to the beneficiary in the previous token.
- 2.Swap the escrow_unvested_amount from the previous token to the new token.
This means the Money Streaming Program MUST swap the tokens provided by contributors at contribution time if they are different from the escrow_token_address.
escrow_vested_amount: The amount of money available to withdraw from the stream by the beneficiary. Updated every block, which is about ~400ms in Solana.
is_running = resume_block_height > escrow_vested_amount_snap_block_height
rate = is_running * rate_amount / rate_interval_in_seconds
marker_block_height = max(escrow_vested_amount_snap_block_height, resumed_block_height)
rate * (current_block_height - marker_block_height)
escrow_unvested_amount: The amount of money held in escrow by the stream. This money will be released at the rate and calculated as:
escrow_unvested_amount = total_deposits - total_withdrawals - escrow_vested_amount
resumed_block_height: Automatically set when the stream is resumed (State = Running).
resumed_block_time: The timestamp corresponding to the stream_resumed_block_height.
escrow_vested_amount_snap_block_height: The block height of the last calculated escrow_vested_amount_snap. This is useful for conditional money streams with multiple pause/resume state transitions.
escrow_vested_amount_snap_block_time: The timestamp corresponding to the escrow_vested_amount_snap_block_height
escrow_vested_amount_snap: A snapshot of the amount of money vested until the specific block defined by escrow_vested_amount_snap_block_height. This is useful for conditional money streams with multiple pause/resume state transitions.