diff --git a/docs/protocol/wallet-protocol.md b/docs/protocol/wallet-protocol.md index 7a6b142f68..8c3df4ea92 100644 --- a/docs/protocol/wallet-protocol.md +++ b/docs/protocol/wallet-protocol.md @@ -127,6 +127,37 @@ class RespondBlockHeader(Streamable): header_block: HeaderBlock ``` +## request_block_headers + +A request from the wallet to the full node for a HeaderBlock at a specific height. +NOTE: this message deprecates and replaces `request_header_blocks` (flip block and header). + +```python +class RequestBlockHeaders(Streamable): + height: uint32 # Height of the header block +``` + +## respond_block_headers + +A response to a `request_block_headers` request. +NOTE: this message deprecates and replaces `respond_header_blocks` (flip block and header). + +```python +class RespondBlockHeaders(Streamable): + header_block: HeaderBlock +``` + +## reject_block_headers + +A rejection to a `request_block_headers` request. +NOTE: this message deprecates and replaces `reject_header_blocks` (flip block and header). + +```python +class RejectBlockHeaders(Streamable): + start_height: uint32 + end_height: uint32 +``` + ## reject_header_request A rejection to a `request_block_header` request. @@ -215,6 +246,7 @@ class RejectAdditionsRequest(Streamable): ## request_header_blocks +DEPRECATED: this message has been deprecated and replaced with `request_block_headers` (flip block and header). A request from the wallet to the full node for a list of consecutive header blocks, inclusive. ```python @@ -225,6 +257,7 @@ class RequestHeaderBlocks(Streamable): ## reject_header_blocks +DEPRECATED: this message has been deprecated and replaced with `reject_block_headers` (flip block and header). A rejection for a `request_header_blocks` request. ```python @@ -235,6 +268,7 @@ class RejectHeaderBlocks(Streamable): ## respond_header_blocks +DEPRECATED: this message has been deprecated and replaced with `respond_block_headers` (flip block and header). A response to a `request_header_blocks` request. ```python @@ -350,3 +384,190 @@ class RespondSESInfo(Streamable): reward_chain_hash: List[bytes32] heights: List[List[uint32]] ``` + +:::note +The below messages have been added via [Chip 26](https://github.com/Chia-Network/chips/blob/8a597d06988eb308aa13488c5916ec041f39bc74/CHIPs/chip-0026.md). +These have been added to the reference [node codebase](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/protocols/wallet_protocol.py) but have not been implemented in the reference wallet as of January 2025. +::: + +## request_remove_puzzle_subscriptions + +Removes puzzle hashes from the subscription list (or all of them if None). + +```python +class RequestRemovePuzzleSubscriptions: + puzzle_hashes: Optional[List[bytes32]] +``` + +## respond_remove_puzzle_subscriptions + +Returns the hashes that were actually removed. + +```python +class RespondRemovePuzzleSubscriptions: + puzzle_hashes: List[bytes32] +``` + +## request_remove_coin_subscriptions + +Removes coin ids from the subscription list (or all of them if None) + +```python +class RequestRemoveCoinSubscriptions: + coin_ids: Optional[List[bytes32]] +``` + +## respond_remove_coin_subscriptions + +Returns the ids that were actually removed. + +```python +class RespondRemoveCoinSubscriptions: + coin_ids: List[bytes32] +``` + +## request_puzzle_state + +Requests coin states that match the given puzzle hashes (or hints). +When subscribe is set to True, it will add and return as many coin ids to the subscriptions list as possible. +When subscribe is set to True and mempool updates are enabled (can be done during the handshake) mempool update messages will be sent (including an initial MempoolItemsAdded message when you subscribe for the first time). +Filter out spent, unspent, or hinted coins, as well as coins below a minimum amount. + +```python +class RequestPuzzleState: + puzzle_hashes: List[bytes32] + previous_height: Optional[uint32] + header_hash: bytes32 + filters: CoinStateFilters + subscribe_when_finished: bool + +class CoinStateFilters: + include_spent: bool + include_unspent: bool + include_hinted: bool + min_amount: uint64 +``` + +## respond_puzzle_state + +Responds with coin states that match the given puzzle hashes (or hints). + +```python +class RespondPuzzleState: + puzzle_hashes: List[bytes32] + height: uint32 + header_hash: bytes32 + is_finished: bool + coin_states: List[CoinState] +``` + +## reject_puzzle_state + +Reject request_puzzle_state in the event that a reorg is detected by a node, this is the only scenario it will be rejected like this. + +```python +class RejectPuzzleState: + reason: uint8 # RejectStateReason + + +class RejectStateReason(IntEnum): + REORG = 0 + EXCEEDED_SUBSCRIPTION_LIMIT = 1 +``` + +## request_coin_state + +Request coin states that match the given coin ids. +When subscribe is set to True, it will add and return as many coin ids to the subscriptions list as possible. +When subscribe is set to True and mempool updates are enabled (can be done during the handshake) mempool update messages will be sent (including an initial MempoolItemsAdded message when you subscribe for the first time). + +```python +class RequestCoinState: + coin_ids: List[bytes32] + previous_height: Optional[uint32] + header_hash: bytes32 + subscribe: bool +``` + +## respond_coin_state + +Respond with coin states that match the given coin ids. +This does not implement batching for simplicity. The order is also not guaranteed. However, you can still specify the previous_height and header_hash to start. + +```python +class RespondCoinState: + coin_ids: List[bytes32] + coin_states: List[CoinState] +``` + +## reject_coin_state + +Reject request_coin_state in the event that a reorg is detected by a node, this is the only scenario it will be rejected like this. + +```python +class RejectCoinState: + reason: uint8 # RejectStateReason + +class RejectStateReason(IntEnum): + REORG = 0 + EXCEEDED_SUBSCRIPTION_LIMIT = 1 +``` + +## mempool_items_added + +The below mempool update messages (including an initial MempoolItemsAdded message when you subscribe for the first time) are received when: + +- `request_coin_state` or `request_puzzle_state` messages are sent, +- AND subscribe is set to True in the request, +- AND mempool updates are enabled (can be done during the handshake). + +```python +class MempoolItemsAdded: + transaction_ids: List[bytes32] +``` + +## mempool_items_removed + +The below mempool update messages (including an initial MempoolItemsAdded message when you subscribe for the first time) are received when: + +- `request_coin_state` or `request_puzzle_state` messages are sent, +- AND subscribe is set to True in the request, +- AND mempool updates are enabled (can be done during the handshake). + +```python +class MempoolItemsRemoved: + removed_items: List[RemovedMempoolItem] + +class RemovedMempoolItem: + transaction_id: bytes32 + reason: uint8 # MempoolRemoveReason + +class MempoolRemoveReason(Enum): + CONFLICT = 1 + BLOCK_INCLUSION = 2 + POOL_FULL = 3 + EXPIRED = 4 +``` + +## request_cost_info + +Request various information about the costs of transactions, blocks, and the mempool. + +```python +class RequestCostInfo: + pass +``` + +## respond_cost_info + +Respond with various information about the costs of transactions, blocks, and the mempool. + +```python +class RespondCostInfo: + max_transaction_cost: uint64 + max_block_cost: uint64 + max_mempool_cost: uint64 + mempool_cost: uint64 + mempool_fee: uint64 + bump_fee_per_cost: uint8 +```