Circle's FiatToken contract is an ERC-20 compatible token. It allows minting/burning of tokens by multiple entities, pausing all activity, freezing of individual addresses, and a way to upgrade the contract so that bugs can be fixed or features added.
The FiatToken
has a number of roles (addresses) which control different
functionality:
masterMinter
- adds and removes minters and increases their minting allowanceminters
- create and destroy tokenspauser
- pause the contract, which prevents all transfers, minting, and burningblacklister
- prevent all transfers to or from a particular address, and prevents that address from minting or burningowner
- re-assign any of the roles except foradmin
admin
- manage the proxy-level functionalities such as switching the implementation contractrescuer
- transfer any ERC-20 tokens that are locked up in the contract
Circle will control the address of all roles.
The FiatToken
implements the standard methods of the ERC-20 interface with
some changes:
- A blacklisted address will be unable to call
transfer
ortransferFrom
, and will be unable to receive tokens.approve
was not allowed for blacklisted addresses in FiatToken versions <2.2 but available in versions 2.2+. See "Blacklisting" section for more details.
transfer
,transferFrom
, andapprove
will fail if the contract has been paused.
The FiatToken contract allows multiple entities to create and destroy tokens. These entities will have to be members of Circle, and will be vetted by Circle before they are allowed to create new tokens.
Each minter
has a minterAllowance
, which Circle configures. The
minterAllowance
is how many tokens that minter may issue, and as a minter
issues tokens, its minterAllowance
declines. Circle will periodically reset
the minterAllowance
as long as a minter
remains in good standing with Circle
and maintains adequate reserves for the tokens it has issued. The
minterAllowance
is to limit the damage if any particular minter
is
compromised.
Circle adds minters via the configureMinter
method. When a minter is
configured a minterAllowance
is specified, which is the number of tokens that
address is allowed to mint. As a minter
mints tokens, the minterAllowance
will decline.
- Only the
masterMinter
role may call configureMinter.
The minters
will need their allowance reset periodically to allow them to
continue minting. When a minter
's allowance is low, Circle can make another
call to configureMinter
to reset the minterAllowance
to a higher value.
Circle removes minters via the removeMinter
method. This will remove the
minter
from the list of minters
and set its minterAllowance
to 0. Once a
minter
is removed it will no longer be able to mint or burn tokens.
- Only the
masterMinter
role may callremoveMinter
.
A minter
mints tokens via the mint
method. The minter
specifies the
amount
of tokens to create, and a _to
address which will own the newly
created tokens. A minter
may only mint an amount less than or equal to its
minterAllowance
. The minterAllowance
will decrease by the amount of tokens
minted, and the balance of the _to
address and totalSupply
will each
increase by amount
.
-
Only a
minter
may callmint
. -
Minting fails when the contract is
paused
. -
Minting fails when the
minter
or_to
address is blacklisted. -
Minting emits a
Mint(minter, _to, amount)
event and aTransfer(0x00, _to, amount)
event.
A minter
burns tokens via the burn
method. The minter
specifies the
amount
of tokens to burn, and the minter
must have a balance
greater than
or equal to the amount
. Burning tokens is restricted to minter
addresses to
avoid accidental burning of tokens by end users. A minter
with a
minterAllowance
of 0 is allowed to burn tokens. A minter
can only burn
tokens which it owns. When a minter burns tokens, its balance and the
totalSupply are reduced by amount
.
Burning tokens will not increase the minterAllowance of the address doing the burning.
-
Only a minter may call burn.
-
Burning fails when the contract is paused.
-
Burning fails when the minter is blacklisted.
-
Burning emits a
Burn(minter, amount)
event, and aTransfer(minter, 0x00, amount)
event.
Addresses can be blacklisted. A blacklisted address will be unable to transfer tokens, mint, or burn tokens.
In FiatToken versions <2.2, A blacklisted address is unable to call approve
,
increaseAllowance
, decreaseAllowance
, or authorize future pull payments
using permit
. Nor can it be authorized to pull payments from other addresses.
This has been changed in v2.2 where a blacklisted address can perform the above
functions. But they are still blocked from transferring the assets in any way.
and therefore any operations on modifying the allowance of blacklisted addresses
are considered meaningless.
Circle blacklists an address via the blacklist
method. The specified account
will be added to the blacklist.
- Only the
blacklister
role may callblacklist
. - Blacklisting emits a
Blacklist(account)
event
Circle removes an address from the blacklist via the unblacklist
method. The
specified account
will be removed from the blacklist.
- Only the
blacklister
role may callunblacklist
. - Unblacklisting emits an
UnBlacklist(account)
event.
The entire contract can be paused in case a serious bug is found or there is a serious key compromise. All transfers, minting, burning, and adding minters will be prevented while the contract is paused. Other functionality, such as modifying the blacklist, removing minters, changing roles, and upgrading will remain operational as those methods may be required to fix or mitigate the issue that caused Circle to pause the contract.
Circle will pause the contract via the pause
method. This method will set the
paused flag to true.
-
Only the
pauser
role may call pause. -
Pausing emits a
Pause()
event
Circle will unpause the contract via the unpause
method. This method will set
the paused
flag to false. All functionality will be restored when the contract
is unpaused.
-
Only the
pauser
role may call unpause. -
Unpausing emits an
Unpause()
event
The contract is compatible with
ERC-2612. Users may update their
ERC-20 allowances by signing a permit
message and passing the signed message
to a relayer who will execute the on-chain transaction, instead of submitting a
transaction themselves.
The contract is compatible with ERC-3009. Users may transfer assets to another user by signing an EIP-3009 authorization and passing the authorization to a relayer who will execute the authorization on chain, instead of submitting a transaction themselves.
The contract supports signature validation via:
- ECDSA signatures for Externally Owned Accounts (EOAs)
- ERC-1271 for ERC-1271 compatible Smart Contract Wallets
The FiatTokenProxy contract uses the zeppelinos Unstructured-Storage Proxy
pattern
[https://github.com/zeppelinos/zos-lib/blob/8a16ef3ad17ec7430e3a9d2b5e3f39b8204f8c8d/contracts/upgradeability/AdminUpgradeabilityProxy.sol].
FiatTokenV2_2.sol is the implementation,
the actual token will be a Proxy contract
(FiatTokenProxy.sol) which will forward
all calls to FiatToken
via delegatecall. This pattern allows Circle to upgrade
the logic of any deployed tokens seamlessly.
- Circle will upgrade the token via a call to
upgradeTo
orupgradeToAndCall
if initialization is required for the new version. - Only the
admin
role may callupgradeTo
orupgradeToAndCall
.
The roles outlined above may be reassigned. The owner
role has the ability to
reassign all roles (including itself) except for the admin
role.
changeAdmin
updates theadmin
role to a new address.changeAdmin
may only be called by theadmin
role.
updateMasterMinter
updates themasterMinter
role to a new address.updateMasterMinter
may only be called by theowner
role.
updatePauser
updates thepauser
role to a new address.updatePauser
may only be called by theowner
role.
updateBlacklister
updates theblacklister
role to a new address.updateBlacklister
may only be called by theowner
role.
transferOwnership
updates theowner
role to a new address.transferOwnership
may only be called by theowner
role.
updateRescuer
updates therescuer
role to a new address.updateRescuer
may only be called by theowner
role.