CHIP-0027: Signer Protocol Wallet APIs

CHIPs/chip-0027.md

@@ -0,0 +1,287 @@
+CHIP Number   | 0027
+:-------------|:----
+Title         | Signer Protocol Wallet APIs
+Description   | The maximum set of APIs for the wallet signer protocol
+Author        | [Matt Hauff](https://github.com/Quexington)
+Editor        | [Dan Perry](https://github.com/danieljperry)
+Comments-URI  | [CHIPs repo, PR #102](https://github.com/Chia-Network/chips/pull/102)
+Status        | Review
+Category      | Process
+Sub-Category  | Tooling
+Created       | 2024-03-14
+Requires      | None
+Replaces      | None
+Superseded-By | None
+
+## Abstract
+
+This CHIP provides the maximum set of APIs that can be used with the wallet signer protocol.
+
+## Motivation
+
+In order to use the wallet signer protocol, a standard set of APIs is needed. These APIs will be presented in human-readable JSON. Any wallet that wishes to implement the wallet signer protocol will need to serialize the APIs from this CHIP, for example by using the standard from [CHIP-0029](https://github.com/Chia-Network/chips/pull/104).
+
+## Backwards Compatibility
+
+This CHIP does not introduce any backwards incompatibilities. The APIs from this CHIP were created for the new wallet signer protocol. They do not modify any existing APIs. In addition, no code forks are necessary for this CHIP's implementation.
+
+## Rationale
+
+The specific APIs from this CHIP were created to be as simple as possible, while enabling the required functionality for communication with the wallet signer protocol.
+
+## Specification
+
+The specification for this CHIP consists of two parts:
+
+1. The types used in the APIs
+2. The APIs themselves
+
+### Types
+
+For brevity in the API descriptions, we will first define the following types:
+
+#### `coin`
+
+```py
+{
+  "parent_coin_id": "..."
+  "puzzle_hash": "..."
+  "amount": "..."
+}
+```
+
+---
+
+#### `spend`
+
+```py
+{
+  "coin": <coin>
+  "puzzle": "..."
+  "solution": "..."
+}
+```
+
+---
+
+#### `transaction_info`
+
+```py
+{
+  "spends": [<spend>]
+}
+```
+
+---
+
+#### `signing_target`
+
+```py
+{
+  "pubkey": "..."
+  "message": "..."
+  "hook": "..."
+}
+```
+
+---
+
+#### `sum_hint`
+
+```py
+{
+  "fingerprints": ["..."]
+  "synthetic_offset": "..."
+  "final_pubkey": "..."
+}
+```
+* Note 1: `synthetic_offset` is an optional parameter
+* Note 2: `final_pubkey` indicates the resulting pubkey of the sum of the others
+
+---
+
+#### `path_hint`
+
+```py
+{
+  "root_fingerprint": "..."
+  "path": ["..."]
+}
+```
+
+---
+
+#### `key_hints`
+
+```py
+{
+  "sum_hints": [<sum_hint>]
+  "path_hints": [<path_hint>]
+}
+```
+
+---
+
+#### `signing_instructions`
+
+```py
+{
+  "key_hints": <key_hints>
+  "targets": [<signing_target>]
+}
+```
+
+---
+
+#### `unsigned_transaction`
+
+```py
+{
+  "transaction_info": <transaction_info>
+  "signing_instructions": <signing_instructions>
+}
+```
+
+---
+
+#### `signing_response`
+
+```py
+{
+  "signature": <signature>
+  "hook": "..."
+}
+```
+
+---
+
+#### `signature`
+
+```py
+{
+  "signature_type": <signature_type>
+  "signature": <signature>
+}
+```
+
+Where valid options for `<signature_type>` include:
+* `bls_12381_aug_scheme`
+
+---
+
+#### `signed_transaction`
+
+```py
+{
+  "transaction_info": <transaction_info>
+  "signatures": [<signature>]
+}
+```
+
+---
+
+### APIs
+
+This section contains a list of optional RPC APIs to be used with the wallet signer protocol.
+
+#### Note on serialization
+
+Each specific implementation will have the option for how to handle the serialization of the keys in this section.
+
+For example, the return values for wallet RPC APIs typically are in JSON format, so the client code may send something like:
+
+`response["unsigned_transactions"]`
+
+This will send a list of BLOBs that are serialized according to the specified translation/serialization CHIPS, but the whole response will not be serialized in this way.
+
+---
+
+#### `create_transactions`
+
+Note: In current practice this will come from many RPCs, though this may not necessarily always be true.
+
+**ARGUMENTS**
+```
+Defined on a case-by-case basis.
+```
+
+**RETURNS**
+```py
+{
+  "unsigned_transactions": [<unsigned_transaction>]
+}
+```
+
+---
+
+#### `gather_signing_info`
+
+**ARGUMENTS**
+```py
+{
+  "spends": [<spend>]
+}
+```
+
+**RETURNS**
+```py
+{
+  "signing_instructions": <signing_instructions>
+}
+```
+
+---
+
+#### `apply_signatures`
+
+**ARGUMENTS**
+```py
+{
+  "spends": [<spend>]
+  "signing_responses": [<signing_response>]
+}
+```
+
+**RETURNS**
+```py
+{
+  "signed_transactions": [<signed_transaction>]
+}
+```
+
+---
+
+#### `submit_transactions`
+
+**ARGUMENTS**
+```py
+{
+  "signed_transactions": [<signed_transaction>]
+}
+```
+
+**RETURNS**
+```py
+{
+  "mempool_ids": ["..."],
+}
+```
+
+## Reference Implementation
+
+The APIs for this CHIP have been implemented in the following locations:
+* [gather_signing_info](https://github.com/Chia-Network/chia-blockchain/blob/8e3a42c7c1cd5687b657bbd72dbc6ea0774001af/chia/wallet/wallet_state_manager.py#L2652)
+* [apply_signatures](https://github.com/Chia-Network/chia-blockchain/blob/385916a6a29c5124155b43cb7cfe48c6ec7b3590/chia/wallet/wallet.py#L679)
+* [submit_transactions](https://github.com/Chia-Network/chia-blockchain/blob/8e3a42c7c1cd5687b657bbd72dbc6ea0774001af/chia/wallet/wallet_state_manager.py#L2784)
+* [signer_protocol](https://github.com/Chia-Network/chia-blockchain/blob/385916a6a29c5124155b43cb7cfe48c6ec7b3590/chia/wallet/signer_protocol.py)
+
+## Security
+
+Chia Network, Inc. has conducted an internal review of the code involved with this CHIP.
+
+## Additional Assets
+
+None
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).