diff --git a/kip-0006.md b/kip-0006.md new file mode 100644 index 0000000..8ccc11e --- /dev/null +++ b/kip-0006.md @@ -0,0 +1,163 @@ +--- +KIP: KIP-0006 +Title: transfer standard +Author: Doug Beardsley doug@kadena.io +Status: Draft +Type: Standard +Category: API +Created: 2020-08-12 +--- + +## Abstract + +Define a standard process / algorithm for handling Kadena token transfers that +facilitates smooth interoperability between various tools, services, and +ecosystem participants. + +## Motivation + +Kadena users have discovered that various parts of the Kadena ecosystem +(exchanges, wallets, etc) don't always interoperate seamlessly. Here are some +real problems that we have encountered: + +1. Transfers from one entity to another fail because because the receiving + account already existed and the sending entity used `transfer-create` with a + keyset that didn't match the one already defined for the account. +2. Transfers from one entity to another fail because the sending entity only + supported the `transfer` function but the user didn't have an existing + account or any coins by which to create one. +3. One tool or entity exports an address format not supported by other entities. + +## Rationale + +The Kadena ecosystem has several features that make this task complex: native +support for multi-sig (enabled by what we call "keysets"), an account model (as +opposed to a UTXO model) with stable account names and the ability to rotate +keysets, and multiple chains which unavoidably increase complexity for certain +types of transfers. + +Kadena tokens can be sent using one of three methods: `transfer`, +`transfer-create`, or `transfer-crosschain`. KIP-0002 [1] and KIP-0005 [2] are +the relevant KIPs where these functions are specified. The actual code used by +Chainweb for this can be found at [3]. + +### Requirements + +In order to fully support token transfers in the Kadena ecosystem, the following +requirements must be satisfied: + +1. SHOULD Use a single recipient input field +2. MUST support transfers to recipient account that doesn't exist +3. MUST support transfers to any recipient account that does exist and not fail + unnecessarily +4. SHOULD Warn about key mismatch +5. MUST support all of the following recipient formats: TxBuilder, single public + key, account name + +#### High Level Transfer Flow Chart + +[Flow Chart](kip-0006/transfer-flow-chart.png) + +#### Single Recipient Input Field + +Fully specifying a Kadena account can require quite a bit of data. Nice UIs for +specifying all of it as multiple input fields are complex to specify and build. +To keep the user experience simple, we recommend having a single input field +where the recipient information can be pasted. + +#### Transfer to New Accounts + +Systems that support Kadena token transfers MUST include support for +transferring to accounts that haven't been created yet. This is crucial for +onboarding new users who don't already hold KDA. + +#### Transfer to Any Existing Account + +It should be possible to transfer to ANY account that already exists on the +Kadena blockchain. We have seen some systems fail to do this because they used +`transfer-create` with a default keyset predicate. This will fail if the +predicate doesn't match the one already associated with the account. The only +potential exception to this is key mismatch, our next section... + +#### Warn About Key Mismatch + +Since Kadena account names have to be unique, it is often desireable to make the +account name be the same as the public key. Since public keys are randomly +generated and have 2^256 possible values, using the public key as the account +name is an easy way to guarantee uniqueness. However, if the account name is one +public key and the keyset has a different public key, users could end up +transferring tokens to an account that is not controlled by the person they +think it's controlled by. + +Kadena transfer systems should detect when an account name is a public key and +warn the user if the account's keyset is anything other than a single key keyset +with the same public key. + +#### Recipient Formats + +One of at least three formats should be accepted in the recipients field: +TxBuilder, public key, and account name. This can be implemented easily by first +attempting to parse the recipient as a TxBuilder. The TxBuilder data structure +contains all the information necessary to specify a recipient, so if the +recipient is a valid TxBuilder, the transfer can be done immediately. It is +possible that the transfer could fail, but that is unavoidable user error. + +If the recipient data is not a valid TxBuilder, the next step is to check if it +is a valid public key. In many other blockchains public keys define an account, +so this is important for making the Kadena ecosystem more accessible to +newcomers. + +TODO add more detail about proper handling of the public key case + +Finally, if the recipient data is not a valid public key, then we assume it is +an account name. In this case, we can do a `transfer` to that account name. If +possible, it is desireable to call the `details` function with that account name +to get balance and key information to show the user so they can sanity check +that the account is indeed controlled by the key(s) they expect. + +## Backwards Compatibility + +N/A + +## Specification + +### TxBuilder + +A TxBuilder is a JSON representation of all the information needed to specify +the recipient of a token transfer. Here is an example: + +``` +{ + "account": "my-test-account", + "chain": "00", + "keyset": { + "keys": [ + "b7d76b10eaff025a8c3307b8eb8804b1d4f68976176cd297e8da1c603a190ecb", + "e0fe8143702c6b706a8a2b18a675abcf517f26a43f12a4f375479974c394a305" + ], + "pred": "keys-any" + } +} +``` + +The `account` and `chain` fields are mandatory. They `keyset` field is optional. +Both the `transfer-create` and `transfer-crosschain` functions require a keyset, +so omitting the `keyset` field usually suggests the use of the `transfer` +function. + +The `keys` field specifies a list of keys that control this account. Currently +these are always 64-character hex strings that represent ED25519 public keys. In +the future more key types will be supported and the key representation will +include information about what signature algorithm is being used. + +The `pred` field specifies the keyset predicate that determines how many +signatures are required to sign transactions for this account. There are three +built-in predicates: `keys-all`, `keys-any`, and `keys-2`. Other user-specified +predicates are supported but that topic is out of scope for this document. + +## References + +[1] https://github.com/kadena-io/KIPs/blob/master/kip-0002.md +[2] https://github.com/kadena-io/KIPs/blob/master/kip-0005.md +[3] https://github.com/kadena-io/chainweb-node/tree/master/pact/coin-contract + diff --git a/kip-0006/transfer-flow-chart.png b/kip-0006/transfer-flow-chart.png new file mode 100644 index 0000000..63bf3ed Binary files /dev/null and b/kip-0006/transfer-flow-chart.png differ