Docs: clarify vesting terminology as time lock escrow + distinguish between common legal vesting terminology

[hxrts]

Summary

Legal vesting has a specific meaning that does not map to how "vesting accounts" are currently implemented.

Problem Definition

This terminological confusion has tripped up many entities with whom the ICF has interacted.

Proposal

Change all instances of "vesting accounts" to "locked accounts" or similar.

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[tac0turtle]

Can you explain what parts have tripped up people? We already stray from normal vesting nomenclature, but vesting is a common term within this space.

Id prefer to bring the current vesting design within scope of the needs instead of changing the name as it will greatly confuse the ecosystem.

[robert-zaremba]

If we do it in the code as well, then this is a breaking change, and we should do it together with: #9958

[tac0turtle]

If we do it in the code as well, then this is a breaking change, and we should do it together with: #9958

I'm quite opposed to unneeded breaking changes. Users already complain about this, let's first understand the problem/

[robert-zaremba]

Well, we want to move vesting out of auth anyway - there are other problems related to that.

[tac0turtle]

Well, we want to move vesting out of auth anyway - there are other problems related to that.

def fine with this change since it enables more things, but renaming the module should be done after we understand the problem.

[tac0turtle]

@hxrts could you define what the problem you are running into?

[hxrts]

Vesting is the delivery of payment contingent on some behaviour (i.e. staying at a company for X years). When we write ICF contracts that use "vesting" in the SDK we always need to clarify that this is unlike legal vesting in that delivery is guaranteed. The SDK's notion of vesting is actually a timelock escrow.

[tac0turtle]

Vesting is the delivery of payment contingent on some behaviour (i.e. staying at a company for X years). When we write ICF contracts that use "vesting" in the SDK we always need to clarify that this is unlike legal vesting in that delivery is guaranteed. The SDK's notion of vesting is actually a timelock escrow.

Vesting is intended to be used in both cases, we don't have functionality to claw back the tokens but there is an issue for this. I know teams using it as vesting accounts for contributors that stay x amount of years at the project and also different reasons.

I'm still not a fan of causing an ecosystem rename/breaking change like this in light of our users complaining about how we are doing many breaking changes.

[hxrts]

At the very least we should provide further clarification in the docs.

[tac0turtle]

yea, happy to change docs. Want to edit the issue with a focus on docs and we can add labels to get help on it

[hxrts]

Cool done

[JimLarson]

FYI, Agoric is implementing a variant of PeriodicVestingAccount that has separate schedules for vesting (subject to clawback) and unlocking (not subject to clawback), with a clawback operation where the funder to order the transfer of all unvested funds to another account.

The name of the account type is TBD, but probably ClawbackVestingAccount.

Issue: Agoric/agoric-sdk#4085

[alexanderbez]

@JimLarson clawback functionality would be amazing. Is this work complete? Can I see the code?

[JimLarson]

@alexanderbez Sure! The PR is in development, but we're trying to get it merged into our fork this week-ish. See agoric-labs#155

Don't be dissuaded by the "draft" status - we're doing some branch and PR shennanigans. Go ahead and comment.

The documentation is a little sparse at the moment - refer back to the design notes in Agoric/agoric-sdk#4085

Related issues: #9959, #10493

[tac0turtle]

we are renaming vesting to lockup in the new accounts module. The term vesting shouldnt be present in the next release

[tac0turtle]

the new vesting accounts were named lockup to avoid this confusion