# Smart contracts *** ## EVM contracts {% tabs %} {% tab title="Ethereum Mainnet" %} * AllowlistV3 Proxy - * USTB Token Proxy - * USCC Token Proxy - * USTB RedemptionIdle Proxy - * Superstate USTB Continuous Price Oracle - * Chainlink USTB Oracle - * Chainlink USCC Oracle - [https://etherscan.io/address/0xAfFd8F5578E8590665de561bdE9E7BAdb99300d9]() {% endtab %} {% tab title="Sepolia Testnet" %} * AllowlistV3 Proxy - * USTB Token Proxy - * USCC Token Proxy - * USTB RedemptionIdle Proxy - * Superstate USTB Continuous Price Oracle - * Chainlink USTB Oracle - * Chainlink USCC Oracle - [https://sepolia.etherscan.io/address/0xE38b0917888d0d5d8d03B7371d5214A1aF8e1892]() {% endtab %} {% tab title="Plume Mainnet" %} * AllowlistV3 Proxy - * USTB Token Proxy - * USCC Token Proxy - {% endtab %} {% tab title="Plume Testnet" %} * AllowlistV3 Proxy - * USTB Token Proxy - * USCC Token Proxy - {% endtab %} {% endtabs %} 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 * [Github - USTB](https://github.com/superstateinc/ustb/tree/main) * [Github - on-chain redemptions](https://github.com/superstateinc/onchain-redemptions) #### Audits * * * * * * * * * * * * {% file src="/files/iBrehX5OPLl9D7AnlDUS" %} *** ## SVM contracts {% tabs %} {% tab title="Solana Mainnet" %} * Allowlist - * USTB Token 2022 - * USCC Token 2022 - * Burn Address - * Pyth USTB Oracle - * Pyth USCC Oracle - * Pyth FWDI Superstate Oracle (for DeFi protocols) - * Pyth FWDI Nasdaq Oracle - * Pyth GLXY Superstate Oracle (for DeFi protocols) - * Pyth GLXY Nasdaq Oracle - {% endtab %} {% tab title="Solana Devnet" %} * Allowlist - * USTB Token 2022 - * USCC Token 2022 - * Burn Address - * Pyth USTB Oracle - * Pyth USCC Oracle - {% endtab %} {% endtabs %} Our Allowlist program is upgradeable. To simplify integrations, it has both a [Rust SDK](https://crates.io/crates/superstate-allowlist-interface) and a [Typescript SDK](https://www.npmjs.com/package/@superstateinc/allowlist). *** ## Allowlist Audits {% file src="/files/Bd8PXKZtcG1JDz16chd1" %} {% file src="/files/WzC0z0G1Fe3mfXR25n80" %} * Macro Audit - *** ## **USTB and USCC Shared Functionality** #### 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 `offchainRedeem`function 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](https://spl.solana.com/token-2022) with the following extensions: * [Default Account State](https://solana.com/developers/courses/token-extensions/default-account-state) (set to Frozen) * [Permanent Delegate](https://solana.com/developers/courses/token-extensions/permanent-delegate) * [ScaledUi](https://solana.com/docs/tokens/extensions/scaled-ui-amount) * [Immutable Owner](https://solana.com/developers/courses/token-extensions/immutable-owner) * [Metadata and Metadata Pointer](https://solana.com/developers/courses/token-extensions/token-extensions-metadata) 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. * **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. * **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: * **EVM:** This is done by calling the `bridgeToBookEntry` function onchain. * **SVM**: Burn to book-entry is not supported for shares of funds held as SVM tokens. Instead investors can redeem shares held as SVM tokens, set their purchase destination to book-entry, and re-purchase the same fund.
#### Bridging * **EVM:** This is done by calling the `bridge` function. It 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. As mentioned in the burn to book-entry section, the 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. * **SVM:** Bridging is not supported for shares of funds held as SVM tokens. Instead investors can redeem shares held as SVM tokens, set their purchase destination to another chain, and re-purchase the same fund.
#### 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 specific 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](https://docs.rs/superstate-allowlist-interface/0.1.0/superstate_allowlist_interface/instruction/fn.admin_add_public_allowed_account.html) or [admin\_add\_private\_allowed\_account](https://docs.rs/superstate-allowlist-interface/0.1.0/superstate_allowlist_interface/instruction/fn.admin_add_private_allowed_account.html) instructions. The Allowlist Program is the Freeze Authority for Superstate Tokens, and [provides a permissionless Thaw instruction](https://docs.rs/superstate-allowlist-interface/0.1.0/superstate_allowlist_interface/instruction/fn.thaw.html) 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.com/ustb](http://superstate.com/ustb). #### RedemptionIdle Contract (Ethereum only) 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.com/ustb](http://superstate.com/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. #### 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. This oracle has the daily USTB/USCC NAV/S price and can be used like any other Chainlink oracle. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.superstate.com/investors/smart-contracts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.