@agoric/cosmos 0.35.0-upgrade-14-dev-c8f9e7b.0 → 0.35.0-upgrade-16a-dev-fb592e4.0

package/x/lien/spec/01_concepts.md

@@ -1,146 +0,0 @@
-<!--
-order: 1
--->
-
-# Concepts
-
-## Notes on Terminology
-
-* "Bonded", "delegated", and "staked" are all synonyms.
-* "Unlocking" is a time-delayed process by which tokens become available for
-  withdrawal. "Vesting" is a time-delayed process where tokens change
-  ownership, and is subject to "clawback" which stops the process. The
-  cosmos-sdk implements several kinds of "vesting account" which implement
-  unlocking, and only one - clawback accounts - which implement vesting.
-
-## Account Balances
-
-The existing dynamic of account balances work in two dimensions: bonding
-and locking.
-
-### The Bonding Dimension
-
-In the bonding dimension, the balance of the staking token owned by an account
-is partitioned into three categories:
-
-* "Bonded": tokens that are currently staked with a validator.
-* "Unbonding": tokens that are held in escrow after being bonded and subject
-  to slashing if validator misbehavior is discovered after the fact.
-* "Unbonded": tokens that are not bonded and unencumbered by any slashing
-  liability. These are the only tokens that are shown in the account balance
-  in the `x/bank` module.
-
-### The Locking Dimension
-
-In the locking dimension, the balance of tokens owned by an account is
-partitioned into two categories:
-
-* "Locked" (aka "vesting" or "unvested"): tokens which may not yet be
-  transfered out of the account.
-* "Unlocked" (aka "vested"): tokens which may be freely transferred
-  out of the account.
-
-The sum of these two categories must be equal to the sum of the three
-categories in the bonding dimension.
-
-### The Vesting (Clawback) Dimension
-
-The vesting dimension is similar to the locking dimension in that
-unvested tokens are encumbered and many not be transferred out of the
-account, but further, unvested tokens are subject to clawback.
-Be careful to distinguish the legacy use of "vesting" to mean locking
-and the clawback-aware notion of vesting.
-
-* "Unvested" (aka "vesting): tokens which may not yet be transferred
-  out of the account, and are subject to clawback.
-* "Vested":  tokens which may be freely transferred and are not
-  subject to clawback.
-
-### No Cartesian Product
-
-Surprisingly, tokens are *not* tracked by the cartesian product of the
-dimensions, i.e. the system does not track whether the tokens staked to
-a particular validator are locked or unlocked. Instead, when trying to
-transfer tokens out of an account, it checks separately whether enough
-unbonded tokens are available, and whether enough unlocked tokens are
-available, and deducts the transferred amount from both of those
-categories.
-
-Slashed tokens are taken out of the locked category until it is depleted,
-and then from the unlocked category.
-
-## Introducing Liens
-
-Liens are an encumbrance on tokens that prevent them from being transferred
-out of the account, much like locking (and liens are implemented by reusing
-the locking/vesting mechanisms).  Liens live in the vesting dimension,
-as tokens may be orthogonally locked, but must be vested in order to
-be liened. The categories in the vesting dimension are now:
-
-* "Unvested": tokens which may not be transferred and are subject to clawback.
-* "Liened": vested tokens encumbered by a lien which may not be transferred.
-* "Free": the remainder of tokens in an account which are neither
-  encumbered nor subject to clawback.
-
-Liens are imposed and lifted by the higher Agoric swingset layer.
-We intend liens to be placed on bonded, vested tokens only. However,
-we cannot force tokens to remain bonded, as they may be involuntarily
-unbonded when a validator retires. The best we can do is that when
-the higher layers wish to increase the total liened amount, the new
-total must be less than the bonded tokens and less than the unlocked
-tokens.  Liens can be lifted at any time.
-
-The liened amount is *not* reduced by slashing, and if slashing reduces
-the account balance below the liened amount, the account effectively has
-negative equity.  We'll model this by allowing the Unliened amount to
-be negative.
-
-## Representing Account State
-
-Putting all three dimensions together, the account state is:
-
-* Bonding Dimension:
-    * Bonded
-    * Unbonding
-    * Unbonded
-* Locking Dimension:
-    * Locked
-    * Unlocked
-* Lien Dimension:
-    * Unvested
-    * Liened
-    * Unliened (may be negative)
-
-with the constraint that the sum of categories in each dimension must be
-the same. We can represent this without the constraints with the following
-primary quantities:
-
-* Total: total amount in the account
-* Bonded
-* Unbonding
-* Locked
-* Liened
-* Unvested
-
-which gives rise to the derived quantities:
-
-* Unbonded = Total - (Bonded + Unbonding)
-* Unlocked = Total - Locked
-* Free = Total - Unvested - Liened (may be negative)
-
-## Implementing Lien Encumbrance
-
-Liened tokens may not be transferred out of an account. Rather than
-modifying the `x/bank` module to implement a new type of containment,
-we leverage the existing mechanism to prevent locked tokens from being
-transferred.
-
-To do this, we create a new type of vesting \[*sic*\] account which wraps
-an existing account where the liened tokens are considered locked. If
-the existing account is already a vesting account, the wrapper locks the
-maximum of the liened and locked amounts.
-
-To effect this wrapping of accounts, a different wrapper is placed around
-an `AccountKeeper` which intercepts `GetAccount()` and `SetAccount()` calls
-which read and write the account from the store. This way no change is
-needed in the persisted representation of accounts.

package/x/lien/spec/02_messages.md

@@ -1,96 +0,0 @@
-<!--
-order: 2
--->
-
-# Messages
-
-This documents the messages sent across the bridge to the Javascript swingset.
-
-## From Javascript to Golang
-
-### LIEN_CHANGE_LIENED
-
-Request: JSON object with the fields
-
-* type: "LIEN_CHANGE_LIENED"
-* address: string, bech32-encoded
-* denom: string
-* delta: string encoding integer of change to liened amount
-
-Response: JSON string encoding nonnegative integer holding the current lien amount.
-
-The following rules are used:
-
-* The total liened amount can always be decreased.
-* When increasing the total liened amount, the new total liened plus unvested
-  must be less than or equal to the bonded amount.
-* Can be used to change from zero balance or to zero balance.
-
-### LIEN_GET_ACCOUNT_STATE
-
-Request: JSON object with the fields
-
-* type: "LIEN_GET_ACCOUNT_STATE"
-* address: string, bech32-encoded
-* denom: string
-
-Response: JSON object with the fields
-
-* currentTime: string timestamp
-* total: string encoding nonnegativeinteger
-* bonded: string encoding nonnegative integer
-* unbonding: string encoding nonnegative integer
-* locked: string encoding nonnegative integer
-* liened: string encoding nonnegative integer
-
-See [Concepts](01_concepts.md) for the meaning of the amounts.
-
-### LIEN_GET_STAKING
-
-Request: JSON object with the fields
-
-* type: "LIEN_GET_STAKING"
-* validators: array of strings of bech32-encoded operator addresses
-* delegators: array of strings of bech32-encoded account addresses
-
-Response: JSON object with the fields
-
-* epoch_tag: string encoding the staking epoch.
-If it is the same in two different responses, the results can be
-safely aggregated.
-* denom: string giving the name of the staking token
-* validator_values: array of the same length as the request `validators`,
-where each entry is a string encoding nonnegative integer
-giving the tokens delegated to the corresponding validator, or `null`
-if that validator address is malformed.
-* delegator_states: array of the same length as the request `delegators`,
-holding `null` if the address is malformed, otherwise an object containing:
-    * val_idx: array of nonnegative integers referring to the index of
-    a validator in the request. If the same validator address is
-    given multiple times in the request, the index of the last one is used.
-    * values: array of strings of the same size as `val_idx` encoding
-    nonnegative integers for the amount this delegator has delegated
-    to the referenced validator.
-    * other: string encoding nonnegative integer of the total amount
-    this delegator has delegated to validators not mentioned in the request.
-
-This call obtains a partial snapshot of staking data in a compact
-representation. It is intended for use in tallying votes of delegated tokens,
-with proxying of votes based on delegation. It has nothing to do with liens
-per se, but the lien module has the necessary connectivity to implement it.
-This call may be moved to another module in the future if appropriate.
-
-## From Golang to Javascript
-
-None.
-
-## Design Notes
-
-The LIEN_SET_TOTAL operation checks the Golang-side state and might reject
-the operation. It has the power to do so to avoid a race between checking
-the account state and updating the liened amount, vs other cosmos-sdk
-operations which might change the account state. The cosmos-side lien amount
-is the source of truth for the lien.
-
-The LIEN_GET_STAKING call is categorized as a lien operation onlyb because
-of the similarity to LIEN_GET_ACCOUNT_STATE.

package/x/lien/types/accountkeeper.go

@@ -1,81 +0,0 @@
-package types
-
-import (
-	sdk "github.com/cosmos/cosmos-sdk/types"
-	authkeeper "github.com/cosmos/cosmos-sdk/x/auth/keeper"
-	authtypes "github.com/cosmos/cosmos-sdk/x/auth/types"
-)
-
-// AccountWrapper wraps/unwraps accounts.
-// The Wrap and Unwrap functions map accounts to accounts.
-type AccountWrapper struct {
-	Wrap   func(sdk.Context, authtypes.AccountI) authtypes.AccountI
-	Unwrap func(sdk.Context, authtypes.AccountI) authtypes.AccountI
-}
-
-// identWrap is an identity mapping of accounts.
-func identWrap(_ sdk.Context, a authtypes.AccountI) authtypes.AccountI {
-	return a
-}
-
-// DefaultAccountWrapper is an AccountWrapper that does nothing.
-var DefaultAccountWrapper = AccountWrapper{
-	Wrap:   identWrap,
-	Unwrap: identWrap,
-}
-
-// WrappedAccountKeeper wraps an account AccountKeeper transform accounts
-// when reading or writing accounts from/to storage.
-// Applies the Wrap function when reading accounts from the store and applies
-// the Unwrap function when writing them to the store.
-//
-// Note that we do not wrap the Accounts() method since the returned accounts
-// are serialized and sent in the GRPC response and we don't need to modify
-// their behavior.
-type WrappedAccountKeeper struct {
-	authkeeper.AccountKeeper
-	AccountWrapper
-}
-
-var _ authkeeper.AccountKeeper = (*WrappedAccountKeeper)(nil)
-
-// NewWrappedAccountKeeper returns a WrappedAccountKeeper with the default (identity) wrapper.
-func NewWrappedAccountKeeper(ak authkeeper.AccountKeeper) *WrappedAccountKeeper {
-	return &WrappedAccountKeeper{
-		AccountKeeper:  ak,
-		AccountWrapper: DefaultAccountWrapper,
-	}
-}
-
-// GetAccount implements AccountKeeper.GetAccount().
-// It calls the embedded AccountKeeper then Wraps the account.
-func (wak *WrappedAccountKeeper) GetAccount(ctx sdk.Context, address sdk.AccAddress) authtypes.AccountI {
-	acc := wak.AccountKeeper.GetAccount(ctx, address)
-	if acc == nil {
-		return nil
-	}
-	return wak.Wrap(ctx, acc)
-}
-
-// IterateAccounts implements AccountKeeper.IterateAccounts().
-// It calls the embedded AccountKeeper but Wraps the retrieved accounts.
-func (wak *WrappedAccountKeeper) IterateAccounts(ctx sdk.Context, cb func(account authtypes.AccountI) (stop bool)) {
-	wak.AccountKeeper.IterateAccounts(ctx, func(acc authtypes.AccountI) (stop bool) {
-		return cb(wak.Wrap(ctx, acc))
-	})
-}
-
-// SetAccount implements AccountKeeper.SetAccount().
-// It Unwraps the account then calls the embedded AccountKeeper.
-func (wak *WrappedAccountKeeper) SetAccount(ctx sdk.Context, acc authtypes.AccountI) {
-	unwrappedAcc := wak.Unwrap(ctx, acc)
-	wak.AccountKeeper.SetAccount(ctx, unwrappedAcc)
-}
-
-// SetWrapper updates the AccountWrapper.
-// We need to modify the wrapper after it's created for the planned use,
-// since there is a circular dependency in the creation of the WrappedAccountKeeper
-// and the lien.Keeper.
-func (wak *WrappedAccountKeeper) SetWrapper(aw AccountWrapper) {
-	wak.AccountWrapper = aw
-}

package/x/lien/types/accountstate.go

@@ -1,27 +0,0 @@
-package types
-
-import (
-	sdk "github.com/cosmos/cosmos-sdk/types"
-)
-
-// AccountState represents the abstract state of an account.
-// See ../spec/01_concepts.md for details.
-type AccountState struct {
-	Total     sdk.Coins `json:"total"`
-	Bonded    sdk.Coins `json:"bonded"`
-	Unbonding sdk.Coins `json:"unbonding"`
-	Locked    sdk.Coins `json:"locked"`
-	Liened    sdk.Coins `json:"liened"`
-	Unvested  sdk.Coins `json:"unvested"`
-}
-
-// IsEqual returns whether two AccountStates are equal.
-// (Coins don't play nicely with equality (==) or reflect.DeepEqual().)
-func (s AccountState) IsEqual(other AccountState) bool {
-	return s.Total.IsEqual(other.Total) &&
-		s.Bonded.IsEqual(other.Bonded) &&
-		s.Unbonding.IsEqual(other.Unbonding) &&
-		s.Locked.IsEqual(other.Locked) &&
-		s.Liened.IsEqual(other.Liened) &&
-		s.Unvested.IsEqual(other.Unvested)
-}

package/x/lien/types/expected_keepers.go

@@ -1,18 +0,0 @@
-package types
-
-import (
-	sdk "github.com/cosmos/cosmos-sdk/types"
-	stakingTypes "github.com/cosmos/cosmos-sdk/x/staking/types"
-)
-
-type BankKeeper interface {
-	GetAllBalances(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
-	GetBalance(ctx sdk.Context, addr sdk.AccAddress, denom string) sdk.Coin
-}
-
-type StakingKeeper interface {
-	BondDenom(ctx sdk.Context) string
-	GetDelegatorDelegations(ctx sdk.Context, delegator sdk.AccAddress, maxRetrieve uint16) []stakingTypes.Delegation
-	GetUnbondingDelegations(ctx sdk.Context, delegator sdk.AccAddress, maxRetrieve uint16) []stakingTypes.UnbondingDelegation
-	GetValidator(ctx sdk.Context, addr sdk.ValAddress) (stakingTypes.Validator, bool)
-}