Rates
The Rates ADO is a smart contract used to impose some kind of fees on fund transactions.
This contract is implemented as a module and attached to other contracts which would apply the specified rates on any fund transfers. The contract owner can specify specific addresses to be exempt from these rates. A small example on this would be putting rates on a CW721 ADO, sending a percentage as tax/royalty to the original owner whenever an NFT is sold.
There are two main types of rates:
- Taxes: Funds are added to the price and paid by the buyer.
- Royalties: Funds are deducted from the price and are paid by the seller.
Ado_type: rates
Rust
JSON
pub struct InstantiateMsg {
pub rates: Vec<RateInfo>,
}
{
"rates":
[
{
"rate":{
"percent":{
"percent":"0.1"
},
"is_additive": false,
"recipients":[{
"addr":"andr1..."
},
{
"addr":"andr1..."
}
]
},
...
]
}
Name | Type | Description |
|---|---|---|
rates | A vector containing the different RateInfo of the contract. |
The information about the rates is stored in a
RateInfo struct.Each of the recipients will receive the rate imposed. ( The rate is 3% and we have 5 recipients then 15 % would go to them in total.)
Taxes are added to the selling price (Paid by buyer) while royalties are deducted from the price (Paid by seller).
pub struct RateInfo {
pub rate: Rate,
pub is_additive: bool,
pub description: Option<String>,
pub recipients: Vec<Recipient>,
}
An enum used to define various types of fees which is used in the RateInfo.
pub enum Rate {
Flat(Coin),
Percent(PercentRate),
External(PrimitivePointer),
}
The Rate can be one of the three option seen above:
The flat rate needs to be a whole number.
The percentage rate needs to be a decimal i.e 0.2 for 20%
- Percent: A percentage based rate. Needs to have the percent specified.
- External: This refers to a rate that we want to use which is saved in a primitive contract. Needs the address of the primitive and the key of the stored Rate primitive to be specified. The value saved in the primitive needs to be one of two types:
1. Decimal: If the value is a decimal then the rate taken will be a percentage equivalent to the specified decimal value.
2.Coin: If the value is of type coin then the rate taken will be flat equivalent to the a. amount specified in the coin value.
Any other type of value will not be will not apply any rates.
pub struct PercentRate {
pub percent: Decimal,
}
Name | Type | Description |
|---|---|---|
percent | Decimal | The percentage to take as rate. |
PrimitivePointer
pub struct PrimitivePointer {
pub address: AndrAddress,
pub key: Option<String>,
}
Name | Type | Description |
|---|---|---|
address | The address of the primitive contract. | |
key | Option<String> | The key for the stored data. If not specified, then the default key is used. |
Only the contract owner can execute UpdateRates.
Rust
JSON
pub enum ExecuteMsg{
UpdateRates{
rates: Vec<RateInfo>
}
}
{
"update_rates":{
"rates":
[
{
"rate":{
"percent":{
"percent":"0.1"
},
"is_additive": false,
"recipients":[
{
"addr":"andr1..."
},
{
"addr":"andr1..."
},
...
]
},
...
]
}
}
Name | Type | Description |
|---|---|---|
rates | A vector containing the new RateInfo to be used by the contract. |
Specifies an address to be exempt from any rates set by this contract.
Only available to the contract owner.
Rust
JSON
pub enum ExecuteMsg {
AddExemption {
address: String
}
}
{
"add_exemption":{
"address":"andr1..."
}
}
Name | Type | Description |
|---|---|---|
address | String | The address that will not have the rates applied. |
Removes an address from the list of exempt addresses.
Rust
JSON
pub enum ExecuteMsg {
RemoveExemption {
address: String
}
}
{
"remove_exemption":{
"address":"andr1..."
}
}
Name | Type | Description |
|---|---|---|
address | String | The address to remove the exemption from. |
Returns the rates used by the contract in a vector of
RateInfo.Rust
JSON
pub enum QueryMsg{
#[returns(PaymentsResponse)]
Payments {}
}
{
"payments":{}
}
Rust
JSON
pub struct PaymentsResponse {
pub payments: Vec<RateInfo>,
}
{
"payments":
[
{
"rate":{
"percent":{
"percent":"0.3"
}
},
"is_additive": false,
"recipients":[
{
"addr":"andr1..."
},
{
"addr":"andr1..."
},
...
]
},
...
]
}
Name | Type | Description |
|---|---|---|
payments | A vector of the RatInfo currently used by the contract. |
Checks if the specified address is exempt from rates.
Rust
JSON
pub enum QueryMsg {
#[returns(bool)]
IsExempt {address: String }
}
{
"is_exempt":{
"address":"andr1..."
}
}
Name | Type | Description |
|---|---|---|
address | String | The address to check if exempt from rates. |
Returns true if included and false otherwise.
Queries the list of addresses exempt from rates.
Rust
JSON
pub enum QueryMsg {
#[returns(ExemptionsResponse)]
Exemptions {
limit: Option<u32>,
start_after: Option<String>,
}
}
{
"exemptions":{
"limit": 80
}
}
Name | Type | Description |
|---|---|---|
limit | Option<u32> | An optional limit on how many are returned. Default limit is 50 and the maximum limit that can be set is 100. |
start_after | Option<String> | An optional Id for which to start after, used for pagination. |
Rust
JSON
pub struct ExemptionsResponse {
pub exemptions: Vec<String>,
}
{
"exemptions":["andr1...","andr1...",...]
}
An ADO accepts the addition of multiple rates at once. This could be one of two cases:
- 1.Adding multiple rates using the same rates module ADO.
- 2.Adding multiple rates using different rates module ADOs
In this case, all the rates are applied on the initial price of the NFT being sold. For example, if I specify the following rates:
- 350 flat rate royalty
- 10% royalty
Then selling the NFT for 1000 uandr will take 350 uandr for the first rate and 100 uandr for the second rate.
In this case, the rates are applied by order. After the first deductions are made, the second rate will use the remaining amount and deduct from it. For example, if I specify the following rates:
- 350 flat rate royalty using the first rates ADO
- 10% royalty using the second rates ADO
Then selling the NFT for 1000 uandr will take 350 uandr for the first rate and 65 uandr for the second rate.