feat: implement true vesting accounts with clawback #155

JimLarson · 2022-01-10T19:47:50Z

Description

Implements "true" vesting accounts which are subject to clawback.

True vesting accounts have a lockup schedule and a vesting schedule. Any tokens may be staked, but cannot be withdrawn unless they are both unlocked and vested. At any time, the account which funded the true vesting account may command a "clawback" of the unvested amount. The clawback may result in the transfer of bonded or unbonding tokens.

Staking rewards are encumbered with vesting in proportion to the vested/unvested ratio of the staked tokens.

This PR contains:

proto definitions for the new account type and messages
updates the vesting app module and message handler to include a staking keeper
CLI for account creation and clawback commands
message handler methods for the new messages
utilities for merging schedules in various ways
implementation of new account type with clawback and reward methods
hook in distribution keeper for post-reward action on certain accounts
staking keeper operations to transfer staked and unbonding amounts

The last is the most critical to review, as it mutates core staking data structures.

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

confirmed the correct type prefix in the PR title
confirmed ! in the type prefix if API or client breaking change
confirmed all author checklist items have been addressed
reviewed state machine logic
reviewed API design and naming
reviewed documentation is accurate
reviewed tests and test coverage
manually tested (if applicable)

michaelfig

Just posting now so that you have time to act on the bikeshed. Still reviewing the rest of the PR.

docs/core/proto-docs.md

proto/cosmos/vesting/v1beta1/tx.proto

x/auth/vesting/client/cli/tx.go

michaelfig

Wow! Good stuff!

I didn't find anything that looked suspicious, but there are just a few nits I pointed out.

x/auth/vesting/msg_server.go

michaelfig · 2022-01-10T20:52:44Z

x/auth/vesting/msg_server.go

+}
+
+// Clawback removes the unvested amount from a TrueVestingAccount.
+// The destination defaults to the funder address, but


Incomplete thought?

x/auth/vesting/msg_server.go

x/auth/vesting/types/period.go

x/auth/vesting/types/vesting_account.go

JimLarson · 2022-01-11T03:51:40Z

I've addressed all but one to-fix comment, so the code is ready for review.

I'll be concurrently working on the tests. Please request particular tests to cover.

zmanian · 2022-01-17T09:32:25Z

x/staking/keeper/delegation.go

+// TransferDelegation changes the ownership of at most the desired number of shares.
+// Returns the actual number of shares transferred. Will also transfer redelegation
+// entries to ensure that all redelegations are matched by sufficient shares.
+// Note that no tokens are transferred to or from any pool or account, since no
+// delegation is actually changing state.


My view has been that transfer delegation should be in the upstream staking module. It's useful in a lot of scenarios and I don't think it harms proof of stake security. I think there should be a message type for in the delegation module

Agree, this is useful and should be upstreamed to the SDK

Filed Agoric/agoric-sdk#4315 for a later PR to surface this feature.

zmanian · 2022-01-17T10:22:05Z

x/auth/vesting/types/vesting_account.go

+			if !found {
+				panic("validator not found") // shouldn't happen
+			}
+			wantShares, err := validator.SharesFromTokensTruncated(want)


This should handle a slashing event correctly

Do you mean "this should be changed so that it handles slashing" or "it's great that this already handles slashing"? It looks like validators are never removed if any delegator is still holding shares, but I made the code tolerate a missing validator, reading the delegation as having no value, both here and in similar following code..

zmanian

Looked for the obvious edge case like Clawback after slashing and it does the correct things

fedekunze

This implementation has a lot of nice additions to the vesting logic. Unfortunately, it's really hard to follow through. I'd highly recommend using specific names for variables, adding more comments on top of the functions and inside them to complement the code and make it more maintainable.

As for the staking and distribution, I think they can be split into a separate PR and upstreamed to the SDK. I highly recommend using a distribution hook for rewards instead of a SmartAccount.

fedekunze · 2022-01-17T12:41:17Z

proto/cosmos/vesting/v1beta1/tx.proto

@@ -43,8 +48,39 @@ message MsgCreatePeriodicVestingAccount {
  string   to_address                      = 2 [(gogoproto.moretags) = "yaml:\"to_address\""];
  int64    start_time                      = 3 [(gogoproto.moretags) = "yaml:\"start_time\""];
  repeated Period vesting_periods = 4 [(gogoproto.nullable) = false];
+  bool merge = 5;


what does merge mean, can you add a comment?

It means to merge the described grant into an existing PeriodicVestingAccount, or create it if it does not exist.

Added a comment here, and for the like-named field in MsgCreateTrueVestingAccount.

what's the use case for merging?

You'll have to ask @dtribble or @rowgraus for the exact justification. We want merging for TrueVestingAccount too in order to be able to make staking rewards vest.

fedekunze · 2022-01-17T12:42:33Z

proto/cosmos/vesting/v1beta1/tx.proto

+  string from_address = 1 [(gogoproto.moretags) = "yaml:\"from_address\""];
+  string   to_address                      = 2 [(gogoproto.moretags) = "yaml:\"to_address\""];


are these the tx signer and vesting addresses? or the vesting and the "admin"?

Since we decided that creating a ClawbackVestingAccount (revised name, renaming commit will follow) is a non-privileged operation, we don't want to use the term "admin", so we're describing the one making the grant (and signing it) as the "funder". Added descriptions in all the request message fields to make things more clear.

fedekunze · 2022-01-17T12:44:03Z

proto/cosmos/vesting/v1beta1/vesting.proto

+  BaseVestingAccount base_vesting_account = 1 [(gogoproto.embed) = true];
+
+  // funder_address specifies the account which can perform clawback.
+  string funder_address = 2;


nit, I'd rename this to admin

In this implementation we decided not to make it a privileged operation to create a vesting account, so it would be better to have a name that doesn't suggest a privileged role. Open to suggestions other than "funder", though.

sounds good

fedekunze · 2022-01-17T12:44:21Z

proto/cosmos/vesting/v1beta1/vesting.proto

+  // funder_address specifies the account which can perform clawback.
+  string funder_address = 2;
+  int64 start_time = 3 [(gogoproto.moretags) = "yaml:\"start_time\""];
+  repeated Period combined_periods = 4 [(gogoproto.moretags) = "yaml:\"combined_periods\"", (gogoproto.nullable) = false];


what are combined periods?

They are explained here: Agoric/agoric-sdk#4085 (comment)
Probably good to have inline comments for these as well IMO.

But I also don't find it very easy to follow.

Can someone answer this:

Let's say someone's tokens are subject to 36 months vesting AND lockup from TGE, released every 6 months.
After month 6, is it:

Option 1: 1/6th of "subject-to-lockup" tokens become vested, but only 1/6th of "subject-to-lockup" tokens are unlocked, which means that in fact they can only sell 1/36th of those tokens;

OR

Option 2: the lockup runs concurrently to vesting; e.g. for all tokens regardless of vesting, it is the case that no more than x tokens shall be sold according to some lockup schedule. So after 6 months, 1/6th of tokens will be unlocked and unvested.

Or are both scenarios possible/configurable depending on the schedule of each? If so, how?

I'll add comments here too. Combined periods gives the merge of the unlocking schedule and the vesting schedule, to determine when tokens are actually unencumbered. For instance, if I make a clawback grant of 1000 today (2022-01-17) that vests a 1/4th every 3months, but all of it is locked until Nov 1, then we'd have:

Unlocking schedule: 2022-11-01: 1000 Vesting schedule: 2022-04-17: 250 2022-07-17: 250 2022-10-17: 250 2023-01-17: 250 Combined schedule (when tokens are both vested and unlocked): 2022-11-01: 750 2023-01-17: 250

Per a note in vesting_accounts.go, I'm considering dropping the combined_periods field and just querying the two schedules directly. I'd expect the common use case is a vesting schedule with dozens of events, but with a lockup cliff, so this would be just as efficient.

I think we can remove the combined schedule actually 👍

Okay, I'll implement that.

BTW, this PR is fighting against the prevailing terminology in x/auth/vesting in that it uses "vesting" only to describe the status associated with clawback, and "lockup" to describe the encumbrance that prevents transfer - i.e. what is called "vesting" elsewhere. Let me know if I need to be even more emphatic about this in the comments.

What would you have instead of the combined schedule then? I think it's important to keep it, because Option 1 of the comment above is unlikely to be the understanding of what most people mean by combined vesting and lockup, or the contractual terms.

Oh, we'll have the same behavior, but we just won't precompute the combined schedule. I.e. to get the unlocked coins at time t, instead of computing ReadSchedule(combined_periods, t), we'd compute min(ReadSchedule(lockup_periods, t), ReadSchedule(vesting_periods, t). (Not the exact API calls, of course, but that's the idea.)

fedekunze · 2022-01-17T12:46:41Z

x/auth/vesting/client/cli/tx.go


+			funderString, _ := cmd.Flags().GetString(FlagFunder)


shouldn't this be the from address?

Ugh - we've got some ugly choices here and I'd appreciate a better suggestion. At clawback time, we're transferring funds from the vesting account to a destination account, based on a message signed by the funder who was the "from" address when the account was created. So at clawback time, "from" is dangerously ambiguous. My proposed solution here is that at clawback time we say "funder" to avoid ambiguity, but at creation time we say "from" for consistency with the other commands to create vesting accounts.

Tbh I think maintaining from is totally OK since this is the CLI (this will remove additional flags) and I'd expect users to use gRPC (which can use the funder name)

Turns out to be necessary to get the cli tests to work - at least without more poking into it. Done.

fedekunze · 2022-01-17T13:13:00Z

x/staking/keeper/delegation.go

+	// keeping a liability for 25 shares and transferring one for 75 shares.
+	// Of course, the redelegations themselves can have multiple entries for
+	// different timestamps, so we're actually working at a finer granularity.
+	redelegations := k.GetRedelegations(ctx, fromAddr, math.MaxUint16)


ditto use iterator

It looks like you break the contract if you modify the section of the store you're iterating over. See comment on Iterator() method of KVStore in store/types/store.go.

fedekunze · 2022-01-17T13:14:33Z

x/distribution/keeper/delegation.go

+// SmartRewardAccount is an account with a post-reward processing function.
+// Such an account ignores a non-default withdrawal address, as this can
+// be implemented in the post-reward processing if desired.
+type SmartRewardAccount interface {


why not introduce Distribution Hooks instead of a new account?

fedekunze · 2022-01-17T13:16:02Z

x/distribution/keeper/delegation.go

 		err := k.bankKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, withdrawAddr, coins)
 		if err != nil {
 			return nil, err
 		}
+		if isSmart {
+			smartAcc.PostReward(ctx, coins, k.authKeeper, k.bankKeeper, k.stakingKeeper)


I think this should be an AfterWithdrawRewards hook.

We also need to prevent the use of a different withdrawAddr when we're dealing with a vesting account with clawback. I could have another hook method, AllowWithdrawAddr(acc authtypes.AccountI) bool - although this is odd, since there are no other hook methods that return a value or affect execution of the calling module.

Vesting accounts themselves are precedent for having modules modify their behavior based on account type - in its interaction with the x/bank module. However, I'm not sure if that's a good precedent to follow.

So I could use the following odd hook interface. I'm not sure if the resulting code is any simpler or more idiomatic:

type interface DistributionHook { AllowWithdrawAddr(acc authtypes.AccountI) bool AfterReward(ctx sdk.Context, acc authTypes.AccountI, reward sdk.Coins) }

Or I could keep this as-is. Let me know which you'd prefer.

(BTW, why don't the hook-calling modules allow for an arbitrary number of registered hooks? It doesn't seem any harder.)

type StakingKeeper struct { ... hooks []types.StakingHooks ... } func (k Keeper) BeforeFoo(ctx sdk.Context, addr sdk.AccAddress, foo types.Whatever) { for _, hook := range k.hooks { hook.BeforeFoo(ctx, addr, foo) } }

Okay, so I implemented distribution hooks as I described. It was a little tricky getting the wiring correct to tie it all together, but now it's more general, and I think we'll have some other uses for it.

fedekunze · 2022-01-17T13:19:50Z

x/auth/vesting/types/vesting_account.go

+	unbondings := sk.GetUnbondingDelegations(ctx, tva.GetAddress(), math.MaxUint16)
+	for _, unbonding := range unbondings {
+		for _, entry := range unbonding.Entries {
+			unbonded = unbonded.Add(entry.Balance)


shouldn't this be unbonding?

Yes, it should, thanks. I'll expand the test coverage for this.

fedekunze · 2022-01-17T13:20:24Z

x/auth/vesting/types/vesting_account.go

+		tokens := validator.TokensFromSharesTruncated(shares).RoundInt()
+		bonded = bonded.Add(tokens)
+	}
+	return


nit, the return values should be explicit

…ount

Fixes issue Agoric/agoric-sdk#4300

Make sure we can merge with an empty vesting schedule.

JimLarson added the enhancement New feature or request label Jan 10, 2022

JimLarson requested review from zmanian and michaelfig January 10, 2022 19:47

JimLarson self-assigned this Jan 10, 2022

github-actions bot added C:x/auth C:x/distribution C:x/staking labels Jan 10, 2022

michaelfig reviewed Jan 10, 2022

View reviewed changes

docs/core/proto-docs.md Show resolved Hide resolved

proto/cosmos/vesting/v1beta1/tx.proto Outdated Show resolved Hide resolved

x/auth/vesting/client/cli/tx.go Outdated Show resolved Hide resolved

michaelfig reviewed Jan 10, 2022

View reviewed changes

JimLarson marked this pull request as ready for review January 11, 2022 03:52

michaelfig force-pushed the 4085-true-vesting branch from 78e08a6 to 6085859 Compare January 15, 2022 01:21

github-actions bot added C:x/bank Type: Build Type: CI labels Jan 15, 2022

michaelfig changed the base branch from Agoric to Agoric-ag0 January 15, 2022 01:22

liamsi mentioned this pull request Jan 15, 2022

Add claw back to vesting module cosmos/cosmos-sdk#10493

Closed

4 tasks

michaelfig force-pushed the 4085-true-vesting branch from 6085859 to 79575b7 Compare January 15, 2022 01:39

github-actions bot removed Type: Build C:x/bank Type: CI labels Jan 15, 2022

zmanian reviewed Jan 17, 2022

View reviewed changes

zmanian approved these changes Jan 17, 2022

View reviewed changes

fedekunze reviewed Jan 17, 2022

View reviewed changes

michaelfig changed the base branch from Agoric-ag0 to Agoric-ag0.true-vesting-base January 17, 2022 19:37

michaelfig marked this pull request as draft January 17, 2022 19:38

michaelfig mentioned this pull request Jan 17, 2022

feat: land clawback vesting on Agoric-ag0 #158

Merged

19 tasks

JimLarson mentioned this pull request Jan 17, 2022

Docs: clarify vesting terminology as time lock escrow + distinguish between common legal vesting terminology cosmos/cosmos-sdk#10662

Closed

4 tasks

JimLarson added 14 commits February 14, 2022 16:37

test: cli tests for clawback vesting

4eba401

refactor: rename TrueVestingAccount and friends to ClawbackVestingAcc…

d0984e6

…ount

docs: update vesting spec for clawback accounts

df1b978

fix: correctly handle post-clawback residual lockup after slashing

ef4e214

test: expand tests, test clawback

d209430

refactor: remove 'combined_periods' fields and compute dynamically

6daaf16

fix: clawback after slash fix, refactor test helper

34a57a8

fix: factor out reward when computing reward vesting

948ed4d

refactor: put additional grant merge logic in vesting accounts

bc4dfe5

fix: reset delegation bookkeeping when adding new grants

9c88b58

Fixes issue Agoric/agoric-sdk#4300

fix: remember slashed amount when adding vesting grant

3d87b6b

test: corner case for add grant after full slash

81aa5de

Make sure we can merge with an empty vesting schedule.

refactor: provide staking routines for bonded and unbonding balances

d706abb

test: improve coverage, fix some test bugs

1718229

JimLarson force-pushed the 4085-true-vesting branch from c350738 to 1718229 Compare February 15, 2022 00:39

github-actions bot added C:CLI C:x/bank C:x/genutil C:x/params Type: Build Type: CI labels Feb 15, 2022

JimLarson changed the base branch from Agoric-ag0.true-vesting-base to Agoric February 15, 2022 00:41

JimLarson merged commit 6c7f9c0 into Agoric Feb 15, 2022

JimLarson mentioned this pull request Feb 16, 2022

Upstream x/staking changes for transfer of locked tokens Agoric/agoric-sdk#4569

Open

JimLarson mentioned this pull request Mar 2, 2022

feat: final clawback changes #183

Merged

liamsi mentioned this pull request Apr 9, 2022

feature: add real vesting module celestiaorg/celestia-app#280

Closed

JimLarson deleted the 4085-true-vesting branch April 20, 2022 02:38

dwedul-figure mentioned this pull request Jun 16, 2022

Research vesting options. provenance-io/provenance#876

Closed

4 tasks

dwedul-figure mentioned this pull request Jul 11, 2022

Enhance vesting accounts. provenance-io/provenance#916

Closed

4 tasks

SpicyLemon mentioned this pull request Jul 18, 2022

Vesting accounts: Add clawback provenance-io/provenance#944

Open

4 tasks

		string from_address = 1 [(gogoproto.moretags) = "yaml:\"from_address\""];
		string to_address = 2 [(gogoproto.moretags) = "yaml:\"to_address\""];

feat: implement true vesting accounts with clawback #155

feat: implement true vesting accounts with clawback #155

Conversation

JimLarson commented Jan 10, 2022

Description

Author Checklist

Reviewers Checklist

michaelfig left a comment

Choose a reason for hiding this comment

michaelfig left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JimLarson commented Jan 11, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zmanian left a comment

Choose a reason for hiding this comment

fedekunze left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liamsi Jan 17, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liamsi Jan 17, 2022 •

edited

Loading