Conditional Splitter

Introduction

The Conditional Splitter ADO is a smart contract used to split funds to specified recipients based on the amount that is sent. At instantiation, the owner specifies the recipient sets along with the minimum amount of funds needed for each set.

The ADO can be locked by the owner meaning that the recipient lists cannot be changed for the duration of the lock.

Example:

A user has 3 recurring monthly payments that they need to pay:

1. Employee Salaries: 5000 tokens needed to pay the salaries of 5 employees.

2. Family Allowances: User needs 1000 tokens to be distributed to 4 family members as a monthly allowance.

3. Subscription Payments: 300 tokens needed to pay for 2 subscription services.

Instead of having to do this manually every month, the user can set up the conditional splitter as follows:

1. First list of recipients are the employee addresses wiht a min threshold of 5000

2. Seconds set of recipients are the family addresses with a threshold of 500

3. Third set of recipients are the addresses for the subscription services with a threshold of 300

For each split, the owner specifies the percentage of each recipient.

This means that if the amount of funds sent is between 300 and 1000, they will go to the subscription addresses. If the amount sent is between 1000 and 5000, then they are split between the family addresses. Finally, if the amount sent is greater or equal to 5000, then the funds are split between the employee addresses.

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

ADO_type: conditional-splitter

Version: 1.3.0-beta

InstantiateMsg

The lock time can only be set between 86400 and 31536000 (1 day and 1 year).

All of the amounts are specified in micro denomination (uandr and not ANDR). For example, a min of 500000 = 0.5 ANDR.

Rust

pub struct InstantiateMsg {
    pub thresholds: Vec<Threshold>,
    pub lock_time: Option<Expiry>,
    pub kernel_address:String,
    pub owner: Option<String>,
}

JSON

{
  "thresholds": [
    {
      "min": "1000",
      "address_percent": [
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.5"
        },
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.5"
        }
      ]
    },
    {
      "min": "5000",
      "address_percent": [
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.7"
        },
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.3"
        }
      ]
    }
  ],
  "lock_time":{ 
       "from_now":6000000,
      }
  "kernel_address":"andr1..."
}

Name	Type	Description
thresholds	Vec<Threshold>	The sets of recipients, their weights and the min threshold amount.
lock_time	Option<Expiry>	How long the splitter is locked. When locked, no recipients can be added/changed. Duration specified in milliseconds.
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.

Threshold

The min field is specified in micro denomination (uandr).

pub struct Threshold {
    pub min: Uint128,
    pub address_percent: Vec<AddressPercent>,
}

Name	Type	Description
min	Uint128	The minimum amount of funds needed to be sent for the corresponding address_percent to be applied.
address_percent	Vec<AddressPercent>	The addresses and percentages for the recipients.

AddressPercent

pub struct AddressPercent {
    pub recipient: Recipient,
    pub percent: Decimal,
}

Name	Type	Description
recipient	Recipient	The address to receive the specified percent.
percent	Decimal	The percent to be received by the specified recipient.

ExecuteMsg

UpdateThresholds

Update the list of recipients and thresholds.

Only available to the ADO owner.

Cannot be called if there is an existing lock that has not expired yet.

Rust

pub enum ExecuteMsg {
    UpdateThresholds {
       thresholds: Vec<Threshold> 
       },
    }

JSON

{
  "thresholds": [
    {
      "min": "7000",
      "address_percent": [
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.3"
        },
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.7"
        }
      ]
    },
    {
      "min": "5000",
      "address_percent": [
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.2"
        },
        {
          "recipient": {
            "address": "andr1..."
          },
          "percent": "0.8"
        }
      ]
    }
  ]
}

Name	Type	Description
thresholds	Vec<Threshold>	The new recipient sets and minimum thresholds.

UpdateLock

Add a new lock time for the recipient sets.

Only available to the ADO owner.

Cannot be called if there is an existing lock that has not expired yet.

Rust

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

JSON

{
"update_lock":{
    "lock_time":600000000
    }
}

Name	Type	Description
lock_time	MillisecondsDuration	How long the splitter is locked. When locked, no recipients can be added/changed. Duration specified in milliseconds.

Send

Divides any attached funds to the message amongst the recipients.

The funds are sent to the recipient set with the closest threshold that is less than the amount sent. For example if we have thresholds 300, 600, 1500, and 2000, then sending 400 goes to the first set, 1400 to the second set, 1980 to the third set, and anything equal or greater than 2000 to the fourth set.

Rust

pub enum ExecuteMsg {
     Send {},
  }

JSON

{
"send"{}
}

Base Executes

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

QueryMsg

GetConditionalSplitterConfig

Queriest the splitter's recipient sets and thresholds and lock time if found.

Rust

pub enum QueryMsg {
    #[returns(GetConditionalSplitterConfigResponse)]
    GetConditionalSplitterConfig {},
}

JSON

{
"get_conditional_splitter_config"{}
}

GetConditionalSplitterConfigResponse

pub struct GetConditionalSplitterConfigResponse {
    pub config: ConditionalSplitter,
}

pub struct ConditionalSplitter {
    pub thresholds: Vec<Threshold>,
    pub lock_time: Option<MillisecondsExpiration>,
}

Base Queries

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