search

informalsystems / themis-contract

A command line-based parameterized contracting tool
Apache License 2.0
46 stars 5 forks source link

Don't use "personal" as ID for signature example #94

Closed shonfeder closed 3 years ago

shonfeder commented 3 years ago

It doesn't make sense to have a signature with the id "personal". Signature id's are used to identify signatories, which means they must not have duplicate IDs, but if everyone used the ID "personal" they would all be clashing when trying to sign the same document. Also, the distinction between profiles and signatures is meant to allow different profiles to share the same signatures, so the example of the "personal" profile using a signature with the ID "personal" doesn't make sense.

shonfeder commented 3 years ago

I'm fast tracking this! We can make any fixes needed in a followup.

thanethomson commented 3 years ago

Local signature IDs have no relation to signatory IDs in the contract. See here for where the current signature is loaded.

Once the signature's loaded, and if you haven't used the themis-contract sign --as flag, it looks up your signatory in the contract.dhall file based on the e-mail address associated with the current local signature.

Perhaps some disambiguation's needed in the docs for this. Maybe a good way of explaining it in the docs would be something along the lines of: a "signature" is something that lives on your machine, and it has an ID and e-mail address associated with it. A "signatory" is an entity in the contract, and it also has an ID and e-mail address associated with it. The connection between the two is the e-mail address, not the ID.

shonfeder commented 3 years ago

Oh it's email address based! I had no idea. Having "id" fields which aren't actually used to coordinate identification is confusing IMO. I think this should be clarified in the manual and fixed in the implementation.

shonfeder commented 3 years ago

Still, I don't think "personal" is the kind of value that should be in an "id" field, and I don't understand why you'd name a signature "personal": people don't have different signatures for personal and private and purposes.

thanethomson commented 3 years ago

Thinking about it now, it's probably a good idea to do away with the IDs altogether 😁 It does just complicate the UX. I've opened #95 in this regard.

shonfeder commented 3 years ago

Awesome! I also forgot to say: sorry for my mistake here! I shouldn't have just assumed things worked a certain way :)

thanethomson commented 3 years ago

No, it's great UX feedback actually 😁

zramsay commented 3 years ago

yeah this PR helps with clarity 👍

The signature / signatory distinction could definitely be clarified and to Shon's point that "people don't have different signatures for personal and private and purposes." I wonder if the workflow could be streamlined in the setup phase, i.e., it could be one command to setup a signature and make it the default instead of having profile (IMO it adds a layer of complexity for the non power users)

shonfeder commented 3 years ago

That makes sense, @zramsay. Maye a "default" profile could be created automatically the first time a signature is added? Perhaps we need a new issue to track this?