A standard interface for Fungible Key Bound Tokens (FKBT/s), a subset of the more general Key Bound Tokens (KBT/s).
The following standardizes an API for tokens within smart contracts and provides basic functionality to the addBindings function. This function designates Key Wallets[^1], which are responsible for conducting a Safe Transfer[^2]. During this process, FKBT's are safely approved so they can be spent by the user or an on-chain third-party entity.
The premise of FKBT's is to provide fully optional security features built directly into the fungible asset, via the concept of allow found in the allowTransfer and allowApproval functions. These functions are called by one of the Key Wallets[^1] and allow the Holding Wallet[^3] to either call the already familiar transfer and approve function found in ERC-20. Responsibility for the FKBT is therefore split. The Holding Wallet contains the asset and Key Wallets have authority over how the assets can be spent or approved. Default Behaviors[^4] of a traditional fungible ERC-20 can be achieved by simply never using the addBindings function.
We considered FKBTs being used by every individual who wishes to add additional security to their fungible assets, as well as consignment to third-party wallets/brokers/banks/insurers. FKBTs are resilient to attacks/thefts, by providing additional protection to the asset itself on a self-custodial level.
In this fast-paced technologically advancing world, people learn and mature at different speeds. The goal of global adoption must take into consideration the target demographic is of all ages and backgrounds. Unfortunately for self-custodial assets, one of the greatest pros is also one of its greatest cons. The individual is solely responsible for their actions and adequately securing their assets. If a mistake is made leading to a loss of funds, no one is able to guarantee their return.
From January 2021 through March 2022, the United States Federal Trade Commission received more than 46,000[^5] crypto scam reports. This directly impacted crypto users and resulted in a net consumer loss exceeding $1 Billion[^6]. Theft and malicious scams are an issue in any financial sector and oftentimes lead to stricter regulation. However, government-imposed regulation goes against one of this space’s core values. Efforts have been made to increase security within the space through centralized and decentralized means. Up until now, no one has offered a solution that holds onto the advantages of both whilst eliminating their disadvantages.
We asked ourselves the same question as many have in the past, “How does one protect the wallet?”. After a while, realizing the question that should be asked is “How does one protect the asset?”. Creating the wallet is free, the asset is what has value and is worth protecting. This question led to the development of KBT's. A solution that is fully optional and can be tailored so far as the user is concerned. Individual assets remain protected even if the seed phrase or private key is publicly released, as long as the security feature was activated.
FKBTs saw the need to improve on the widely used fungible ERC-20 token standard. The security of fungible assets is a topic that concerns every entity in the crypto space, as their current and future use cases are continuously explored. FKBTs provide a scalable decentralized security solution that takes security one step beyond wallet security, focusing on the token's ability to remain secure. The security is on the blockchain itself, which allows every demographic that has access to the internet to secure their assets without the need for current hardware or centralized solutions. Made to be a promising alternative, FKBTs inherit all the characteristics of an ERC-20. This was done so FKBTs could be used on every dApp that is configured to use traditional fungible tokens.
During the development process, the potential advantages KBT's explored were the main motivation factors leading to their creation;
Completely Decentralized: The security features are fully decentralized meaning no third-party will have access to user funds when activated. This was done to truly stay in line with the premise of self-custodial assets, responsibility and values.
Limitless Scalability: Centralized solutions require the creation of an account and their availability may be restricted based on location. FKBT's do not face regional restrictions or account creation. Decentralized security solutions such as hardware options face scalability issues requiring transport logistics, secure shipping and vendor. FKBT's can be used anywhere around the world by anyone who so wishes, provided they have access to the internet.
Fully Optional Security: Security features are optional, customizable and removable. It’s completely up to the user to decide the level of security they would like when using FKBT's.
Default Functionality: If the user would like to use FKBT's as a traditional ERC-20, the security features do not have to be activated. As the token inherits all of the same characteristics, it results in the token acting with traditional fungible Default Behaviors[^4]. However, even when the security features are activated, the user will still have the ability to customize the functionality of the various features based on their desired outcome. The user can pass a set of custom and or Default Values[^7] manually or through a dApp.
Unmatched Security: By calling the addBindings function a Key Wallet[^1] is now required for the allowTransfer or allowApproval function. The allowTransfer function requires 4 parameters, _amount[^8], _time[^9], _address[^10], and _allFunds[^11], where as the allowApproval function has 2 parameters, _time[^12] and _numberOfTransfers[^13]. In addition to this, FKBT's have a safeFallback and resetBindings function. The combination of all these prevent and virtually cover every single point of failure that is present with a traditional ERC-20, when properly used.
Security Fail-Safes: With FKBTs, users can be confident that their tokens are safe and secure, even if the Holding Wallet[^3] or one of the Key Wallets[^1] has been compromised. If the owner suspects that the Holding Wallet has been compromised or lost access, they can call the safeFallback function from one of the Key Wallets. This moves the assets to the other Key Wallet preventing a single point of failure. If the owner suspects that one of the Key Wallets has been comprised or lost access, the owner can call the resetBindings function from _keyWallet1[^15] or _keyWallet2[^16]. This resets the FKBT's security feature and allows the Holding Wallet to call the addBindings function again. New Key Wallets can therefore be added and a single point of failure can be prevented.
Anonymous Security: Frequently, centralized solutions ask for personal information that is stored and subject to prying eyes. Purchasing decentralized hardware solutions are susceptible to the same issues e.g. a shipping address, payment information, or a camera recording during a physical cash pick-up. This may be considered by some as infringing on their privacy and asset anonymity. FKBT's ensure user confidentially as everything can be done remotely under a pseudonym on the blockchain.
Low-Cost Security: The cost of using FKBT's security features correlate to on-chain fees, the current GWEI at the given time. As a standalone solution, they are a viable cost-effective security measure feasible to the majority of the population.
Environmentally Friendly: Since the security features are coded into the FKBT, there is no need for centralized servers, shipping, or the production of physical object/s. Thus leading to a minimal carbon footprint by the use of FKBT's, working hand in hand with Ethereum’s change to a PoS[^14] network.
User Experience: The security feature can be activated by a simple call to the addBindings function. The user will only need two other wallets, which will act as _keyWallet1[^15] and _keyWallet2[^16], to gain access to all of the benefits FKBT's offer. The optional security features improve the overall user experience and Ethereum ecosystem by ensuring a safety net for those who decide to use it. Those that do not use the security features are not hindered in any way. This safety net can increase global adoption as people can remain confident in the security of their assets, even in the scenario of a compromised wallet.
IKBT20 (Token Contract)NOTES:
0.8.0 (or above)false from returns (bool success). Callers MUST NOT assume that false is never returned!interface IKBT20 {
event AccountSecured(address _account, uint256 _amount);
event AccountResetBinding(address _account);
event SafeFallbackActivated(address _account);
event AccountEnabledTransfer(
address _account,
uint256 _amount,
uint256 _time,
address _to,
bool _allFunds
);
event AccountEnabledApproval(
address _account,
uint256 _time,
uint256 _numberOfTransfers
);
event Ingress(address _account, uint256 _amount);
event Egress(address _account, uint256 _amount);
struct AccountHolderBindings {
address firstWallet;
address secondWallet;
}
struct FirstAccountBindings {
address accountHolderWallet;
address secondWallet;
}
struct SecondAccountBindings {
address accountHolderWallet;
address firstWallet;
}
struct TransferConditions {
uint256 amount;
uint256 time;
address to;
bool allFunds;
}
struct ApprovalConditions {
uint256 time;
uint256 numberOfTransfers;
}
function addBindings(
address _keyWallet1,
address _keyWallet2
) external returns (bool);
function getBindings(
address _account
) external view returns (AccountHolderBindings memory);
function resetBindings() external returns (bool);
function safeFallback() external returns (bool);
function allowTransfer(
uint256 _amount,
uint256 _time,
address _to,
bool _allFunds
) external returns (bool);
function getTransferableFunds(
address _account
) external view returns (TransferConditions memory);
function allowApproval(
uint256 _time,
uint256 _numberOfTransfers
) external returns (bool);
function getApprovalConditions(
address account
) external view returns (ApprovalConditions memory);
function getNumberOfTransfersAllowed(
address _account,
address _spender
) external view returns (uint256);
function isSecureWallet(address _account) external view returns (bool);
}
AccountSecured eventEmitted when the _account is securing his account by calling the addBindings function.
_amount is the current balance of the _account.
event AccountSecured(address _account, uint256 _amount)
AccountResetBinding eventEmitted when the holder is resetting his keyWallets by calling the resetBindings function.
event AccountResetBinding(address _account)
SafeFallbackActivated eventEmitted when the holder is choosing to move all the funds to one of the keyWallets by calling the safeFallback function.
event SafeFallbackActivated(address _account)
AccountEnabledTransfer eventEmitted when the _account has allowed for transfer an _amount of tokens for the _time amount of block seconds for _to address (or if
the _account has allowed for transfer all funds though _allFunds set to true) by calling the allowTransfer function.
event AccountEnabledTransfer(address _account, uint256 _amount, uint256 _time, address _to, bool _allFunds)
AccountEnabledApproval eventEmitted when _account has allowed approval, for the _time amount of block seconds and set a _numberOfTransfers allowed, by calling the allowApproval function.
event AccountEnabledApproval(address _account, uint256 _time, uint256 _numberOfTransfers)
Ingress eventEmitted when _account becomes a holder. _amount is the current balance of the _account.
event Ingress(address _account, uint256 _amount)
Egress eventEmitted when _account transfers all his tokens and is no longer a holder. _amount is the previous balance of the _account.
event Egress(address _account, uint256 _amount)
The functions detailed below MUST be implemented.
addBindings functionSecures the sender account with other two wallets called _keyWallet1 and _keyWallet2 and MUST fire the AccountSecured event.
The function SHOULD revert if:
0x0)function addBindings (address _keyWallet1, address _keyWallet2) external returns (bool)
getBindings functionThe function returns the keyWallets for the _account in a struct format.
struct AccountHolderBindings {
address firstWallet;
address secondWallet;
}
function getBindings(address _account) external view returns (AccountHolderBindings memory)
resetBindings functionNote: This function is helpful when one of the two keyWallets is compromised.
Called from a keyWallet, the function resets the keyWallets for the holder account. MUST fire the AccountResetBinding event.
The function SHOULD revert if the sender is not a keyWallet.
function resetBindings() external returns (bool)
safeFallback functionNote: This function is helpful when the holder account is compromised.
Called from a keyWallet, this function transfers all the tokens from the holder account to the other keyWallet and MUST fire the SafeFallbackActivated event.
The function SHOULD revert if the sender is not a keyWallet.
function safeFallback() external returns (bool);
allowTransfer functionCalled from a keyWallet, this function is called before a transfer function is called.
It allows to transfer a maximum amount, for a specific time frame, to a specific address.
If the amount is 0 then there will be no restriction on the amount.
If the time is 0 then there will be no restriction on the time.
If the to address is zero address then there will be no restriction on the to address.
Or if _allFunds is true, regardless of the other params, it allows all funds, whenever, to anyone to be transferred.
The function MUST fire AccountEnabledTransfer event.
The function SHOULD revert if the sender is not a keyWallet or if the _amount is greater than the holder account balance.
function allowTransfer(uint256 _amount, uint256 _time, address _to, bool _allFunds) external returns (bool);
getTransferableFunds functionThe function returns the transfer conditions for the _account in a struct format.
struct TransferConditions {
uint256 amount;
uint256 time;
address to;
bool allFunds;
}
function getTransferableFunds(address _account) external view returns (TransferConditions memory);
allowApproval functionCalled from a keyWallet, this function is called before one of the approve, increaseAllowance or decreaseAllowance function are called.
It allows the holder for a specific amount of _time to do an approve, increaseAllowance or decreaseAllowance and limit the number of transfers the spender is allowed to do through _numberOfTransfers (0 - unlimited number of transfers in the allowance limit).
The function MUST fire AccountEnabledApproval event.
The function SHOULD revert if the sender is not a keyWallet.
function allowApproval(uint256 _time, uint256 _numberOfTransfers) external returns (bool)
getApprovalConditions functionThe function returns the approval conditions in a struct format. Where time is the block.timestamp until the approve, increaseAllowance or decreaseAllowance functions can be called, and numberOfTransfers is the number of transfers the spender will be allowed.
struct ApprovalConditions {
uint256 time;
uint256 numberOfTransfers;
}
function getApprovalConditions(address _account) external view returns (ApprovalConditions memory);
transfer functionThe function transfers _amount of tokens to address _to.
The function MUST fire the Transfer event.
The function SHOULD revert if the sender’s account balance does not have enough tokens to spend, or if the sender is a secure account and it has not allowed the transfer of funds through allowTransfer function.
Note: Transfers of 0 values MUST be treated as normal transfers and fire the Transfer event.
function transfer(address _to, uint256 _amount) external returns (bool)
approve functionThe function allows _spender to transfer from the holder account multiple times, up to the _value amount.
The function also limits the _spender to the specific number of transfers set in the ApprovalConditions for that holder account. If the value is 0 then the _spender can transfer multiple times, up to the _value amount.
The function MUST fire an Approval event.
If this function is called again it overrides the current allowance with _value and also overrides the number of transfers allowed with _numberOfTransfers, set in allowApproval function.
The function SHOULD revert if:
allowApproval function_time, set in the allowApproval function, has elapsed.function approve(address _spender, uint256 _amount) external returns (bool)
increaseAllowance functionThe function increases the allowance granted to _spender to withdraw from your account.
The function Emits an Approval event indicating the updated allowance.
The function SHOULD revert if:
allowApproval function_spender is a zero address (0x0)_time, set in the allowApproval function, has elapsed.function increaseAllowance(address _spender, uint256 _addedValue) external returns (bool)
decreaseAllowance functionThe function decreases the allowance granted to _spender to withdraw from your account.
The function Emits an Approval event indicating the updated allowance.
The function SHOULD revert if:
allowApproval function_spender is a zero address (0x0)_time, set in the allowApproval function, has elapsed._subtractedValue is greater than the current allowancefunction decreaseAllowance(address _spender, uint256 _subtractedValue) external returns (bool)
transferFrom functionThe function transfers _amount of tokens from address _from to address _to.
The function MUST fire the Transfer event.
The transferFrom method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf.
The function SHOULD revert unless the _from account has deliberately authorized the sender.
Each time the spender calls the function the contract subtracts and checks if the number of allowed transfers has reached 0,
and when that happens the approval is revoked using an approve of 0 amount.
Note: Transfers of 0 values MUST be treated as normal transfers and fire the Transfer event.
function transferFrom(address _from, address _to, uint256 _amount) external returns (bool)
The intent from individual technical decisions made during the development of FKBTs focused on maintaining consistency and backward compatibility with ERC-20s, all the while offering self-custodial security features to the user. It was important that FKBT's inherited all of ERC-20s characteristics to comply with requirements found in dApps which use fungible tokens on their platform. In doing so, it allowed for flawless backward compatibility to take place and gave the user the choice to decide if they want their FKBTs to act with Default Behaviors[^4]. We wanted to ensure that wide-scale implementation and adoption of FKBTs could take place immediately, without the greater collective needing to adapt and make changes to the already flourishing decentralized ecosystem.
For developers and users alike, the allowTransfer and allowApproval functions both return bools on success and revert on failures. This decision was done purposefully, to keep consistency with the already familiar ERC-20. Additional technical decisions related to self-custodial security features are broken down and located within the Security Considerations section.
KBT's are designed to be backward-compatible with existing token standards and wallets. Existing tokens and wallets will continue to function as normal, and will not be affected by the implementation of FKBT's.
The assets directory has all the tests.
Average Gas used (GWEI):
addBindings - 154,991resetBindings - 30,534safeFallback - 51,013allowTransfer - 49,887allowApproval - 44,971The implementation is located in the assets directory. There's also a diagram with the contract interactions.
FKBT's were designed with security in mind every step of the way. Below are some design decisions that were rigorously discussed and thought through during the development process.
Key Wallets[^1]: When calling the addBindings function for an FKBT, the user must input 2 wallets that will then act as _keyWallet1[^15] and _keyWallet2[^16]. They are added simultaneously to reduce user fees, minimize the chance of human error and prevent a pitfall scenario. If the user had the ability to add multiple wallets it would not only result in additional fees and avoidable confusion but would enable a potentially disastrous safeFallback situation to occur. For this reason, all KBT's work under a 3-wallet system when security features are activated.
Typically if a wallet is compromised, the fungible assets within are at risk. With FKBT's there are two different functions that can be called from a Key Wallet[^1] depending on which wallet has been compromised.
Scenario: Holding Wallet[^3] has been compromised, call safeFallback.
safeFallback: This function was created in the event that the owner believes the Holding Wallet[^3] has been compromised. It can also be used if the owner losses access to the Holding Wallet. In this scenario, the user has the ability to call safeFallback from one of the Key Wallets[^1]. FKBT's are then redirected from the Holding Wallet to the other Key Wallet.
By redirecting the FKBT's it prevents a single point of failure. If an attacker were to call safeFallback and the FKBT's redirected to the Key Wallet[^1] that called the function, they would gain access to all the FKBT's.
Scenario: Key Wallet[^1] has been compromised, call resetBindings.
resetBindings: This function was created in the event that the owner believes _keyWallet1[^15] or _keyWallet2[^16] has been compromised. It can also be used if the owner losses access to one of the Key Wallets[^1]. In this instance, the user has the ability to call resetBindings, removing the bound Key Wallets and resetting the security features. The FKBT's will now function as a traditional ERC-20 until addBindings is called again and a new set of Key Wallets are added.
The reason why _keyWallet1[^15] or _keyWallet2[^16] are required to call the resetBindings function is because a Holding Wallet[^3] having the ability to call resetBindings could result in an immediate loss of FKBT's. The attacker would only need to gain access to the Holding Wallet and call resetBindings.
In the scenario that 2 of the 3 wallets have been compromised, there is nothing the owner of the FKBT's can do if the attack is malicious. However, by allowing 1 wallet to be compromised, holders of fungible tokens built using the FKBT standard are given a second chance, unlike other current standards.
The allowTransfer function is in place to guarantee a Safe Transfer[^2], but can also have Default Values[^7] set by a dApp to emulate Default Behaviors[^3] of a traditional ERC-20. It enables the user to highly specify the type of transfer they are about to conduct, whilst simultaneously allowing the user to unlock all the FKBT's to anyone for an unlimited amount of time. The desired security is completely up to the user.
This function requires 4 parameters to be filled and different combinations of these result in different levels of security;
Parameter 1 _amount[^8]: This is the number of FKBT's that will be spent on a transfer.
Parameter 2 _time[^9]: The number of blocks the FKBT's can be transferred starting from the current block timestamp.
Parameter 3 _address[^10]: The destination the FKBT's will be sent to.
Parameter 4 _allFunds[^11]: This is a boolean value. When false, the transfer function takes into consideration Parameters 1, 2 and 3. If the value is true, the transfer function will revert to a Default Behavior[^4], the same as a traditional ERC-20.
The allowTransfer function requires _keyWallet1[^15] or _keyWallet2[^16] and enables the Holding Wallet[^3] to conduct a transfer within the previously specified parameters. These parameters were added in order to provide additional security by limiting the Holding Wallet in case it was compromised without the user's knowledge.
The allowApproval function provides extra security when allowing on-chain third parties to use your FKBT's on your behalf. This is especially useful when a user is met with common malicious attacks e.g. draining dApp.
This function requires 2 parameters to be filled and different combinations of these result in different levels of security;
Parameter 1 _time[^12]: The number of blocks that the approval of a third-party service can take place, starting from the current block timestamp.
Parameter 2 _numberOfTransfers_[^13]: The number of transactions a third-party service can conduct on the user's behalf.
The allowApproval function requires _keyWallet1[^15] or _keyWallet2[^16] and enables the Holding Wallet[^3] to allow a third-party service by using the approve function. These parameters were added to provide extra security when granting permission to a third-party that uses assets on the user's behalf. Parameter 1, _time[^12], is a limitation to when the Holding Wallet can approve a third-party service. Parameter 2, _numberOfTransfers[^13], is a limitation to the number of transactions the approved third-party service can conduct on the user's behalf before revoking approval.
Copyright and related rights waived via CC0.
[^1]: The Key Wallet/s refers to _keyWallet1 or _keyWallet2 which can call the safeFallback, resetBindings, allowTransfer and allowApproval functions.
[^2]: A Safe Transfer is when 1 of the Key Wallets safely approved the use of the FKBT's.
[^3]: The Holding Wallet refers to the wallet containing the FKBT's.
[^4]: A Default Behavior/s refers to behavior/s present in the preexisting non-fungible ERC-20 standard.
[^5]: The number of crypto scam reports the United States Federal Trade Commission received, from January 2021 through March 2022.
[^6]: The amount stolen via crypto scams according to the United States Federal Trade Commission, from January 2021 through March 2022.
[^7]: A Default Value/s refer to a value/s that emulates the non-fungible ERC-20 Default Behavior/s.
[^8]: The _amount represents the amount of the FKBT's intended to be spent.
[^9]: The _time in allowTransfer represents the number of blocks a transfer can take place in.
[^10]: The _address represents the address that the FKBT's will be sent to.
[^11]: The _allFunds is a bool that can be set to true or false.
[^12]: The _time in allowApproval represents the number of blocks an approve can take place in.
[^13]: The _numberOfTransfers is the number of transfers a third-party entity can conduct via transfer on the user's behalf.
[^14]: A PoS protocol, Proof-of-Stake protocol, is a cryptocurrency consensus mechanism for processing transactions and creating new blocks in a blockchain.
[^15]: The _keyWallet1 is 1 of the 2 Key Wallets set when calling the addBindings function.
[^16]: The _keyWallet2 is 1 of the 2 Key Wallets set when calling the addBindings function.
