Standard Pool

Standard Pools offer flexibility and control with a wide range of levers for the creator to adjust, making them suitable for a wide range of tokenomics. The market value of tokens in a Standard Pool is derived from the ratio of paired tokens in the market to the total token supply.

Flow of Funds:

Market Pricing:

Standard Pool Settings

Buy Fee - Amount added to the market value cost of buying tokens. Creator may set both a percentage of market value buy fee and a flat rate per token.
Sell Fee - Amount subtracted from the market value of tokens being sold. Creator specified as a percentage.
Buy Spread - Amount as a percentage that tokens cost over the current market value.
Sell Spread - Amount as a percentage that tokens are worth under the current market value.
Target Supply - Scales buy cost when target supply is exceeded by the ratio of new supply to expected supply - charged as a "demand fee".
Creator Share of Demand Fee - Percentage of the demand fee that is allocated to the creator, the remainder goes to market value of tokens.
Creator Share of Spends - Percentage of the value of tokens spent that are allocated to the creator, the remainder goes to market value of tokens.
Emissions - Tokens the creator may mint at zero cost, up to a self-imposed limit that may only be lowered. Emissions are accrued over time and creator may reset their accrual / only claim a portion to delay the introduction of those zero cost tokens into the market. Since emissions are minted at zero cost they devalue the rest of the supply.

Guardrails:

To maintain fairness and predictability, these settings are constrained by immutable limits established during deployment:

Fee Limits: Caps on buy and sell fees.
Spread Limits: Minimum and maximum buy/sell spreads.
Spend Share Limits: Maximum percentage of spent tokens that can be allocated to the creator.

Transactions

Buy:

A buyer will pay the market value of the tokens, adjusted by the buy spread, plus the creator buy fee plus a demand fee if the new supply exceeds the target supply (if applicable).

Buy spread greater than zero will increase the market value of tokens.

Sell:

A seller will receive the market value of the tokens, adjusted by the sell spread, less the creator sell fee.

Sell spread greater than zero will increase the market value of tokens.

Spend:

A spender will receive no market value for their tokens, market value will instead be transferred to the creator share at a rate specified by the creator.

Creator share of spend less than 100% will increase the market value of tokens.

Claim Emissions:

Creator emissions are accrued at a rate specified during the deployment of the token and may be claimed at any time. Emissions are capped at an amount set at deployment, the cap may be lowered post-deployment but not increased.

Claimed emissions by the creator will mint tokens at zero cost and decrease the market value of tokens.

Creators may opt to forfeit a portion of a claim which will require the forfeitted emissions to be re-accrued before they can be claimed.

Data Types

StandardPoolInitializationParameters

This struct defines parameters used for standard pool initialization.

initialSupplyRecipient: Address to receive the initial supply amount.
initialSupplyAmount: Initial amount of supply to mint to the initial supply recipient.
minBuySpreadBPS: Immutable minimum spread rate in BPS for buys.
maxBuySpreadBPS: Immutable maximum spread rate in BPS for buys.
maxBuyFeeBPS: Immutable maximum buy fee rate in BPS that may be set by the creator.
maxBuyDemandFeeBPS: Immutable maximum buy demand fee rate in BPS that may be set by the creator.
maxSellFeeBPS: Immutable maximum sell fee rate in BPS that may be set by the creator.
maxSpendCreatorShareBPS: Immutable maximum creator share rate in BPS that may be set by the creator.
creatorEmissionRateNumerator: Immutable numerator for the rate in tokens per second that a creator earns emissions.
creatorEmissionRateDenominator: Immutable denominator for the rate in tokens per second that a creator earns emissions.
creatorEmissionsHardCap: Initial value for the hard cap of total emissions that a creator may claim over time.
initialBuyParameters: Initial settings for buy parameters.
initialSellParameters: Initial settings for sell parameters.
initialSpendParameters: Initial settings for spend parameters.
initialPausedState: Initial paused state for pausable functions.

struct StandardPoolInitializationParameters {
    address initialSupplyRecipient;
    uint256 initialSupplyAmount;
    uint256 minBuySpreadBPS;
    uint256 maxBuySpreadBPS;
    uint256 maxBuyFeeBPS;
    uint256 maxBuyDemandFeeBPS;
    uint256 minSellSpreadBPS;
    uint256 maxSellSpreadBPS;
    uint256 maxSellFeeBPS;
    uint256 maxSpendCreatorShareBPS;
    uint256 creatorEmissionRateNumerator;
    uint256 creatorEmissionRateDenominator;
    uint256 creatorEmissionsHardCap;
    StandardPoolBuyParameters initialBuyParameters;
    StandardPoolSellParameters initialSellParameters;
    StandardPoolSpendParameters initialSpendParameters;
    uint256 initialPausedState;
}

StandardPoolBuyParameters

This struct defines parameters used for buys.

buySpreadBPS: Spread rate in BPS for the cost of tokens above the current market value.
buyFeeBPS: Fee rate in BPS for the fee applied to buys.
buyCostPairedTokenNumerator: The numerator for the ratio of paired token to pool token that will be added as a fee on top of buys.
buyCostPoolTokenDenominator: The denominator for the ratio of paired token to pool token that will be added as a fee on top of buys.
useTargetSupply: True if the pool uses a target supply for determining the application of demand fees.
reserved: Unused. Spacing for storage optimization.
buyDemandFeeBPS: Rate in BPS of the amount of demand fee that is allocated to the creator.
targetSupplyBaseline: Baseline supply amount for determining if a buy will exceed the target supply.
targetSupplyBaselineScaleFactor: Scale factor for the baseline supply. Stored as a separate value to optimize storage.
- Actual Supply Baseline = targetSupplyBaseline * 10^targetSupplyBaselineScaleFactor
targetSupplyGrowthRatePerSecond: Rate in tokens per second that the target supply grows when calculating expected supply.
targetSupplyBaselineTimestamp: Unix timestamp for the time when target supply growth rate per second starts accumulating.
- When the current block timestamp is less than targetSupplyBaselineTimestamp:
  - Expected Supply = Actual Supply Baseline.
- When the current block timestamp is greater than targetSupplyBaselineTimestamp:
  - Expected Supply = Actual Supply Baseline + targetSupplyGrowthRatePerSecond * (block.timestamp - targetSupplyBaselineTimestamp)

struct StandardPoolBuyParameters {
    uint16 buySpreadBPS;
    uint16 buyFeeBPS;
    uint96 buyCostPairedTokenNumerator;
    uint96 buyCostPoolTokenDenominator;
    bool useTargetSupply;
    uint24 reserved;
    uint16 buyDemandFeeBPS;
    uint48 targetSupplyBaseline;
    uint8 targetSupplyBaselineScaleFactor;
    uint96 targetSupplyGrowthRatePerSecond;
    uint48 targetSupplyBaselineTimestamp;
}

StandardPoolSellParameters

This struct defines parameters used for sells.

sellSpreadBPS: Spread rate in BPS to adjust value of tokens being sold below market value.
sellFeeBPS: Sell fee rate in BPS that will be subtracted from a sell order.

struct StandardPoolSellParameters {
    uint16 sellSpreadBPS;
    uint16 sellFeeBPS;
}

StandardPoolSpendParameters

This struct defines parameters used for spends.

creatorShareBPS: Rate in BPS of the value of tokens that will be allocated to the creator when tokens are spent.
- Any value not allocated to the creator remains in the market value of tokens and increases the market value of all remaining tokens.

struct StandardPoolSpendParameters {
    uint16 creatorShareBPS;
}

Standard Pool Functions

The following functions are specific to Standard Pools. Platforms integrating TokenMaster with Standard Pools should use these functions to update token settings, claim creator emissions, retrieve the current settings, and retrieve the guardrail settings for display purposes.

    // Administrative functions.
    function setBuyParameters(StandardPoolBuyParameters calldata _buyParameters) external;
    function setSellParameters(StandardPoolSellParameters calldata _sellParameters) external;
    function setSpendParameters(StandardPoolSpendParameters calldata _spendParameters) external;
    function setEmissionsHardCap(uint256 newHardCapAmount) external;
    function claimEmissions(address claimTo, uint256 forfeitAmount) external;

    // Current settings, guardrails and target supply.
    function getBuyParameters() external view returns(StandardPoolBuyParameters memory);
    function getSellParameters() external view returns(StandardPoolSellParameters memory);
    function getSpendParameters() external view returns(StandardPoolSpendParameters memory);
    function targetSupply() external view returns(bool useTargetSupply, uint256 target);
    function getParameterGuardrails() external view returns(
        uint16 minBuySpreadBPS,
        uint16 maxBuySpreadBPS,
        uint16 maxBuyFeeBPS,
        uint16 maxBuyDemandFeeBPS,
        uint16 minSellSpreadBPS,
        uint16 maxSellSpreadBPS,
        uint16 maxSellFeeBPS,
        uint16 maxSpendCreatorShareBPS
    );
    function getCreatorEmissions() external view returns(
        uint256 claimed,
        uint256 claimable,
        uint256 hardCap,
        uint48 lastClaim,
        uint128 creatorEmissionRateNumerator,
        uint128 creatorEmissionRateDenominator
    );

Standard Pool Events

Platforms integrating TokenMaster should index the following events on all tokens that are relevant to the platform to know when a token's buy, sell or spend parameters need to be checked for updates, when a creator updates their emissions hard cap, or when a creator claims emissions.

    /// @dev Emitted when the token's buy settings have been updated.
    event BuyParametersUpdated();

    /// @dev Emitted when the token's sell settings have been updated.
    event SellParametersUpdated();

    /// @dev Emitted when the token's spend settings have been updated.
    event SpendParametersUpdated();

    /// @dev Emitted when the creator updates their hard cap for creator emissions.
    event CreatorEmissionsHardCapUpdated(uint256 newHardCapAmount);

    /// @dev Emitted when a creator claims emissions.
    event CreatorEmissionsClaimed(address to, uint256 claimedAmount, uint256 forfeitedAmount);

Flow of Funds:​

Market Pricing:​

Standard Pool Settings​

Guardrails:​

Transactions​

Data Types​

StandardPoolInitializationParameters​

StandardPoolBuyParameters​

StandardPoolSellParameters​

StandardPoolSpendParameters​

Standard Pool Functions​

Standard Pool Events​