Weighted Distribution Splitter

Introduction

The Weighted-Distribution-Splitter ADO is a smart contract to split funds among a set of defined recipients. Each of the recipients is assigned a weight which is divided by the total weight to get the percentage of each of the recipients. Whenever the splitter receives funds by executing a send it automatically splits the funds to the defined recipients. The splitter can be locked for a specified time as a kind of insurance for recipients that their weights will not be changed for a certain period of time.

Example:

On instantiation, the following weights are assigned:

• User A weight: 5

• User B weight: 3

• User C weight: 4

Then the total weight is 12 and A receives 5/12 of the funds, B receives 3/12 of the funds and C receives 4/12 of the funds. If a recipient is then added, the total weight is increased and the percentages are recalculated.

We also have a percentage based spliiter, set amount splitter, and conditional splitter.

Ado_type: weighted-distribution-splitter

Version: 2.1.0-beta

InstantiateMsg

A maximum of 100 recipients can be set.

The minimum time that can be set is 86,400 which is 1 day.

The maximum time that can be set is 31,536,000 which is 1 year.

Rust

pub struct InstantiateMsg {
    pub recipients: Vec<AddressWeight>,
    pub lock_time: Option<u64>,
    pub kernel_address: String,
    pub owner: Option<String>,
}

JSON

{
"recipients":[
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 4
                  },
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 7
                  },
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 2
                  }
                ]
     }

Name	Type	Description
recipients	Vec<AddressWeight>	The vector of recipients for the contract. Anytime a Send execute message is sent, the amount sent will be divided amongst these recipients depending on their assigned weight.
lock_time	Option<u64>	How long the splitter is locked. When locked, no recipients/weights can be added/changed by the owner.
default_recipient	Option<Recipient>	An optional recipient to receive any leftover funds in case the split is not exactly distributed. Defaults to the sender if not specified.
kernel_address	String	Contract address of the kernel contract to be used for AMP messaging. Kernel contract address can be found in our deployed contracts.
owner	Option<String>	Optional address to specify as the owner of the ADO being created. Defaults to the sender if not specified.

AddressWeight

struct containing the recipient of the funds and the assigned weight for that recipient.

pub struct AddressWeight {
    pub recipient: Recipient,
    pub weight: Uint128,
}

Name	Type	Description
recipient	Recipient	The address to recieve the funds.
weight	Uint128	The weight of the address above.

ExecuteMsg

UpdateRecipients

Updates the recipients of the splitter. When executed, the previous recipients and distribution are replaced by the new list.

Only available to the contract owner when the contract is not locked.

Rust

pub enum ExecuteMsg {
      UpdateRecipients {
        recipients: Vec<AddressWeight>,
    }
}

JSON

{
"update_recipients":{
    "recipients":[
               {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 1
                  },
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 4
                  },
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 12
                  }
                ]
        }
}

Name	Type	Description
recipients	Vec<AddressWeight>	The new recipients of the split funds with their assigned weights.

AddRecipient

Add a recipient to the list.

Only available to the contract owner when the contract is not locked.

When a recipient is added, the total weight is changed and all the weights are recalculated appropriately.

Rust

pub enum ExecuteMsg {
   AddRecipient {
        recipient: AddressWeight,
    }
}

JSON

{
"add_recipient":{
    "recipient":{
            "recipient":{
                 "address":"andr1..."
                },
            "weight": 1
              }
      }

Name	Type	Description
recipient	AddressWeight	The recipient to add along with the corresponding weight.

RemoveRecipient

Only available to the contract owner/ operator when the contract is not locked.

Remove a recipient from the distribution.

Rust

pub enum ExecuteMsg {
     RemoveRecipient {
        recipient: Recipient,
    }
}

JSON

{
"remove_recipient":{
    "recipient":{
        "address":"andr1..."
        }
    }

Name	Type	Description
recipient	Recipient	The recipient to remove from the list.

UpdateLock

Used to lock the contract for a certain period of time making it unmodifiable in any way. This can serve as a way to ensure for recipients that their weights from the splitter are fixed for a certain amount of time. The time is calculated in seconds.

Only available to the contract owner/operator.

The minimum time that can be set is 86,400 which is 1 day.

The maximum time that can be set is 31,536,000 which is 1 year.

Rust

pub enum ExecuteMsg {
     UpdateLock {
        lock_time: u64,
    }
}

JSON

{
"update_lock":{
    "lock_time": 200000
    }
}

Name	Type	Description
lock_time	u64	The time in seconds to lock the contract for.

UpdateRecipientWeight

Updates the weight of a specific recipient from the list of recipients.

Only available to the contract owner when the contract is not locked.

Rust

 pub enum ExecuteMsg { 
     UpdateRecipientWeight {
        recipient: AddressWeight,
    }
}

JSON

{
"update_recipient_weight":{
    "recipient":{
            "recipient":{
                 "address":"andr1..."
                },
            "weight": 1
              }
      }

Name	Type	Description
recipient	AddressWeight	The new weight for the recipient.

Send

Divides any attached funds to the message amongst the recipients list.

A maximum of 5 types of funds can be sent in one send message.

Rust

pub enum ExecuteMsg {
    Send {
     config: Option<Vec<AddressWeight>> 
    }
}

JSON

{
"send":{}
}

Name	Type	Description
config	Option<Vec<AddressWeight>>	An optional set of recipients/weights to use for the split. If not defined, then the default configuration (List defined at instantiation) will be used.

UpdateDefaultRecipient

Updates the set default recipient.

Only available to the contract owner.

Rust

pub enum ExecuteMsg {
  UpdateDefaultRecipient {
        recipient: Option<Recipient>,
    },
}

JSON

{
    "update_default_recipient": {
        "recipient":{
            "address":"andr1..."
            }
        }
}

Name	Type	Description
recipient	Option<Recipient>	The new recipient to receive any leftover funds in case the split is not exactly distributed. For example if a user sets 40% to one user, and 50% to another, and forgets about the last 10%, they would go this default recipient. Defaults to the sender if not specified.

Base Executes

Base Executes

The rest of the execute messages can be found in the ADO Base section.

QueryMsg

GetSplitterConfig

Queries the current config of the contract.

Rust

pub enum QueryMsg {
      #[returns(GetSplitterConfigResponse)]
      GetSplitterConfig {},
}

JSON

{
"get_splitter_config":{}
}

GetSplitterConfigResponse

Rust

pub struct GetSplitterConfigResponse {
    pub config: Splitter,
}

JSON

{
 "config":{
     "recipients":[
               {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 1
                  },
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 4
                  },
                {
                  "recipient":{
                    "address":"andr1..."
                    },
                  "weight": 12
                  }
                ],
    "lock": {
        "at_time": "1655212973"
        }
          
    }
  }

Splitter

pub struct Splitter {
    pub recipients: Vec<AddressWeight>,
    pub lock: Expiration,
}

Name	Type	Description
recipients	Vec<AddressWeight>	The vector of recipients for the contract. Anytime a Send execute message is sent the amount sent will be divided amongst these recipients depending on their assigned weight.
locked	Expiration	The expiration time of the lock. Will return an epoc time which is equal to the current_time + lock_time taken at the point of setting the lock. (Current time refers to the time the lock was set and not the time in this moment.)

GetUserWeight

Queries the user's allocated weight.

Rust

pub enum QueryMsg {
    #[returns(GetUserWeightResponse)]
    GetUserWeight {
        user: Recipient,
        }
    }

JSON

{
"get_user_weight":{
    "user":{
        "address":"andr1..."
        }
    }
}

Name	Type	Description
user	Recipient	The user we want to check the weight for.

GetUserWeightResponse

pub struct GetUserWeightResponse {
    pub weight: Uint128,
    pub total_weight: Uint128,
}

Name	Type	Description
weight	Uint128	The weight of the user.
total_weight	Uint128	The total weight of the splitter.

Base Queries

The rest of the query messages can be found in the ADO Base section.