Smart Contracts

Overview & 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).


A standard Upgradable OpenZeppelin ERC-20 implementation with a few changes: 1. USTB checks that all holders are on the Superstate controlled Allowlist contract 2. Encumber functionality (see below) 3. Burn - Investors can call the burn function or transfer their USTB to the contract address to kick off a redemption 4. Mint - Superstate can call the mint function to mint new shares of USTB when investors subscribe to the fund


USTB 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.


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 the Fund, 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 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:


Adds/Removes Ethereum addresses to/from the allowlist with certain permissions. Right now, only the first boolean in the Permission struct isAllowed is used. This denotes that the address is allowed to hold and use USTB. Ethereum addresses are also grouped by their Entity Id. Entity Ids are how Superstate identifies investors. The USTB 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.

Last updated