266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
|
---
|
||
|
|
eip: 6353
|
||
|
|
title: Charity token
|
||
|
|
description: Extension of EIP-20 token that can be partially donated to a charity project
|
||
|
|
author: Aubay <blockchain-team@aubay.com>, BOCA Jeabby (@bjeabby1507), EL MERSHATI Laith (@lth-elm), KEMP Elia (@eliakemp)
|
||
|
|
discussions-to: https://ethereum-magicians.org/t/erc20-charity-token/12617
|
||
|
|
status: Draft
|
||
|
|
type: Standards Track
|
||
|
|
category: ERC
|
||
|
|
created: 2022-05-13
|
||
|
|
requires: 20
|
||
|
|
---
|
||
|
|
|
||
|
|
## Abstract
|
||
|
|
|
||
|
|
An extension to [EIP-20](./eip-20.md) that can automatically send an additional percentage of each transfer to a third party, and that provides an interface for retrieving this information. This can allow token owners to make donations to a charity with every transfer. This can also be used to allow automated savings programs.
|
||
|
|
|
||
|
|
## Motivation
|
||
|
|
|
||
|
|
There are charity organizations with addresses on-chain, and there are token holders who want to make automated donations. Having a standardized way of collecting and managing these donations helps users and user interface developers. Users can make an impact with their token and can contribute to achieving sustainable blockchain development. Projects can easily retrieve charity donations addresses and rate for a given [EIP-20](./eip-20.md) token, token holders can compare minimum rate donation offers allowed by token contract owners. This standard provides functionality that allows token holders to donate easily.
|
||
|
|
|
||
|
|
## Specification
|
||
|
|
|
||
|
|
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
|
||
|
|
|
||
|
|
Owner of the contract **MAY**, after review, register charity address in `whitelistedRate` and set globally a default rate of donation. To register the address, the rate **MUST** not be null.
|
||
|
|
|
||
|
|
Token holders **MAY** choose and specify a default charity address from `_defaultAddress`, this address **SHOULD** be different from the null address for the donation to be activated.
|
||
|
|
|
||
|
|
The donation is a percentage-based rate model, but the calculation can be done differently. Applications and individuals can implement this standard by retrieving information with `charityInfo()` , which specifies an assigned rate for a given address.
|
||
|
|
|
||
|
|
This standard provides functionality that allows token holders to donate easily. The donation when activated is done directly in the overridden `transfer`, `transferFrom`, and `approve` functions.
|
||
|
|
|
||
|
|
When `transfer`, `transferFrom` are called the sender's balance is reduced by the initial amount and a donation amount is deduced. The initial transfered amount is transferred to the recipient's balance and an additional donation amount is transfered to a third party (charity). The two transfer are done at the same time and emit two `Transfer` events.
|
||
|
|
Also, if the account has an insufficient balance to cover the transfer and the donation the whole transfer would revert.
|
||
|
|
|
||
|
|
```solidity
|
||
|
|
// SPDX-License-Identifier: CC0-1.0
|
||
|
|
pragma solidity ^0.8.4;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// @dev Required interface of an ERC20 Charity compliant contract.
|
||
|
|
///
|
||
|
|
interface IERC20charity is IERC165 {
|
||
|
|
/// The EIP-165 identifier for this interface is 0x557512b6
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @dev Emitted when `toAdd` charity address is added to `whitelistedRate`.
|
||
|
|
*/
|
||
|
|
event AddedToWhitelist (address toAdd);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @dev Emitted when `toRemove` charity address is deleted from `whitelistedRate`.
|
||
|
|
*/
|
||
|
|
event RemovedFromWhitelist (address toRemove);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @dev Emitted when `_defaultAddress` charity address is modified and set to `whitelistedAddr`.
|
||
|
|
*/
|
||
|
|
event DonnationAddressChanged (address whitelistedAddr);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @dev Emitted when `_defaultAddress` charity address is modified and set to `whitelistedAddr`
|
||
|
|
* and _donation is set to `rate`.
|
||
|
|
*/
|
||
|
|
event DonnationAddressAndRateChanged (address whitelistedAddr,uint256 rate);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @dev Emitted when `whitelistedRate` for `whitelistedAddr` is modified and set to `rate`.
|
||
|
|
*/
|
||
|
|
event ModifiedCharityRate(address whitelistedAddr,uint256 rate);
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Called with the charity address to determine if the contract whitelisted the address
|
||
|
|
*and if it is the rate assigned.
|
||
|
|
*@param addr - the Charity address queried for donnation information.
|
||
|
|
*@return whitelisted - true if the contract whitelisted the address to receive donnation
|
||
|
|
*@return defaultRate - the rate defined by the contract owner by default , the minimum rate allowed different from 0
|
||
|
|
*/
|
||
|
|
function charityInfo(
|
||
|
|
address addr
|
||
|
|
) external view returns (
|
||
|
|
bool whitelisted,
|
||
|
|
uint256 defaultRate
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Add address to whitelist and set rate to the default rate.
|
||
|
|
* @dev Requirements:
|
||
|
|
*
|
||
|
|
* - `toAdd` cannot be the zero address.
|
||
|
|
*
|
||
|
|
* @param toAdd The address to whitelist.
|
||
|
|
*/
|
||
|
|
function addToWhitelist(address toAdd) external;
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Remove the address from the whitelist and set rate to the default rate.
|
||
|
|
* @dev Requirements:
|
||
|
|
*
|
||
|
|
* - `toRemove` cannot be the zero address.
|
||
|
|
*
|
||
|
|
* @param toRemove The address to remove from whitelist.
|
||
|
|
*/
|
||
|
|
function deleteFromWhitelist(address toRemove) external;
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Get all registered charity addresses.
|
||
|
|
*/
|
||
|
|
function getAllWhitelistedAddresses() external ;
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Display for a user the rate of the default charity address that will receive donation.
|
||
|
|
*/
|
||
|
|
function getRate() external view returns (uint256);
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Set personlised rate for charity address in {whitelistedRate}.
|
||
|
|
* @dev Requirements:
|
||
|
|
*
|
||
|
|
* - `whitelistedAddr` cannot be the zero address.
|
||
|
|
* - `rate` cannot be inferior to the default rate.
|
||
|
|
*
|
||
|
|
* @param whitelistedAddr The address to set as default.
|
||
|
|
* @param rate The personalised rate for donation.
|
||
|
|
*/
|
||
|
|
function setSpecificRate(address whitelistedAddr , uint256 rate) external;
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Set for a user a default charity address that will receive donation.
|
||
|
|
* The default rate specified in {whitelistedRate} will be applied.
|
||
|
|
* @dev Requirements:
|
||
|
|
*
|
||
|
|
* - `whitelistedAddr` cannot be the zero address.
|
||
|
|
*
|
||
|
|
* @param whitelistedAddr The address to set as default.
|
||
|
|
*/
|
||
|
|
function setSpecificDefaultAddress(address whitelistedAddr) external;
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Set for a user a default charity address that will receive donation.
|
||
|
|
* The rate is specified by the user.
|
||
|
|
* @dev Requirements:
|
||
|
|
*
|
||
|
|
* - `whitelistedAddr` cannot be the zero address.
|
||
|
|
* - `rate` cannot be less than to the default rate
|
||
|
|
* or to the rate specified by the owner of this contract in {whitelistedRate}.
|
||
|
|
*
|
||
|
|
* @param whitelistedAddr The address to set as default.
|
||
|
|
* @param rate The personalised rate for donation.
|
||
|
|
*/
|
||
|
|
function setSpecificDefaultAddressAndRate(address whitelistedAddr , uint256 rate) external;
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Display for a user the default charity address that will receive donation.
|
||
|
|
* The default rate specified in {whitelistedRate} will be applied.
|
||
|
|
*/
|
||
|
|
function specificDefaultAddress() external view returns (
|
||
|
|
address defaultAddress
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
*@notice Delete The Default Address and so deactivate donnations .
|
||
|
|
*/
|
||
|
|
function deleteDefaultAddress() external;
|
||
|
|
}
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
### Functions
|
||
|
|
|
||
|
|
#### **addToWhitelist**
|
||
|
|
|
||
|
|
Add address to whitelist and set the rate to the default rate.
|
||
|
|
|
||
|
|
| Parameter | Description |
|
||
|
|
| ---------|-------------|
|
||
|
|
| toAdd | The address to the whitelist.
|
||
|
|
|
||
|
|
#### **deleteFromWhitelist**
|
||
|
|
|
||
|
|
Remove the address from the whitelist and set rate to the default rate.
|
||
|
|
|
||
|
|
| Parameter | Description |
|
||
|
|
| ---------|-------------|
|
||
|
|
| toRemove | The address to remove from whitelist.
|
||
|
|
|
||
|
|
#### **getAllWhitelistedAddresses**
|
||
|
|
|
||
|
|
Get all registered charity addresses.
|
||
|
|
|
||
|
|
#### **getRate**
|
||
|
|
|
||
|
|
Display for a user the rate of the default charity address that will receive donation.
|
||
|
|
|
||
|
|
#### **setSpecificRate**
|
||
|
|
|
||
|
|
Set personalized rate for charity address in {whitelistedRate}.
|
||
|
|
|
||
|
|
| Parameter | Description |
|
||
|
|
| ---------|-------------|
|
||
|
|
| whitelistedAddr | The address to set as default. |
|
||
|
|
| rate | The personalised rate for donation. |
|
||
|
|
|
||
|
|
#### **setSpecificDefaultAddress**
|
||
|
|
|
||
|
|
Set for a user a default charity address that will receive donations. The default rate specified in {whitelistedRate} will be applied.
|
||
|
|
|
||
|
|
| Parameter | Description |
|
||
|
|
| ---------|-------------|
|
||
|
|
| whitelistedAddr | The address to set as default.
|
||
|
|
|
||
|
|
#### **setSpecificDefaultAddressAndRate**
|
||
|
|
|
||
|
|
Set for a user a default charity address that will receive donations. The rate is specified by the user.
|
||
|
|
|
||
|
|
| Parameter | Description |
|
||
|
|
| ---------|-------------|
|
||
|
|
| whitelistedAddr | The address to set as default. |
|
||
|
|
| rate | The personalized rate for donation.
|
||
|
|
|
||
|
|
#### **specificDefaultAddress**
|
||
|
|
|
||
|
|
Display for a user the default charity address that will receive donations. The default rate specified in {whitelistedRate} will be applied.
|
||
|
|
|
||
|
|
#### **deleteDefaultAddress**
|
||
|
|
|
||
|
|
Delete The Default Address and so deactivate donations.
|
||
|
|
|
||
|
|
#### **charityInfo**
|
||
|
|
|
||
|
|
Called with the charity address to determine if the contract whitelisted the address and if it is, the rate assigned.
|
||
|
|
|
||
|
|
| Parameter | Description |
|
||
|
|
| ---------|-------------|
|
||
|
|
| addr | The Charity address queried for donnation information.
|
||
|
|
|
||
|
|
## Rationale
|
||
|
|
|
||
|
|
This EIP chooses to whitelist charity addresses by using an array and keeping track of the "active" status with a mapping `whitelistedRate` to allow multiple choice of recipient and for transparence. The donation address can also be a single address chosen by the owner of the contract and modified by period.
|
||
|
|
|
||
|
|
If the sender balance is insuficent i.e total amount of token (initial transfer + donation) is insuficent the transfer would revert. Donation are done in the `transfer` function to simplify the usage and to not add an additional function, but the implementation could be donne differently, and for exemple allow a transfer to go through without the donation amount when donation is activated. The token implementer can also choose to store the donation in the contract or in another one and add a withdrawal or claimable function, so the charity can claim the allocated amount of token themselves, the additional transfer will be triggered by the charity and not the token holder.
|
||
|
|
|
||
|
|
Also, donations amount are calculated here as a percentage of the amount of token transfered to allow different case scenario, but the token implementer can decide to opt for another approach instead like rounding up the transaction value.
|
||
|
|
|
||
|
|
## Backwards Compatibility
|
||
|
|
|
||
|
|
This implementation is an extension of the functionality of [EIP-20](./eip-20.md), it introduces new functionality retaining the core interfaces and functionality of the [EIP-20](./eip-20.md) standard. There is a small backwards compatibility issue, indeed if an account has insufficient balance, it's possible for the transfer to fail.
|
||
|
|
|
||
|
|
## Test Cases
|
||
|
|
|
||
|
|
Tests can be found in [`charity.js`](../assets/eip-6353/test/charity.js).
|
||
|
|
|
||
|
|
## Reference Implementation
|
||
|
|
|
||
|
|
The reference implementation of the standard can be found under [`contracts/`](../assets/eip-6353/contracts/ERC20Charity.sol) folder.
|
||
|
|
|
||
|
|
## Security Considerations
|
||
|
|
|
||
|
|
There are no additional security considerations compared to EIP-20.
|
||
|
|
|
||
|
|
## Copyright
|
||
|
|
|
||
|
|
Copyright and related rights waived via [CC0](../LICENSE.md).
|