Bigchaindb: Rename 'owners_after' to 'fulfillers'

[sohkai]

@ttmc, @TimDaub, and I had a small discussion on the misleading wording of 'owners_after' (they're not _exactly_ the owners after).

Thoughts @diminator @r-marques?

This should probably be done after https://github.com/bigchaindb/bigchaindb-common/pull/4 and #590 are merged, to make it easier to do.

[ttmc]

The list that we call owners_after is just a list of all public keys associated with the crypto-conditions (outputs) on the asset in the transaction. It's there for convenience. You can get that list by looking through all the conditions and subconditions etc.

The basic idea is that there are two sets of keys:

1. The set of keys associated with the crypto-conditions on an asset. They are the ones with some power to cause a transaction to happen. (This set is called owners_after in BigchaindB.)
2. The set of keys of the true owners of the asset. BigchainDB doesn't know or store those anywhere. It doesn't need them.

Right now, there's an implicit assumption (in BigchainDB) that those two sets of keys are equal, but here are some real-world examples illustrating how they can be different:

1. A club might have two co-treasurers and a bank account. The co-treasurers don't own the money in the bank account, but they can sign checks to pay others out of the bank account.
2. In many countries, a house can not be sold unless a notary signs some legal document, in addition to the current owners. The notary doesn't own the house, yet the notary would be one of the public keys with the power to cause a transfer.
3. Some trust funds are set up so that only trustees can sign documents to transfer money out of the fund. The trustees don't own the money in the fund.
4. Someone might have a will where they name an executor who has the power (or partial power) to transfer property to the beneficiaries named in the will. The executor doesn't own the assets listed in the will.

Related things: owned_before, owned_after and get_owned_ids

[diminator]

Agreed that they are not strictly owners_* and fulfillers is closer to their actual meaning. However at the point in time of owners_after they are not fulfillers but rather potential actors in the output condition. So maybe signees and signers are better terms.

Terminology aside, there is potentially a discrepancy to the public keys in the list and the actual actors in the condition: In the case of only a condition URI provided, there is no way for the system to cross-check the condition actors with the listed public keys.

I am currently leaning towards providing the full condition details when public keys are involved in the system (Threshold, Ed25519, ...) This can be detected from the type or feature bitmask.

[ttmc]

@TimDaub wrote some solution ideas as part of a comment to issue https://github.com/bigchaindb/bigchaindb-common/issues/31#issuecomment-251378908

[ttmc]

Another possible name, instead of fulfillers or signers, would be controllers, because the entities with the necessary signing keys (or hash preimages) control the transfer of the asset.

Or if we want to go verbose and super-literal, we could call then transfer_enablers.

[ttmc]

You might be wondering, "If we rename owners_* to something else (without the word owners), then where will we store the _true owners_ of the asset?"

Good question! We don't need to store the true owners anywhere. That can be seen as a privacy feature. Once we're using the new asset model (e.g. see PR #599), BigchainDB users can stuff the true owners inside the transaction.metadata.data if they like. It's up to them.

[ttmc]

get_owned_ids should also be renamed around the same time as owners_before and owners_after get renamed.

[diminator]

We don't need to store the true owners anywhere. That can be seen as a privacy feature.

Considering we would only work with URIs, this is true for owners_after but not for owners_before as the fulfillment_uri can be deserialized into a full object with all internals (verifying_keys) known

[ttmc]

@diminator Verifying whether those lists (to be renamed) agree with the conditions or fulfillments (if possible) is a separate issue. Should we create a new GitHub issue for that?

[diminator]

yeah, it's probably an involved issue

[ttmc]

Okay I created a new issue for that: #677

[ttmc]

Another idea: rather than coming up with a short word or phrase to describe what's those lists (currently named owners_after and owners_before) _really mean_, we could just change them both to pubkeys. I don't think anyone would disagree that they are, in fact, always lists of public keys!

We don't need the _after and _before because a pubkeys list will always come from inside a condition (the "after" case) or inside a fulfillment (the "before" case).

The _interpretation_ of a particular pubkeys list could then be federation-dependent. For example, I can imagine a special-purpose federation for storing the owners of garden gnomes. That federation might have a rule that each garden gnome can only have one owner and only that owner can sign to transfer it. In that federation, pubkeys will always be a list of length 1 and the one key in that list will be both the owner and the transfer-enabler.

We already use the "pubkey" shorthand in other places in the data models:

• Blocks have a block.node_pubkey
• Votes have a node_pubkey

[sbellem]

We don't need the _after and _before because a pubkeys list will always come from inside a condition (the "after" case) or inside a fulfillment (the "before" case).

Well, if that's the case, then this is a good idea!

[r-marques]

@ttmc also agree with that.
This is a good step to probably replace the notion of inputs and outputs with fulfillments and conditions

[ttmc]

@r-marques Yes, good point, but to keep the pull request for this issue manageable, I made a new issue for that: #743

[sohkai]

Closing for #743.