vbank

package
v0.0.0-...-f0ccde6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 24, 2025 License: Apache-2.0 Imports: 21 Imported by: 0

README

Virtual Bank

This module manages the integration between the Cosmos x/bank module and the VM.

"Bank purses" connect Cosmos-level bank module accounts with Agoric-level ERTP purses and payments. A "bank purse" is created at the ERTP level which be observed and manipulated as other purses, but modifications to it are sent over the bridge to act upon the bank account. Updates to the bank account balance are sent over the bridge to update the bank purse, whose balance can be queried entirely at the ERTP level.

Parameters

  • feeCollectorName: the module which handles fee distribution to stakers.
  • reward_epoch_duration_blocks: the duration (in blocks) over which fees should be given to the fee collector.
  • per_epoch_reward_fraction: a decimal of how much of the GiveawayPool is paid as validator rewards per epoch
  • allowed_monitoring_accounts: an array of account addresses that can be monitored for sends and receives, defaulting to [authtypes.NewModuleAddress(types.ProvisionPoolName)]. An element of "*" will permit any address.

State

The Vbank module maintains no significant state, but will access stored state through the bank module.

Protocol

Purse operations which change the balance result in a downcall to this module to update the underlying account. A downcall is also made to query the account balance.

Upon an EndBlock() call, the module will scan the block for all MsgSend and MsgMultiSend events (see cosmos-sdk/x/bank/spec/04_events.md) and perform a VBANK_BALANCE_UPDATE upcall for all denominations held in only in the allowed_monitoring_accounts.

The following fields are common to the Vbank messages:

  • "address", "recipient", "sender": account address as a bech32-encoded string
  • "amount": either amount to transfer or account balance, as an integer string
  • "denom": denomination as a string
  • "nonce": unique integer, as a number
  • "type": string of the type of message (enumerated below)
  • "updated": list of objects with the fields "address", "denom", "amount".

Downcalls from JS to Cosmos (by type):

  • VBANK_GET_BALANCE (type, address, denom): gets the account balance in the given denomination from the bank. Returns the amount as a string.
  • VBANK_GIVE (type, recipeient, denom, amount): adds amount of denomination to account balance to reflect a deposit to the virtual purse. Returns a VBANK_BALANCE_UPDATE message restricted to the recipient account and denomination.
  • VBANK_GIVE_TO_FEE_COLLECTOR (type, denom, amount): stores rewards which will be gradually sent to the fee collector
  • VBANK_GRAB (type, sender, denom, amount): burns amount of denomination from account balance to reflect withdrawal from virtual purse. Returns a VBANK_BALANCE_UPDATE message restricted to the sender account and denomination.

Upcalls from Cosmos to JS: (by type)

  • VBANK_BALANCE_UPDATE (type, nonce, updated): inform virtual purse of change to the account balance (including a change initiated by VBANK_GRAB or VBANK_GIVE).

Testing

Test the following transfer scenarios:

  • Purse-to-bank-purse
  • bank-purse-to-purse
  • bank-purse-to-bank-purse

The initial BLD and IST purses are bank purses, but newly-created purses will not be bank purses by default.

Governance

To use Cosmos governance to change the reward_epoch_duration_blocks value:

$ agd query vbank params
reward_epoch_duration_blocks: "720"
$ cat <<EOF > epoch-duration-proposal.json
{
  "title": "Vbank param-change test",
  "description": "Decrease the fee disbursal epoch parameter to 30 blocks.",
  "changes": [
    {
      "subspace": "vbank",
      "key": "reward_epoch_duration_blocks",
      "value": "30"
    }
  ],
  "deposit": "1000000ubld"
}
EOF
$ agd tx gov submit-proposal param-change epoch-duration-proposal.json --from=mykey --chain-id=agoric
# Then vote on the proposal.
$ agd tx vote ...
# After passing,
$ agd query vbank params
reward_epoch_duration_blocks: "30"
$

Documentation

Index

Constants

View Source 
const (
	ModuleName = types.ModuleName
	RouterKey  = types.RouterKey
	StoreKey   = types.StoreKey
)

Variables

View Source 
var (
	NewKeeper     = keeper.NewKeeper
	ModuleCdc     = types.ModuleCdc
	RegisterCodec = types.RegisterCodec
)

Functions

func DefaultGenesisState 

func DefaultGenesisState() *types.GenesisState

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, k Keeper) *types.GenesisState

func InitGenesis 

func InitGenesis(ctx sdk.Context, keeper Keeper, data *types.GenesisState) []abci.ValidatorUpdate

func NewGenesisState 

func NewGenesisState() *types.GenesisState

func NewHandler 

func NewHandler(keeper Keeper) sdk.Handler

NewHandler returns a handler for "vbank" type messages.

func NewPortHandler 

func NewPortHandler(am AppModule, keeper Keeper) portHandler

func ValidateGenesis 

func ValidateGenesis(data *types.GenesisState) error

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

func NewAppModule 

func NewAppModule(k Keeper) AppModule

NewAppModule creates a new AppModule Object

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock)

BeginBlock implements the AppModule interface

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

func (AppModule) EndBlock 

func (am AppModule) EndBlock(ctx sdk.Context, req abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock implements the AppModule interface

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the exported genesis state as raw bytes for the ibc-transfer module.

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, data json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs genesis initialization for the ibc-transfer module. It returns no validator updates.

func (AppModule) LegacyQuerierHandler 

func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler implements the AppModule interface

func (AppModule) Name 

func (AppModule) Name() string

func (AppModule) PushAction 

func (am AppModule) PushAction(ctx sdk.Context, action vm.Action) error

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute implements the AppModule interface

func (AppModule) RegisterInvariants 

func (AppModule) RegisterInvariants(ir sdk.InvariantRegistry)

RegisterInvariants implements the AppModule interface

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers module services.

func (AppModule) Route 

func (am AppModule) Route() sdk.Route

Route implements the AppModule interface

type AppModuleBasic 

type AppModuleBasic struct {
}

app module Basics object

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the deployment

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd implements AppModuleBasic interface

func (AppModuleBasic) GetTxCmd 

func (AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd implements AppModuleBasic interface

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

func (AppModuleBasic) RegisterInterfaces 

func (b AppModuleBasic) RegisterInterfaces(registry cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

Validation check of the Genesis

type Keeper 

type Keeper = keeper.Keeper

type VbankBalanceUpdate 

type VbankBalanceUpdate struct {
	*vm.ActionHeader `actionType:"VBANK_BALANCE_UPDATE"`
	Nonce            uint64                  `json:"nonce"`
	Updated          vbankManyBalanceUpdates `json:"updated"`
}

type VbankSingleBalanceUpdate 

type VbankSingleBalanceUpdate struct {
	Address string `json:"address"`
	Denom   string `json:"denom"`
	Amount  string `json:"amount"`
}

Source Files

View all Source files

Directories

Path Synopsis
client
cli
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.