STPV2

Git Source (opens in a new tab)

Inherits: ERC721, AccessControlled, Multicallable, Initializable, ReentrancyGuard

Author: Fabric Inc.

An NFT contract which allows users to mint time and access token gated content while time remains.

State Variables

ROLE_MANAGER

The manager role can do most things, except calls that involve money (except tier management with rewardbps)

uint16 private constant ROLE_MANAGER = 1;

ROLE_AGENT

The agent can only grant and revoke time

uint16 private constant ROLE_AGENT = 2;

ROLE_ISSUER

The issuer role can issue shares

uint16 private constant ROLE_ISSUER = 4;

_contractURI

The metadata URI for the contract (tokenUri is derived from this)

string private _contractURI;

_name

The name of the token

string private _name;

_symbol

The symbol of the token

string private _symbol;

_rewardParams

The reward parameters (slash params)

RewardParams private _rewardParams;

_feeParams

The fee parameters (collector, bips)

FeeParams private _feeParams;

_currency

The denomination of the token (0 for native)

Currency private _currency;

_state

The subscription state (subscribers, tiers, etc)

SubscriptionLib.State private _state;

_referrals

Referral codes and rewards

ReferralLib.State private _referrals;

_rewards

The reward pool state (holders, balances, etc)

RewardPoolLib.State private _rewards;

_transferRecipient

The address of the account which can receive transfers via sponsored calls

address private _transferRecipient;

_factoryAddress

The address of the factory which created this contract

address private _factoryAddress;

Functions

constructor

Disable initializers on the logic contract

constructor();

receive

Fallback function to mint time for native token contracts

receive() external payable;

initialize

Initialize the contract with the core parameters

function initialize(
    InitParams memory params,
    Tier memory tier,
    RewardParams memory rewards,
    CurveParams memory curve,
    FeeParams memory fees
) public initializer;

mint

Mint or renew a subscription for sender

This is backwards compatible with the original mint function (default tier or subscribers current tier)

function mint(uint256 numTokens) external payable;

Parameters

mintFor

Mint or renew a subscription for a specific account. Intended for automated renewals.

This is backwards compatible with the original mint function (default tier or subscribers current tier)

function mintFor(address account, uint256 numTokens) public payable;

Parameters

mintAdvanced

Mint a subscription with advanced settings

This is the advanced minting function, which allows for setting a specific tier, referral code, and referrer

function mintAdvanced(MintParams calldata params) external payable;

Parameters

refund

Refund an account, clearing the subscription and revoking any grants, and paying out a set amount

This refunds using the creator balance. If there is not enough balance, it will fail.

function refund(address account, uint256 numTokens) external;

Parameters

grantTime

Grant time to a given account

function grantTime(address account, uint48 numSeconds, uint16 tierId) external nonReentrant;

Parameters

revokeTime

Revoke time from a given account

function revokeTime(address account) external;

Parameters

deactivateSubscription

Deactivate a sub, kicking them out of their tier to the 0 tier

The intent here is to help with supply capped tiers and subscription lapses

function deactivateSubscription(address account) external;

Parameters

transferFunds

function transferFunds(address to, uint256 amount) external;

topUp

Top up the creator balance. Useful for refunds, tips, etc.

function topUp(uint256 numTokens) external payable;

Parameters

updateMetadata

Update the contract metadata

function updateMetadata(string memory uri) external;

Parameters

setTransferRecipient

Set a transfer recipient for automated/sponsored transfers

function setTransferRecipient(address recipient) external;

Parameters

setGlobalSupplyCap

Set the global supply cap for all tiers

function setGlobalSupplyCap(uint64 supplyCap) external;

Parameters

createTier

Create a new tier

function createTier(Tier memory params) external;

Parameters

updateTier

Update an existing tier

This will overwrite all existing tier parameters, so care should be taken with single field intents

function updateTier(uint16 tierId, Tier memory params) external;

Parameters

updateProtocolFeeRecipient

Update the protocol fee collector address (must be called from the factory)

function updateProtocolFeeRecipient(address recipient) external;

Parameters

updateClientFeeRecipient

Update the client fee collector address (must be called from the factory)

function updateClientFeeRecipient(address recipient) external;

Parameters

setReferralCode

Create or update a referral code for giving rewards to referrers on mint

function setReferralCode(uint256 code, uint16 basisPoints, bool permanent, address account) external;

Parameters

referralDetail

Fetch the reward basis points for a given referral code

function referralDetail(uint256 code) external view returns (ReferralLib.Code memory value);

Parameters

Returns

_purchase

Purchase a subscription, minting a token if necessary, switching tiers if necessary

function _purchase(
    address account,
    uint16 tierId,
    uint256 numTokens,
    uint256 code,
    address referrer
) private nonReentrant;

_transferFee

Transfer a fee to a recipient, returning the amount transferred

function _transferFee(uint256 amount, uint16 bps, address recipient) private returns (uint256 fee);

_checkCreatorBalance

Ensure the contract has a creator balance to cover the transfer, without dipping into rewards

function _checkCreatorBalance(uint256 amount) private view;

_issueAndAllocateRewards

Issue rewards to an account and allocate funds to the pool (if configured)

function _issueAndAllocateRewards(address account, uint256 amount, uint16 tierId) private;

issueRewardShares

Mint tokens to an account without payment (used for migrations, tips, etc)

function issueRewardShares(address account, uint256 numShares) external;

yieldRewards

Allocate rewards to the pool in the denominated currency

function yieldRewards(uint256 amount) external payable nonReentrant;

Parameters

createRewardCurve

Create a new reward curve

function createRewardCurve(CurveParams memory curve) external;

Parameters

transferRewardsFor

Transfer rewards for a given account, if any are available

Permissionless to allow the creator or agents to transfer rewards on behalf of users

function transferRewardsFor(address account) public;

Parameters

slash

Slash the reward shares for a given account if the subscription has expired and the grace period ended.

This rebalances share value and is intended to incentivize users to renew subscriptions.

function slash(address account) external;

Parameters

curveDetail

Get details about a given reward curve

function curveDetail(uint8 curveId) external view returns (CurveParams memory curve);

Parameters

Returns

subscriptionOf

Get details about a particular subscription

function subscriptionOf(address account) external view returns (SubscriberView memory subscription);

Parameters

Returns

contractDetail

Get details about the contract state

function contractDetail() external view returns (ContractView memory detail);

Returns

feeDetail

Get details about the fee structure

function feeDetail() external view returns (FeeParams memory fee);

Returns

tierDetail

Get details about a given tier

function tierDetail(uint16 tierId) external view returns (TierLib.State memory tier);

Parameters

Returns

stpVersion

Get the version of the protocol

function stpVersion() external pure returns (uint8 version);

Returns

tierBalanceOf

Fetch the balance of a given account in a specific tier (0 if they are not in the tier)

function tierBalanceOf(uint16 tierId, address account) external view returns (uint256 numSeconds);

Parameters

Returns

name

Fetch the name of the token

function name() public view override returns (string memory);

Returns

symbol

Fetch the symbol of the token

function symbol() public view override returns (string memory);

Returns

contractURI

Fetch the contract metadata URI

function contractURI() public view returns (string memory uri);

Returns

tokenURI

Fetch the metadata URI for a given token

The metadata host must be able to resolve the token ID as a path part (contractURI/${tokenId})

function tokenURI(uint256 tokenId) public view override returns (string memory uri);

Parameters

Returns

balanceOf

Override the default balanceOf behavior to account for time remaining

function balanceOf(address account) public view override returns (uint256 numSeconds);

Parameters

Returns

_beforeTokenTransfer

Prevent burning, handle soulbound tiers, and transfer subscription/reward state

function _beforeTokenTransfer(address from, address to, uint256) internal override;

recoverCurrency

Recover a token from the contract (unless it is the contracts denominated token)

function recoverCurrency(address tokenAddress, address recipientAddress, uint256 tokenAmount) external;

Parameters

Events

Withdraw

Emitted when the owner withdraws available funds

event Withdraw(address indexed account, uint256 tokensTransferred);

TopUp

Emitted when the creator tops up the contract balance on refund

event TopUp(uint256 tokensIn);

FeeTransfer

Emitted when the fees are transferred to the collector

event FeeTransfer(address indexed to, uint256 tokensTransferred);

ProtocolFeeRecipientChange

Emitted when the protocol fee recipient is updated

event ProtocolFeeRecipientChange(address indexed account);

ClientFeeRecipientChange

Emitted when the client fee recipient is updated

event ClientFeeRecipientChange(address indexed account);

ReferralPayout

Emitted when a referral fee is paid out

event ReferralPayout(
    uint256 indexed tokenId, address indexed referrer, uint256 indexed referralId, uint256 rewardAmount
);

GlobalSupplyCapChange

Emitted when the supply cap is updated

event GlobalSupplyCapChange(uint256 supplyCap);

TransferRecipientChange

Emitted when the transfer recipient is updated

event TransferRecipientChange(address indexed recipient);

SlashTransferFallback

Emitted when slashing and the reward transfer fails. The balance is reallocated to the creator

event SlashTransferFallback(address indexed account, uint256 amount);

Errors

InvalidOwner

Error when the owner is invalid

error InvalidOwner();

InvalidTokenParams

Error when the token params are invalid

error InvalidTokenParams();

InvalidFeeParams

Error when the fee params are invalid

error InvalidFeeParams();

TransferToExistingSubscriber

Error when a transfer fails due to the recipient having a subscription

error TransferToExistingSubscriber();

InsufficientBalance

Error when the balance is insufficient for a transfer

error InsufficientBalance();

NotSlashable

Error when slashing fails due to constraints

error NotSlashable();