Venus: Command names for deals and vouchers

[mishmosh]

Description

There is an emerging need for several new commands having to do with deals and deal payment vouchers. @acruikshank points out that the long hyphenated names aren't great. Current naming also lacks consistency.

There's a story in-flight to add go-filecoin miner list-deals. We currently have a go-filecoin show deal. We're going to need something like go-filecoin miner list-deal-vouchers go-filecoin show deal-voucher and go-filecoin miner redeem-deal-voucher. These long hyphenated names aren't great, and they also muddy the waters between client and miner commands.

This is currently a discussion issue, open for comment or suggestion.

Current or proposed commands:

• go-filecoin show deal
• go-filecoin miner list-deal-vouchers
• go-filecoin show deal-voucher
• go-filecoin miner redeem deal-voucher

Acceptance criteria

The solution(s) need to:

• Use show and list consistently. For example, we could agree on show for details of a single item, list for full list of all of that item.
• Consistent use of miner or not as top-level command. We should use it when ____; we don't need it when ____.
• Use plain language, and be easy to spell and type.

Risks + pitfalls

Where to begin

[rosalinekarr]

I think top level subcommands should be categorizations for easier navigation by the user, and things like show or list should be subcommands of those. So, for example, deals and vouchers should each have their own commands like this:

go-filecoin deals show
go-filecoin deals list
go-filecoin deals accept
go-filecoin deals cancel
...

go-filecoin vouchers show
go-filecoin vouchers list
go-filecoin vouchers redeem
...

I also think we should do our best to keep these nestings flat, like what's advised for routes in web applications. i.e. go-filecoin deals vouchers list is bad because a voucher is a separate object that, while connected and related to deals, can be dealt with independently of it's parent deal.

[rosalinekarr]

Also, I've noticed we have some inconsistency when it some to ls vs list and show vs cat. I don't have a strong preference either way, but we should definitely pick one pattern and stick with it.

[eshon]

@rosalinekarr's flat structure makes sense.

How about no plurals? If commands only use the singular 'deal' this reduces having to guess singular vs plural.

Could also add an optional filter for --client or --miner wherever it makes sense since deals are between 2 parties.

go-filecoin deal list [--client  or --miner]   // optional filters (Could also secretly implement 'go-filecoin deals list' as well)
go-filecoin deal accept <dealid>
go-filecoin deal cancel <dealid>
go-filecoin deal status <dealid>   // could replace query-storage-deal
go-filecoin deal propose <miner> <data> <ask> <duration>  // could replace propose-storage-deal

Not sure what show does - would it be different from status above? Right now in 0.2.2 it's only used to show what's in a block. status might be better because it's about checking on things that change state.

Flat for vouchers works nicely too. How about a filter like --deal <dealid> in case there's a lot of them? (assuming a deal has many vouchers)

go-filecoin voucher list [--deal <dealid>]   // could secretly also allow 'vouchers' for this one
go-filecoin voucher redeem <voucherid>    // could also have 'go-filecoin voucher redeem all'
go-filecoin voucher status <voucherid>   

cat comes from IPFS for looking at the contents of a file so kind of makes sense where it is currently used. show might come from git show but I don't get why its used as a first-level command at all. The CLI is more often go-filecoin <some noun> right now rather than following git <verb>.

At some point in the future I can try to diagram / content audit all CLI commands and try to usability test them. (For now I defer to the devs and people who use the CLI more than I do). And please share any good CLI references.

[acruikshank]

@eshon Every thing you suggest for deals sounds right (although I'm not sure what it would mean to manually accept or cancel a deal).

It might help to clarify the current situation with vouchers a bit. Vouchers are associated with payment channels and could be used for any type of ongoing payment. Right now, they're only really used for storage deals. Deals can have many vouchers.

Vouchers don't have ids, and don't really have a status (though they can be valid or invalid).

We have a specific and acute need to be able to choose the most valuable, valid voucher in a deal and redeem it.

Give the above, does it make sense to have a voucher section, or could we get away with something like:

go-filecoin deal redeem <dealid>. // could also support deal redeem all

?

[rosalinekarr]

although I'm not sure what it would mean to manually accept or cancel a deal

@acruikshank, just fyi, this is something that I believe came up in Palo Alto between @rkowalick, @whyrusleeping and I. Currently, the storage protocol miner automatically accepts all deals it receives, but there was a suggestion that at some point in the future, we may want to give miners an interface for deciding which deals are lucrative enough to accept. In any case, it's something for the far future and not important right now.

[anorth]

Strong +1 for go-filecoin blah show rather than go-filecoin show blah.