An extension to EIP-20 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.
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 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.
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.
Add address to whitelist and set the rate to the default rate.
| Parameter | Description |
|---|---|
| toAdd | The address to the whitelist. |
Remove the address from the whitelist and set rate to the default rate.
| Parameter | Description |
|---|---|
| toRemove | The address to remove from whitelist. |
Get all registered charity addresses.
Display for a user the rate of the default charity address that will receive donation.
Set personalized rate for charity address in {whitelistedRate}.
| Parameter | Description |
|---|---|
| whitelistedAddr | The address to set as default. |
| rate | The personalised rate for donation. |
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. |
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. |
Display for a user the default charity address that will receive donations. The default rate specified in {whitelistedRate} will be applied.
Delete The Default Address and so deactivate donations.
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. |
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.
This implementation is an extension of the functionality of EIP-20, it introduces new functionality retaining the core interfaces and functionality of the EIP-20 standard. There is a small backwards compatibility issue, indeed if an account has insufficient balance, it's possible for the transfer to fail.
Tests can be found in charity.js.
The reference implementation of the standard can be found under contracts/ folder.
There are no additional security considerations compared to EIP-20.
Copyright and related rights waived via CC0.