Smart Contracts
Overview & Contract Addresses
Code Repository
https://github.com/superstateinc/ustb/tree/main
Audits
Contract Addresses
Allowlist Proxy - https://etherscan.io/address/0x42d75c8fdbbf046df0fe1ff388da16ff99de8149
USTB Token Proxy - https://etherscan.io/address/0x43415eB6ff9DB7E26A15b704e7A3eDCe97d31C4e
USCC Token Proxy - https://etherscan.io/address/0x14d60e7fdc0d71d8611742720e4c50e7a974020c
Chainlink USTB Oracle - https://etherscan.io/address/0x289B5036cd942e619E1Ee48670F98d214E745AAC
Chainlink USCC Oracle - https://etherscan.io/address/0xAfFd8F5578E8590665de561bdE9E7BAdb99300d9
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).
USTB and USCC
A standard Upgradable OpenZeppelin ERC-20 implementation with a few changes:
USTB/USCC check that all holders are on the Superstate controlled Allowlist contract and are authorized for that token.
Encumber functionality (see below)
Burn - Investors can call the
burn
function or transfer their USTB/USCC to the contract address to kick off a redemptionMint - 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.
Encumber
What is encumber?
A new EIP from Compound and Superstate. Encumber enables permissioned ERC-20s, like USTB, to be used in decentralized finance protocols.
Why is encumber needed?
Permissioned ERC-20s have allowlists, so not everyone can hold them. Given the structure of our Funds, Superstate must limit who may purchase/sell/hold its security tokens. Additionally, providing custody other than self custody may have additional requirements.
How does it work?
encumber
is like a stronger version of ERC-20 approve
. When you encumber
an amount of your ERC-20 to an EOA or smart contract, they stay in your wallet. However, you cannot revoke an encumbrance. Whomever you encumbered to must call the release
function to remove the encumbrance. You cannot transfer
or approve
encumbered tokens.
If someone encumbered to you, you can call transferFrom
at any time from
the encumbered to
anyone on the token allowlist. This spends the encumbrance. This functionality enables tokens like USTB and USCC to be used in DeFi.
For example, User A encumbers 10 USTB to Compound, and borrows against it. The position becomes unhealthy and Compound must liquidate User A’s 10 USTB. User B wants to pay the loan to buy the collateral. Compound calls transferFrom
on the USTB contract to transfer 10 USTB from User A to User B. Compound never has “custody” of USTB, but facilitates a transfer from one allowlist user to another.
How do I integrate? Here's some samples from Compound: https://github.com/compound-finance/encumber_samples
Allowlist
Adds/Removes Ethereum addresses to/from the allowlist with certain permissions. Right now, only the first two booleans in the Permission
struct are used. Permission.isAllowed
means the entity is onboarded to USTB. Permission.state1
means the entity is onboarded to USCC.
Ethereum addresses are also grouped by their Entity Id. Entity Ids are how Superstate identifies investors.
The USTB/USCC token contract calls getPermission
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 setEntityIdForAddress
, setEntityIdForMultipleAddresses
, setPermission
, setEntityPermissionAndAddresses
, and setNthPermission
. 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.
USTB Oracle
Chainlink handles putting the USTB Net Asset Value per Share price onchain. The Oracle contract uses the AggregatorV3Interface.https://docs.chain.link/data-feeds/api-reference#functions-in-aggregatorv3interface
This oracle has the most up to date USTB NAV/S price and can be used like any other Chainlink oracle.
Last updated