Superstate
  • Introduction to Superstate
    • Onboarding
    • Onboarding: Required Documents
    • Investor Portal
    • Smart Contracts
    • API
    • Security
  • USTB
    • Income, Fees & Yield
    • Purchasing USTB
    • Redeeming USTB
    • Legal Structure
  • USCC
    • Income, Fees & Yield
    • Purchasing USCC
    • Redeeming USCC
    • Legal Structure
Powered by GitBook
On this page
  • Contract Addresses & Overview
  • USTB and USCC Shared Functionality Overview
  • USTB Specific Functionality
  • Subscribe function
  • RedemptionIdle Contract
  • Superstate USTB Continuous Price Oracle
  • Bug Bounty Program
  1. Introduction to Superstate

Smart Contracts

PreviousInvestor PortalNextAPI

Contract Addresses & Overview

Contract Addresses

  • AllowlistV2 Proxy -

  • USTB Token Proxy -

  • USCC Token Proxy -

  • USTB RedemptionIdle Proxy -

  • Superstate USTB Continuous Price Oracle -

  • Chainlink USTB Oracle -

  • Chainlink USCC Oracle -

  • AllowlistV2 Proxy -

  • USTB Token Proxy -

  • USCC Token Proxy -

  • USTB RedemptionIdle Proxy -

  • Superstate USTB Continuous Price Oracle -

  • Chainlink USTB Oracle -

  • Chainlink USCC Oracle -

  • AllowlistV2 Proxy -

  • USTB Token Proxy -

  • USCC Token Proxy -

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


USTB and USCC Shared Functionality Overview

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

Transfers

USTB/USCC is freely transferrable between Ethereum addresses that are on the Allowlist via transfer or transferFrom. Each function checks that the sender and receiver are both on the Allowlist and authorized for that specific token.

Bridging

The bridgefunction 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.

Allowlist

Adds/Removes Ethereum addresses to/from the allowlist with certain permissions. Fund tickers are used with fundPermissionsByEntityIdto 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 isAddressAllowedForFund 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 setEntityAllowedForFund, 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.


USTB Specific Functionality

Subscribe function

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.

RedemptionIdle Contract

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.

Superstate USTB Continuous Price Oracle

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.

Chainlink USTB/USCC Oracle

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


Bug Bounty Program

Superstate encourages the community to audit our contracts and security; we also encourage the responsible disclosure of any issues. This program is intended to recognize the value of working with the community of independent security researchers.

Rewards

Superstate offers substantial rewards for discoveries that can prevent the loss of assets, the freezing of assets, or material harm to a user, commensurate with the severity and exploitability of the vulnerability. We will pay a reward of $1,000 to $100,000 for unique discoveries that are reported responsibly.

Disclosure

Submit all bug bounty disclosures to security@superstate.co. The disclosure must include clear and concise steps to reproduce the discovered vulnerability in either written or video format. We will follow up promptly with acknowledgement of the disclosure.


AllowlistV2 Proxy -

USTB Token Proxy -

USCC Token Proxy -

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

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

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.

Chainlink puts the USTB/USCC Net Asset Value per Share price onchain once per day. The Oracle contract uses the AggregatorV3Interface.

https://testnet-explorer.plumenetwork.xyz/address/0x4b056c23abf9a4c94ec10821b731ced73601a845
https://testnet-explorer.plumenetwork.xyz/address/0x39727692cf58137bd8c401efe87cc8a190d62ead
https://testnet-explorer.plumenetwork.xyz/address/0xebba0e36545903f64291c4ba6d2c3b51c57a812e
https://etherscan.io/address/0x02f1fa8b196d21c7b733eb2700b825611d8a38e5
https://etherscan.io/address/0x43415eB6ff9DB7E26A15b704e7A3eDCe97d31C4e
https://etherscan.io/address/0x14d60e7fdc0d71d8611742720e4c50e7a974020c
https://etherscan.io/address/0x4c21b7577c8fe8b0b0669165ee7c8f67fa1454cf
https://etherscan.io/address/0xe4fa682f94610ccd170680cc3b045d77d9e528a8
https://etherscan.io/address/0x289B5036cd942e619E1Ee48670F98d214E745AAC
https://etherscan.io/address/0xAfFd8F5578E8590665de561bdE9E7BAdb99300d9
https://sepolia.etherscan.io/address/0x4b056c23abf9a4c94ec10821b731ced73601a845
https://sepolia.etherscan.io/address/0x39727692cF58137Bd8c401eFE87Cc8A190D62ead
https://sepolia.etherscan.io/address/0xebba0e36545903f64291c4ba6d2c3b51c57a812e
https://sepolia.etherscan.io/address/0xd33d340cdbef8e879c827199bd7d9705b21e18c9
https://sepolia.etherscan.io/address/0xba595155585b3572f17ee1050d8c6fb9653fcb93
https://sepolia.etherscan.io/address/0x732d3C7515356eAB22E3F3DcA183c5c65102d518
https://sepolia.etherscan.io/address/0xE38b0917888d0d5d8d03B7371d5214A1aF8e1892
https://phoenix-explorer.plumenetwork.xyz/address/0x06ed3c1cfd09e3665f72928517c86f6a87e8c35d
https://phoenix-explorer.plumenetwork.xyz/address/0xe4fa682f94610ccd170680cc3b045d77d9e528a8
https://phoenix-explorer.plumenetwork.xyz/address/0x4c21b7577c8fe8b0b0669165ee7c8f67fa1454cf
Github - USTB
Github - on-chain redemptions
https://chainsecurity.com/security-audit/compound-suptb/
https://0xmacro.com/library/audits/superstate-1
https://0xmacro.com/library/audits/superstate-2
https://0xmacro.com/library/audits/superstate-3
https://0xmacro.com/library/audits/superstate-4
https://0xmacro.com/library/audits/superstate-5
https://0xmacro.com/library/audits/superstate-6
superstate.co/ustb
superstate.co/ustb
https://docs.chain.link/data-feeds/api-reference#functions-in-aggregatorv3interface
https://docs.chain.link/data-feeds/api-reference#functions-in-aggregatorv3interface