From 549fec93354afba593487660832ee045a83f4e27 Mon Sep 17 00:00:00 2001 From: Jim Larson Date: Mon, 18 Sep 2023 22:38:44 -0700 Subject: [PATCH] docs: review feedback --- x/auth/vesting/cmd/vestcalc/README.md | 39 +++++++++++++++++++------ x/auth/vesting/cmd/vestcalc/vestcalc.go | 4 +-- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/x/auth/vesting/cmd/vestcalc/README.md b/x/auth/vesting/cmd/vestcalc/README.md index f766e4248847..a445a7b4a88c 100644 --- a/x/auth/vesting/cmd/vestcalc/README.md +++ b/x/auth/vesting/cmd/vestcalc/README.md @@ -30,26 +30,47 @@ Run `go install` in this directory, which will create or update the [documentation](https://pkg.go.dev/cmd/go) for the `go` command-line tool for other options. -## Writing a schedule +## Schedule format -When the `--write` flag is set, the tool will write a schedule to stdout. -The format is the the format expected by the `create-periodic-vesting-account` +Schedules are expressed in the format expected by the `create-periodic-vesting-account` or `create-clawback-vesting-account` cli commands, namely a JSON object with the members: - `"start_time"`: integer UNIX time; -- `"periods"`: a JSON array of JSON objects with members: - - "coins": string giving the text coins format for the amount vested at this event; +- `"periods"`: an array of objects describing vesting events with members: + - "coins": string giving the text coins format for the additional amount vested by this event; - "length_seconds": positive integer seconds from the last vesting event, or from the start time for the first vesting event. +For instance: + +``` +{ + "start_time": 1700000000, + "periods": [ + { + "coins": "10000000uatom,500000000ubld", + "length_seconds": 2678400 + }, + { + "coins": "500000000ubld", + "length_seconds": 31536000 + } + ] +} + +``` + +## Writing a schedule + +When the `--write` flag is set, the tool will write a schedule to stdout. The following flags control the output: - `--coins:` The total coins to vest, e.g. `100ubld,50urun`. -- `--months`: The number of monthly to vesting events. +- `--months`: The total number of months to complete vesting. - `--start`: The vesting start time: i.e. the first event happens in the next month. Specified in the format `YYYY-MM-DD` or `YYYY-MM-DDThh:mm`, e.g. `2006-01-02T15:04` for 3:04pm on January 2, 2006. -- `--time`: The time of day of the vesting events, in 24-hour HH:MM format. +- `--time`: The time of day (in the local timezone) of the vesting events, in 24-hour HH:MM format. Defaults to midnight. - `--cliffs`: Vesting cliffs in `YYYY-MM-DD` or `YYYY-MM-DDThh:mm` format. Only the latest one will have any effect, but it is useful to let @@ -60,12 +81,12 @@ The vesting events will occur each month following the start time on the same day of the month (or the last day of the month, if the month does not have a sufficient number of days), for the specified number of months. The total coins to vest will be divided as evenly as possible among all the vesting events. -Lastly, all events before the last cliff time, if any, are consolidated into a single even +Lastly, all events before the last cliff time, if any, are consolidated into a single event at the last cliff time with the sum of the event amounts. ## Reading a schedule -When the `--read` flag is set, the tool will read a schedule in JSON from +When the `--read` flag is set, the tool will read a schedule from stdin and write the vesting events in absolute time to stdout. ## Examples diff --git a/x/auth/vesting/cmd/vestcalc/vestcalc.go b/x/auth/vesting/cmd/vestcalc/vestcalc.go index 3f639b28605e..b6eedb4b7f7e 100644 --- a/x/auth/vesting/cmd/vestcalc/vestcalc.go +++ b/x/auth/vesting/cmd/vestcalc/vestcalc.go @@ -13,7 +13,7 @@ import ( "github.com/cosmos/cosmos-sdk/x/auth/vesting/client/cli" ) -// vestcalc is a utility for creating or reading period files +// vestcalc is a utility for creating or reading schedule files // for use in some vesting account types. See README.md for usage. // divide returns the division of total as evenly as possible. @@ -98,7 +98,7 @@ func divideCoins(coins sdk.Coins, divisor int) ([]sdk.Coins, error) { // monthlyVestTimes generates timestamps for successive months after startTime. // The monthly events occur at the given time of day. If the month is not // long enough for the desired date, the last day of the month is used. -// The number of months must be postive. +// The number of months must be positive. func monthlyVestTimes(startTime time.Time, months int, timeOfDay time.Time) ([]time.Time, error) { if months < 1 { return nil, fmt.Errorf("must have at least one vesting period")