Smart Contracts

Contract Addresses & Overview

EVM Contract Addresses

Our smart contracts are upgradable and various functions are gated behind the Superstate Admin Address calling them. This includes all minting, adding or removing users from the allowlist, and forcibly burning an investor’s tokens (if required by exogenous legal circumstances, for example).

Code Repositories

Audits

SVM Contract Addresses

Our Allowlist program is upgradeable. To simplify integrations, it has both a Rust SDK and a Typescript SDK.

Allowlist Audits

248KB
Superstate-Allowlist-May-2025-OffsideLabs.pdf
pdf
426KB
Superstat audit report by Certora.pdf
pdf

USTB and USCC Shared Functionality Overview

EVM Design

A standard Upgradable OpenZeppelin ERC-20 implementation with a few changes:

  1. USTB/USCC check that all holders are on the Superstate controlled Allowlist contract and are authorized for that token.

  2. Redeem - Investors can call the offchainRedeemfunction or transfer their USTB/USCC to the contract address to kick off a standard redemption

  3. Mint - Superstate can call the mint function to mint new shares of USTB/USCC when investors subscribe to the fund

SVM Design

Our tokens use the SPL Token 2022 Program with the following extensions:

The tokens are permissioned by a novel and first of its kind Allowlist Program that allows for seamless integration with DeFi protocols.

Transfers

USTB/USCC is freely transferrable between addresses that are on the Allowlist.

On the EVM, this is via transfer or transferFrom. Each function checks that the sender and receiver are both on the Allowlist and authorized for that specific token.

On the SVM, this is done the Transfer or TransferChecked Instructions. Once an account has been thawed by the Allowlist program, that account is able to freely transfer between other addresses that have been thawed.

Burn To Book Entry

It is possible to convert tokenized shares into shares held in Book Entry within Superstate's ledger.

On the EVM, this is done via the burn function, or a simple transfer to the zero address.

On the SVM, this is done via a simple transfer to the Burn address (listed above).

Bridging

On the EVM, the bridge function allows users to burn their tokens on the source chain, and receive the specified number of tokens on supported destination chains. This functionality makes it easy for users of all types to move their tokens cheaply and efficiently across chains.

An easier to use helper function bridgeToBookEntry allows users to burn their tokens and hold their shares in book entry with Superstate, instead of onchain as an ERC-20.

On the SVM, it is not currently possible to initiate a bridge - this functionality is coming soon. If this is desired, consider using the Burn to Book Entry feature and then minting to an EVM chain. However, the destination/receiver of funds can be on Solana (chainId 900) from a bridge request that was made on the Ethereum/Plume.

EVM Allowlist

Adds/Removes Ethereum addresses to/from the allowlist with certain permissions. Fund tickers are used with privateInstrumentPermissionByEntityId determine if an entity is allowed to interact with a speciifc fund's token or not Ethereum addresses are also grouped by their Entity Id. Entity Ids are how Superstate identifies investors. The USTB/USCC token contract calls isAddressAllowedForPrivateInstrument on the Allowlist contract to see if the sender and receiver of USTB are allowed to hold it. Only the Superstate Admin Address can make any changes to the allowlist, using the following functions setEntityAllowedForPrivateInstrument, setProtocolAddressPermission, setProtocolAddressPermissions, setEntityIdForAddress, setEntityIdForMultipleAddresses, setEntityPermissionsAndAddresses.

We call these functions when onboarding or offboarding an investor. We only add Ethereum addresses for investors that have made it through our KYC / Investment Agreement processes. However, Superstate Inc. audited DeFi protocols may be added to the allowlist at our discretion.

SVM Allowlist

On the SVM, Superstate adds/removes addresses via the admin_add_public_allowed_account or admin_add_private_allowed_account instructions.

The Allowlist Program is the Freeze Authority for Superstate Tokens, and provides a permissionless Thaw instruction for DeFi protocols can call to seamlessly integrate and onboard users within existing flows.

Both the Rust and Typescript SDKs provide helper methods for clients to read the Allowlist Program's internal state. This can be used to determine if an address is on the allowlist, for example.

USTB Specific Functionality

Subscribe function (Ethereum only)

Protocols can mint USTB by calling the subscribe function on the Ethereum USTB contract. This function atomically transfers the investor’s USDC to Superstate, and newly minted USTB into the investor’s wallet in one transaction. The price per share is read from the Superstate USTB Continuous Price oracle contract. There are no limits for subscriptions.

Users must call approve on the USDC contract before calling subscribe on the USTB contract.

DeFi Protocols will be interested in the calculateSuperstateTokenOut(uint256 inAmount, address stablecoin) returns (uint256 superstateTokenOutAmount, uint256 stablecoinInAmountAfterFee, uint256 feeOnStablecoinInAmount) function, also on the USTB contract. Given an inAmount of stablecoin it will give you the superstateTokenOutAmount you should expect to receive back accounting for fees. There is also a subscribe function variant that takes a to address argument. The to address can be any of your entity's Allowlisted Ethereum addresses and USTB is sent to it.

At time of writing, fees are set to 0 and only USDC is supported. For more information, please visit superstate.co/ustb.

RedemptionIdle Contract (Ethereum only)

Redeem function

The RedemptionIdle contract holds USDC liquidity while waiting to facilitate USTB redemptions. Investors can call the redeem function on the contract to burn USTB from the investor’s wallet and receive USDC in one transaction. USDC liquidity will be replenished in this contract regularly to facilitate protocol redemptions. The redeem function will revert if there is not enough USDC in the contract to match the superstateTokenInAmount.

Users must call approve on the USTB contract before calling redeem on the RedemptionIdle contract.

DeFi Protocols will be interested in the calculateUstbIn(uint256 usdcOutAmount) returns (uint256 ustbInAmount, uint256 usdPerUstbChainlinkRaw) function. This function takes a desired amount of USDC and returns how much USTB is needed for the superstateTokenInAmount argument of the redeem function to reach the usdcOutAmount. This function always rounds up, so the user will always hit or exceed the usdcOutAmount.

There is also a redeem function variant that takes a to address argument. The to address can be any Ethereum address and USDC is sent to it.

At time of writing, fees are set to 0 and only USDC is supported or more information please visit superstate.co/ustb.

Superstate USTB Continuous Price Oracle (Ethereum only)

A custom onchain oracle to facilitate continuous pricing onchain, which powers Atomic Subscriptions and Redemptions. The oracle receives pricing updates from Superstate every time a new Net Asset Value per Share (NAV/S) is calculated by our NAV Calculation Agent partner. When a continuous price is requested, the Oracle does linear extrapolation using the two newest NAV/S checkpoints to calculate it.

Any smart contract can request a continuous price onchain. The Oracle contract uses the Chainlink AggregatorV3Interface, so it works out of the box with any Chainlink data feed integrations. https://docs.chain.link/data-feeds/api-reference#functions-in-aggregatorv3interface

Chainlink USTB/USCC Oracle

Chainlink puts the USTB/USCC Net Asset Value per Share price onchain once per day. The Oracle contract uses the AggregatorV3Interface.https://docs.chain.link/data-feeds/api-reference#functions-in-aggregatorv3interface

This oracle has the daily USTB/USCC NAV/S price and can be used like any other Chainlink oracle.

PreviousInvestor PortalNextAPI

Last updated