cw_vesting/msg.rs
1use cosmwasm_schema::{cw_serde, QueryResponses};
2use cosmwasm_std::{Timestamp, Uint128};
3use cw20::Cw20ReceiveMsg;
4use cw_denom::UncheckedDenom;
5use cw_ownable::cw_ownable_execute;
6use cw_stake_tracker::StakeTrackerQuery;
7
8use crate::vesting::Schedule;
9
10#[cw_serde]
11pub struct InstantiateMsg {
12 /// The optional owner address of the contract. If an owner is
13 /// specified, the owner may cancel the vesting contract at any
14 /// time and withdraw unvested funds.
15 pub owner: Option<String>,
16 /// The receiver address of the vesting tokens.
17 pub recipient: String,
18
19 /// The a name or title for this payment.
20 pub title: String,
21 /// A description for the payment to provide more context.
22 pub description: Option<String>,
23
24 /// The total amount of tokens to be vested.
25 pub total: Uint128,
26 /// The type and denom of token being vested.
27 pub denom: UncheckedDenom,
28
29 /// The vesting schedule, can be either `SaturatingLinear` vesting
30 /// (which vests evenly over time), or `PiecewiseLinear` which can
31 /// represent a more complicated vesting schedule.
32 pub schedule: Schedule,
33 /// The time to start vesting, or None to start vesting when the
34 /// contract is instantiated. `start_time` may be in the past,
35 /// though the contract checks that `start_time +
36 /// vesting_duration_seconds > now`. Otherwise, this would amount
37 /// to a regular fund transfer.
38 pub start_time: Option<Timestamp>,
39 /// The length of the vesting schedule in seconds. Must be
40 /// non-zero, though one second vesting durations are
41 /// allowed. This may be combined with a `start_time` in the
42 /// future to create an agreement that instantly vests at a time
43 /// in the future, and allows the receiver to stake vesting tokens
44 /// before the agreement completes.
45 ///
46 /// See `suite_tests/tests.rs`
47 /// `test_almost_instavest_in_the_future` for an example of this.
48 pub vesting_duration_seconds: u64,
49
50 /// The unbonding duration for the chain this contract is deployed
51 /// on. Smart contracts do not have access to this data as
52 /// stargate queries are disabled on most chains, and cosmwasm-std
53 /// provides no way to query it.
54 ///
55 /// This value being too high will cause this contract to hold
56 /// funds for longer than needed, this value being too low will
57 /// reduce the quality of error messages and require additional
58 /// external calculations with correct values to withdraw
59 /// avaliable funds from the contract.
60 pub unbonding_duration_seconds: u64,
61}
62
63#[cw_ownable_execute]
64#[cw_serde]
65pub enum ExecuteMsg {
66 /// Fund the contract with a cw20 token. The `msg` field must have
67 /// the shape `{"fund":{}}`, and the amount sent must be the same
68 /// as the amount to be vested (as set during instantiation).
69 /// Anyone may call this method so long as the contract has not
70 /// yet been funded.
71 Receive(Cw20ReceiveMsg),
72 /// Distribute vested tokens to the vest receiver. Anyone may call
73 /// this method.
74 Distribute {
75 /// The amount of tokens to distribute. If none are specified
76 /// all claimable tokens will be distributed.
77 amount: Option<Uint128>,
78 },
79 /// Cancels the vesting payment. The current amount vested becomes
80 /// the total amount that will ever vest, and all pending and
81 /// future staking rewards from tokens staked by this contract
82 /// will be sent to the owner. Tote that canceling does not impact
83 /// already vested tokens.
84 ///
85 /// Upon canceling, the contract will use any liquid tokens in the
86 /// contract to settle pending payments to the vestee, and then
87 /// returns the rest to the owner. Staked tokens are then split
88 /// between the owner and the vestee according to the number of
89 /// tokens that the vestee is entitled to.
90 ///
91 /// The vestee will no longer receive staking rewards after
92 /// cancelation, and may unbond and distribute (vested - claimed)
93 /// tokens at their leisure. the owner will receive staking
94 /// rewards and may unbond and withdraw (staked - (vested -
95 /// claimed)) tokens at their leisure.
96 Cancel {},
97 /// This is translated to a
98 /// [MsgDelegate](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90).
99 /// `delegator_address` is automatically filled with the current
100 /// contract's address. Note: this only works with the native
101 /// staking denom of a Cosmos chain. Only callable by Vesting
102 /// Payment Recipient.
103 #[cfg(feature = "staking")]
104 Delegate {
105 /// The validator to delegate to.
106 validator: String,
107 /// The amount to delegate.
108 amount: Uint128,
109 },
110 /// This is translated to a
111 /// [MsgBeginRedelegate](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L96).
112 /// `delegator_address` is automatically filled with the current
113 /// contract's address. Only callable by Vesting Payment
114 /// Recipient.
115 #[cfg(feature = "staking")]
116 Redelegate {
117 src_validator: String,
118 dst_validator: String,
119 amount: Uint128,
120 },
121 /// This is translated to a
122 /// [MsgUndelegate](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121).
123 /// `delegator_address` is automatically filled with the current
124 /// contract's address. Only callable by Vesting Payment
125 /// Recipient.
126 #[cfg(feature = "staking")]
127 Undelegate {
128 /// The validator to undelegate from
129 validator: String,
130 /// The amount to delegate
131 amount: Uint128,
132 },
133 /// This is translated to a
134 /// [MsgSetWithdrawAddress](https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L31-L37).
135 /// `delegator_address` is automatically filled with the current
136 /// contract's address. Only callable by Vesting Payment
137 /// Recipient.
138 #[cfg(feature = "staking")]
139 SetWithdrawAddress { address: String },
140 /// This is translated to a
141 /// [MsgWithdrawDelegatorReward](https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50).
142 /// `delegator_address` is automatically filled with the current
143 /// contract's address.
144 #[cfg(feature = "staking")]
145 WithdrawDelegatorReward {
146 /// The validator to claim rewards for.
147 validator: String,
148 },
149 /// If the owner cancels a payment and there are not enough liquid
150 /// tokens to settle the owner may become entitled to some number
151 /// of staked tokens. They may then unbond those tokens and then
152 /// call this method to return them.
153 WithdrawCanceledPayment {
154 /// The amount to withdraw.
155 amount: Option<Uint128>,
156 },
157 /// Registers a slash event bonded or unbonding tokens with the
158 /// contract. Only callable by the owner as the contract is unable
159 /// to verify that the slash actually occured. The owner is
160 /// assumed to be honest.
161 ///
162 /// A future version of this contract may be able to
163 /// permissionlessly take slashing evidence:
164 /// <https://github.com/CosmWasm/mesh-security/issues/35>
165 #[cfg(feature = "staking")]
166 RegisterSlash {
167 /// The validator the slash occured for.
168 validator: String,
169 /// The time the slash event occured. Note that this is not
170 /// validated beyond validating that it is < now. This means
171 /// that if two slash events occur for a single validator, and
172 /// then this method is called, a dishonest sender could
173 /// register those two slashes as a single larger one at the
174 /// time of the first slash.
175 ///
176 /// The result of this is that the staked balances tracked in
177 /// this contract can not be relied on for accurate values in
178 /// the past. Staked balances will be correct at time=now.
179 time: Timestamp,
180 /// The number of tokens that THIS CONTRACT lost as a result
181 /// of the slash. Note that this differs from the total amount
182 /// slashed from the validator.
183 amount: Uint128,
184 /// If the slash happened during unbonding. Set to false in
185 /// the common case where the slash impacted bonding tokens.
186 during_unbonding: bool,
187 },
188}
189
190#[cw_serde]
191pub enum ReceiveMsg {
192 /// Funds a vesting contract with a cw20 token
193 Fund {},
194}
195
196#[cw_serde]
197#[derive(QueryResponses)]
198pub enum QueryMsg {
199 /// Get the current ownership.
200 #[returns(::cw_ownable::Ownership<::cosmwasm_std::Addr>)]
201 Ownership {},
202 /// Returns information about the vesting contract and the
203 /// status of the payment.
204 #[returns(crate::vesting::Vest)]
205 Info {},
206 /// Returns the number of tokens currently claimable by the
207 /// vestee. This is the minimum of the number of unstaked tokens
208 /// in the contract, and the number of tokens that have been
209 /// vested at time t.
210 #[returns(::cosmwasm_std::Uint128)]
211 Distributable {
212 /// The time or none to use the current time.
213 t: Option<Timestamp>,
214 },
215 /// Gets the current value of `vested(t)`. If `t` is `None`, the
216 /// current time is used.
217 #[returns(::cosmwasm_std::Uint128)]
218 Vested { t: Option<Timestamp> },
219 /// Gets the total amount that will ever vest, `max(vested(t))`.
220 ///
221 /// Note that if the contract is canceled at time c, this value
222 /// will change to `vested(c)`. Thus, it can not be assumed to be
223 /// constant over the contract's lifetime.
224 #[returns(::cosmwasm_std::Uint128)]
225 TotalToVest {},
226 /// Gets the amount of time between the vest starting, and it
227 /// completing. Returns `None` if the vest has been cancelled.
228 #[returns(Option<::cosmwasm_std::Uint64>)]
229 VestDuration {},
230 /// Queries information about the contract's understanding of it's
231 /// bonded and unbonding token balances. See the
232 /// `StakeTrackerQuery` in `packages/cw-stake-tracker/lib.rs` for
233 /// query methods and their return types.
234 #[returns(::cosmwasm_std::Uint128)]
235 Stake(StakeTrackerQuery),
236}