STP
Contract Reference
STP Ref

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

NameTypeDescription
numTokensuint256the amount of ERC20 tokens or native tokens to transfer

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

NameTypeDescription
accountaddressthe account to mint or renew time for
numTokensuint256the amount of ERC20 tokens or native tokens to transfer

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

NameTypeDescription
paramsMintParamsthe minting 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

NameTypeDescription
accountaddressthe account to refund
numTokensuint256the amount of tokens to refund

grantTime

Grant time to a given account

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

Parameters

NameTypeDescription
accountaddressthe account to grant time to
numSecondsuint48the number of seconds to grant
tierIduint16the tier id to grant time to (0 to match current tier, or default for new)

revokeTime

Revoke time from a given account

function revokeTime(address account) external;

Parameters

NameTypeDescription
accountaddressthe account to revoke time from

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

NameTypeDescription
accountaddressthe account to deactivate

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

NameTypeDescription
numTokensuint256the amount of tokens to transfer

updateMetadata

Update the contract metadata

function updateMetadata(string memory uri) external;

Parameters

NameTypeDescription
uristringthe collection metadata URI

setTransferRecipient

Set a transfer recipient for automated/sponsored transfers

function setTransferRecipient(address recipient) external;

Parameters

NameTypeDescription
recipientaddressthe recipient address

setGlobalSupplyCap

Set the global supply cap for all tiers

function setGlobalSupplyCap(uint64 supplyCap) external;

Parameters

NameTypeDescription
supplyCapuint64the new supply cap

createTier

Create a new tier

function createTier(Tier memory params) external;

Parameters

NameTypeDescription
paramsTierthe tier 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

NameTypeDescription
tierIduint16the id of the tier to update
paramsTierthe new tier parameters

updateProtocolFeeRecipient

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

function updateProtocolFeeRecipient(address recipient) external;

Parameters

NameTypeDescription
recipientaddressthe new fee recipient address

updateClientFeeRecipient

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

function updateClientFeeRecipient(address recipient) external;

Parameters

NameTypeDescription
recipientaddressthe new fee recipient address

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

NameTypeDescription
codeuint256the unique integer code for the referral
basisPointsuint16the reward basis points (max = 50% = 5000 bps)
permanentboolwhether the referral code is locked (immutable after set)
accountaddressthe specific account to reward (0x0 for any account)

referralDetail

Fetch the reward basis points for a given referral code

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

Parameters

NameTypeDescription
codeuint256the unique integer code for the referral

Returns

NameTypeDescription
valueReferralLib.Codethe reward basis points and permanence

_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

NameTypeDescription
amountuint256the amount of tokens (native or ERC20) to allocate

createRewardCurve

Create a new reward curve

function createRewardCurve(CurveParams memory curve) external;

Parameters

NameTypeDescription
curveCurveParamsthe curve parameters. The id is set automatically (monotonic)

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

NameTypeDescription
accountaddressthe account of the reward holder

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

NameTypeDescription
accountaddressthe account to slash

curveDetail

Get details about a given reward curve

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

Parameters

NameTypeDescription
curveIduint8the curve id to fetch

Returns

NameTypeDescription
curveCurveParamsthe curve details

subscriptionOf

Get details about a particular subscription

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

Parameters

NameTypeDescription
accountaddressthe account to fetch the subscription for

Returns

NameTypeDescription
subscriptionSubscriberViewthe relevant information for a subscription

contractDetail

Get details about the contract state

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

Returns

NameTypeDescription
detailContractViewthe contract details

feeDetail

Get details about the fee structure

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

Returns

NameTypeDescription
feeFeeParamsthe fee details

tierDetail

Get details about a given tier

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

Parameters

NameTypeDescription
tierIduint16the tier id to fetch

Returns

NameTypeDescription
tierTierLib.Statethe tier details

stpVersion

Get the version of the protocol

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

Returns

NameTypeDescription
versionuint8the protocol version

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

NameTypeDescription
tierIduint16the tier id to fetch the balance for
accountaddressthe account to fetch the balance of

Returns

NameTypeDescription
numSecondsuint256the number of seconds remaining in the subscription

name

Fetch the name of the token

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

Returns

NameTypeDescription
<none>stringname the name of the token

symbol

Fetch the symbol of the token

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

Returns

NameTypeDescription
<none>stringsymbol the symbol of the token

contractURI

Fetch the contract metadata URI

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

Returns

NameTypeDescription
uristringthe URI for the contract

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

NameTypeDescription
tokenIduint256the tokenId to fetch the metadata URI for

Returns

NameTypeDescription
uristringthe URI for the token

balanceOf

Override the default balanceOf behavior to account for time remaining

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

Parameters

NameTypeDescription
accountaddressthe account to fetch the balance of

Returns

NameTypeDescription
numSecondsuint256the number of seconds remaining in the subscription

_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

NameTypeDescription
tokenAddressaddressthe address of the token to recover
recipientAddressaddressthe address to send the tokens to
tokenAmountuint256the amount of tokens to send

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();