host_api/

chain.rs

//! Remote chain protocol methods (tags 76-103).
//!
//! Translates between SCALE-encoded binary messages from the product-SDK
//! and JSON-RPC for smoldot.  Each function either:
//! - Parses a smoldot JSON-RPC notification and encodes the result as SCALE, or
//! - Encodes a SCALE response for a given chain request tag.
//!
//! All response messages follow the envelope:
//!   `request_id (SCALE str) + response_tag (u8) + v1 (0x00) + payload`

use crate::codec::*;

// ---------------------------------------------------------------------------
// Protocol tag constants (76-103)
// ---------------------------------------------------------------------------

pub const TAG_CHAIN_HEAD_FOLLOW_START: u8 = 76;
pub const TAG_CHAIN_HEAD_FOLLOW_STOP: u8 = 77;
pub const TAG_CHAIN_HEAD_FOLLOW_INTERRUPT: u8 = 78;
pub const TAG_CHAIN_HEAD_FOLLOW_RECEIVE: u8 = 79;

pub const TAG_CHAIN_HEAD_HEADER_REQ: u8 = 80;
pub const TAG_CHAIN_HEAD_HEADER_RESP: u8 = 81;

pub const TAG_CHAIN_HEAD_BODY_REQ: u8 = 82;
pub const TAG_CHAIN_HEAD_BODY_RESP: u8 = 83;

pub const TAG_CHAIN_HEAD_STORAGE_REQ: u8 = 84;
pub const TAG_CHAIN_HEAD_STORAGE_RESP: u8 = 85;

pub const TAG_CHAIN_HEAD_CALL_REQ: u8 = 86;
pub const TAG_CHAIN_HEAD_CALL_RESP: u8 = 87;

pub const TAG_CHAIN_HEAD_UNPIN_REQ: u8 = 88;
pub const TAG_CHAIN_HEAD_UNPIN_RESP: u8 = 89;

pub const TAG_CHAIN_HEAD_CONTINUE_REQ: u8 = 90;
pub const TAG_CHAIN_HEAD_CONTINUE_RESP: u8 = 91;

pub const TAG_CHAIN_HEAD_STOP_OP_REQ: u8 = 92;
pub const TAG_CHAIN_HEAD_STOP_OP_RESP: u8 = 93;

pub const TAG_CHAIN_SPEC_GENESIS_HASH_REQ: u8 = 94;
pub const TAG_CHAIN_SPEC_GENESIS_HASH_RESP: u8 = 95;

pub const TAG_CHAIN_SPEC_CHAIN_NAME_REQ: u8 = 96;
pub const TAG_CHAIN_SPEC_CHAIN_NAME_RESP: u8 = 97;

pub const TAG_CHAIN_SPEC_PROPERTIES_REQ: u8 = 98;
pub const TAG_CHAIN_SPEC_PROPERTIES_RESP: u8 = 99;

pub const TAG_CHAIN_TX_BROADCAST_REQ: u8 = 100;
pub const TAG_CHAIN_TX_BROADCAST_RESP: u8 = 101;

pub const TAG_CHAIN_TX_STOP_REQ: u8 = 102;
pub const TAG_CHAIN_TX_STOP_RESP: u8 = 103;

// ---------------------------------------------------------------------------
// Data types
// ---------------------------------------------------------------------------

/// Runtime information attached to Initialized / NewBlock events.
#[derive(Debug, Clone)]
pub enum RuntimeInfo {
    /// A valid runtime with its specification.
    Valid(RuntimeSpec),
    /// A runtime that could not be decoded.
    Invalid { error: String },
}

/// Parsed runtime specification fields.
#[derive(Debug, Clone)]
pub struct RuntimeSpec {
    pub spec_name: String,
    pub impl_name: String,
    pub spec_version: u32,
    pub impl_version: u32,
    /// `None` when the chain does not expose a transaction version.
    pub transaction_version: Option<u32>,
    /// List of `(apiName, version)` tuples.
    pub apis: Vec<(String, u32)>,
}

/// A single storage result item returned in OperationStorageItems.
#[derive(Debug, Clone)]
pub struct StorageResultItem {
    pub key: Vec<u8>,
    /// Nullable storage value at `key`.
    pub value: Option<Vec<u8>>,
    /// Nullable hash of the storage value.
    pub hash: Option<Vec<u8>>,
    /// Nullable closest-descendant Merkle value.
    pub closest_descendant_merkle_value: Option<Vec<u8>>,
}

/// Strongly-typed representation of every `chainHead_v1_followEvent` variant.
#[derive(Debug, Clone)]
pub enum ChainHeadEvent {
    /// tag 0 — initial state delivered immediately after follow subscription starts.
    Initialized {
        finalized_block_hashes: Vec<Vec<u8>>,
        finalized_block_runtime: Option<RuntimeInfo>,
    },
    /// tag 1 — a new block has been added to the chain.
    NewBlock {
        block_hash: Vec<u8>,
        parent_block_hash: Vec<u8>,
        new_runtime: Option<RuntimeInfo>,
    },
    /// tag 2 — the best block has changed.
    BestBlockChanged { best_block_hash: Vec<u8> },
    /// tag 3 — one or more blocks have been finalized.
    Finalized {
        finalized_block_hashes: Vec<Vec<u8>>,
        pruned_block_hashes: Vec<Vec<u8>>,
    },
    /// tag 4 — body operation completed.
    OperationBodyDone {
        operation_id: String,
        value: Vec<Vec<u8>>,
    },
    /// tag 5 — call operation completed.
    OperationCallDone {
        operation_id: String,
        output: Vec<u8>,
    },
    /// tag 6 — storage operation delivered a batch of items.
    OperationStorageItems {
        operation_id: String,
        items: Vec<StorageResultItem>,
    },
    /// tag 7 — storage operation finished (no more items).
    OperationStorageDone { operation_id: String },
    /// tag 8 — operation is paused; call `continue` to resume.
    OperationWaitingForContinue { operation_id: String },
    /// tag 9 — operation could not be completed (block inaccessible).
    OperationInaccessible { operation_id: String },
    /// tag 10 — operation failed with an error message.
    OperationError { operation_id: String, error: String },
    /// tag 11 — the follow subscription has been forcibly stopped by the server.
    Stop,
}

// ---------------------------------------------------------------------------
// Hex helpers
// ---------------------------------------------------------------------------

/// Convert a `"0xabcd"` hex string to raw bytes `[0xab, 0xcd]`.
///
/// The `"0x"` prefix is optional; an empty string returns an empty `Vec`.
pub fn hex_to_bytes(hex: &str) -> Vec<u8> {
    let s = hex.strip_prefix("0x").unwrap_or(hex);
    if s.is_empty() {
        return Vec::new();
    }
    // Decode two hex digits at a time; silently drop trailing nibble on odd length.
    (0..s.len() / 2)
        .filter_map(|i| u8::from_str_radix(&s[i * 2..i * 2 + 2], 16).ok())
        .collect()
}

/// Convert raw bytes `[0xab, 0xcd]` to `"0xabcd"`.
pub fn bytes_to_hex(bytes: &[u8]) -> String {
    let mut s = String::with_capacity(2 + bytes.len() * 2);
    s.push_str("0x");
    for b in bytes {
        s.push(char::from_digit((b >> 4) as u32, 16).unwrap_or('0'));
        s.push(char::from_digit((b & 0xf) as u32, 16).unwrap_or('0'));
    }
    s
}

// ---------------------------------------------------------------------------
// JSON parsing helpers
// ---------------------------------------------------------------------------

/// Extract the `"0x..."` string from a JSON value and decode to bytes.
fn json_hex(v: &serde_json::Value) -> Option<Vec<u8>> {
    Some(hex_to_bytes(v.as_str()?))
}

/// Parse a JSON `runtimeSpec` object into a `RuntimeSpec`.
fn parse_runtime_spec(obj: &serde_json::Value) -> Option<RuntimeSpec> {
    let spec_name = obj.get("specName")?.as_str()?.to_string();
    let impl_name = obj.get("implName")?.as_str()?.to_string();
    let spec_version = obj.get("specVersion")?.as_u64()? as u32;
    let impl_version = obj.get("implVersion")?.as_u64()? as u32;
    let transaction_version = obj
        .get("transactionVersion")
        .and_then(|v| v.as_u64())
        .map(|v| v as u32);

    // apis: array of [name, version] tuples (JSON spec uses arrays, not objects)
    let apis = obj
        .get("apis")
        .and_then(|a| a.as_array())
        .map(|arr| {
            arr.iter()
                .filter_map(|item| {
                    let pair = item.as_array()?;
                    if pair.len() < 2 {
                        return None;
                    }
                    let name = pair[0].as_str()?.to_string();
                    let version = pair[1].as_u64()? as u32;
                    Some((name, version))
                })
                .collect()
        })
        .unwrap_or_default();

    Some(RuntimeSpec {
        spec_name,
        impl_name,
        spec_version,
        impl_version,
        transaction_version,
        apis,
    })
}

/// Parse a JSON `runtime` field (may be `null`, `{ "type": "valid", ... }`, or `{ "type": "invalid", ... }`).
fn parse_runtime_info(v: &serde_json::Value) -> Option<RuntimeInfo> {
    if v.is_null() {
        return None;
    }
    let ty = v.get("type")?.as_str()?;
    match ty {
        "valid" => {
            let spec = parse_runtime_spec(v.get("spec")?)?;
            Some(RuntimeInfo::Valid(spec))
        }
        "invalid" => {
            let error = v
                .get("error")
                .and_then(|e| e.as_str())
                .unwrap_or("")
                .to_string();
            Some(RuntimeInfo::Invalid { error })
        }
        _ => None,
    }
}

/// Parse a JSON array of hex strings into `Vec<Vec<u8>>`.
fn parse_hex_array(arr: &serde_json::Value) -> Vec<Vec<u8>> {
    arr.as_array()
        .map(|a| a.iter().filter_map(json_hex).collect())
        .unwrap_or_default()
}

/// Parse a JSON `storageResultItem` object.
fn parse_storage_item(obj: &serde_json::Value) -> Option<StorageResultItem> {
    let key = json_hex(obj.get("key")?)?;

    // Each of these three fields is nullable (may be absent or null).
    let value = obj
        .get("value")
        .and_then(|v| if v.is_null() { None } else { json_hex(v) });
    let hash = obj
        .get("hash")
        .and_then(|v| if v.is_null() { None } else { json_hex(v) });
    let closest_descendant_merkle_value = obj.get("closestDescendantMerkleValue").and_then(|v| {
        if v.is_null() {
            None
        } else {
            json_hex(v)
        }
    });

    Some(StorageResultItem {
        key,
        value,
        hash,
        closest_descendant_merkle_value,
    })
}

// ---------------------------------------------------------------------------
// Public: parse a chainHead_v1_followEvent JSON-RPC notification
// ---------------------------------------------------------------------------

/// Parse a smoldot `chainHead_v1_followEvent` notification into a `ChainHeadEvent`.
///
/// Expected JSON shape:
/// ```json
/// {
///   "jsonrpc": "2.0",
///   "method": "chainHead_v1_followEvent",
///   "params": {
///     "subscription": "...",
///     "result": { "event": "...", ... }
///   }
/// }
/// ```
///
/// Returns `None` if the message is not a follow-event or cannot be parsed.
pub fn parse_chain_head_json_rpc(json_rpc: &str) -> Option<ChainHeadEvent> {
    let root: serde_json::Value = serde_json::from_str(json_rpc).ok()?;

    // Verify method name.
    if root.get("method")?.as_str()? != "chainHead_v1_followEvent" {
        return None;
    }

    let result = root.get("params")?.get("result")?;
    let event = result.get("event")?.as_str()?;

    match event {
        "initialized" => {
            let finalized_block_hashes = parse_hex_array(
                result
                    .get("finalizedBlockHashes")
                    .unwrap_or(&serde_json::Value::Null),
            );
            let finalized_block_runtime = result
                .get("finalizedBlockRuntime")
                .and_then(parse_runtime_info);
            Some(ChainHeadEvent::Initialized {
                finalized_block_hashes,
                finalized_block_runtime,
            })
        }

        "newBlock" => {
            let block_hash = json_hex(result.get("blockHash")?)?;
            let parent_block_hash = json_hex(result.get("parentBlockHash")?)?;
            let new_runtime = result.get("newRuntime").and_then(parse_runtime_info);
            Some(ChainHeadEvent::NewBlock {
                block_hash,
                parent_block_hash,
                new_runtime,
            })
        }

        "bestBlockChanged" => {
            let best_block_hash = json_hex(result.get("bestBlockHash")?)?;
            Some(ChainHeadEvent::BestBlockChanged { best_block_hash })
        }

        "finalized" => {
            let finalized_block_hashes = parse_hex_array(
                result
                    .get("finalizedBlockHashes")
                    .unwrap_or(&serde_json::Value::Null),
            );
            let pruned_block_hashes = parse_hex_array(
                result
                    .get("prunedBlockHashes")
                    .unwrap_or(&serde_json::Value::Null),
            );
            Some(ChainHeadEvent::Finalized {
                finalized_block_hashes,
                pruned_block_hashes,
            })
        }

        "operationBodyDone" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            let value = parse_hex_array(result.get("value").unwrap_or(&serde_json::Value::Null));
            Some(ChainHeadEvent::OperationBodyDone {
                operation_id,
                value,
            })
        }

        "operationCallDone" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            let output = json_hex(result.get("output")?)?;
            Some(ChainHeadEvent::OperationCallDone {
                operation_id,
                output,
            })
        }

        "operationStorageItems" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            let items = result
                .get("items")
                .and_then(|a| a.as_array())
                .map(|arr| arr.iter().filter_map(parse_storage_item).collect())
                .unwrap_or_default();
            Some(ChainHeadEvent::OperationStorageItems {
                operation_id,
                items,
            })
        }

        "operationStorageDone" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            Some(ChainHeadEvent::OperationStorageDone { operation_id })
        }

        "operationWaitingForContinue" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            Some(ChainHeadEvent::OperationWaitingForContinue { operation_id })
        }

        "operationInaccessible" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            Some(ChainHeadEvent::OperationInaccessible { operation_id })
        }

        "operationError" => {
            let operation_id = result.get("operationId")?.as_str()?.to_string();
            let error = result
                .get("error")
                .and_then(|e| e.as_str())
                .unwrap_or("")
                .to_string();
            Some(ChainHeadEvent::OperationError {
                operation_id,
                error,
            })
        }

        "stop" => Some(ChainHeadEvent::Stop),

        _ => None,
    }
}

// ---------------------------------------------------------------------------
// SCALE encoding helpers
// ---------------------------------------------------------------------------

/// Encode a `RuntimeInfo` option as SCALE Option(RuntimeType).
///
/// None     → 0x00
/// Some(v)  → 0x01 + RuntimeType_SCALE
fn encode_runtime_info_option(buf: &mut Vec<u8>, rt: &Option<RuntimeInfo>) {
    match rt {
        None => encode_option_none(buf),
        Some(info) => {
            encode_option_some(buf);
            encode_runtime_info(buf, info);
        }
    }
}

/// Encode a `RuntimeInfo` as the SCALE `RuntimeType` enum.
///
/// RuntimeType = Enum { 0: Valid(RuntimeSpec), 1: Invalid({ error: str }) }
fn encode_runtime_info(buf: &mut Vec<u8>, info: &RuntimeInfo) {
    match info {
        RuntimeInfo::Valid(spec) => {
            encode_tag(buf, 0); // Valid variant
            encode_string(buf, &spec.spec_name);
            encode_string(buf, &spec.impl_name);
            buf.extend_from_slice(&spec.spec_version.to_le_bytes());
            buf.extend_from_slice(&spec.impl_version.to_le_bytes());
            // transactionVersion: Option(u32)
            match spec.transaction_version {
                None => encode_option_none(buf),
                Some(v) => {
                    encode_option_some(buf);
                    buf.extend_from_slice(&v.to_le_bytes());
                }
            }
            // apis: Vector(Tuple(str, u32))
            encode_vector_len(buf, spec.apis.len() as u32);
            for (name, version) in &spec.apis {
                encode_string(buf, name);
                buf.extend_from_slice(&version.to_le_bytes());
            }
        }
        RuntimeInfo::Invalid { error } => {
            encode_tag(buf, 1); // Invalid variant
            encode_string(buf, error);
        }
    }
}

/// Encode a `ChainHeadEvent` as its SCALE representation (without the outer envelope).
fn encode_event_payload(buf: &mut Vec<u8>, event: &ChainHeadEvent) {
    match event {
        ChainHeadEvent::Initialized {
            finalized_block_hashes,
            finalized_block_runtime,
        } => {
            encode_tag(buf, 0);
            encode_vector_len(buf, finalized_block_hashes.len() as u32);
            for hash in finalized_block_hashes {
                encode_var_bytes(buf, hash);
            }
            encode_runtime_info_option(buf, finalized_block_runtime);
        }

        ChainHeadEvent::NewBlock {
            block_hash,
            parent_block_hash,
            new_runtime,
        } => {
            encode_tag(buf, 1);
            encode_var_bytes(buf, block_hash);
            encode_var_bytes(buf, parent_block_hash);
            encode_runtime_info_option(buf, new_runtime);
        }

        ChainHeadEvent::BestBlockChanged { best_block_hash } => {
            encode_tag(buf, 2);
            encode_var_bytes(buf, best_block_hash);
        }

        ChainHeadEvent::Finalized {
            finalized_block_hashes,
            pruned_block_hashes,
        } => {
            encode_tag(buf, 3);
            encode_vector_len(buf, finalized_block_hashes.len() as u32);
            for hash in finalized_block_hashes {
                encode_var_bytes(buf, hash);
            }
            encode_vector_len(buf, pruned_block_hashes.len() as u32);
            for hash in pruned_block_hashes {
                encode_var_bytes(buf, hash);
            }
        }

        ChainHeadEvent::OperationBodyDone {
            operation_id,
            value,
        } => {
            encode_tag(buf, 4);
            encode_string(buf, operation_id);
            encode_vector_len(buf, value.len() as u32);
            for item in value {
                encode_var_bytes(buf, item);
            }
        }

        ChainHeadEvent::OperationCallDone {
            operation_id,
            output,
        } => {
            encode_tag(buf, 5);
            encode_string(buf, operation_id);
            encode_var_bytes(buf, output);
        }

        ChainHeadEvent::OperationStorageItems {
            operation_id,
            items,
        } => {
            encode_tag(buf, 6);
            encode_string(buf, operation_id);
            encode_vector_len(buf, items.len() as u32);
            for item in items {
                encode_var_bytes(buf, &item.key);
                // value: Nullable(Hex())
                match &item.value {
                    None => encode_option_none(buf),
                    Some(v) => {
                        encode_option_some(buf);
                        encode_var_bytes(buf, v);
                    }
                }
                // hash: Nullable(Hex())
                match &item.hash {
                    None => encode_option_none(buf),
                    Some(h) => {
                        encode_option_some(buf);
                        encode_var_bytes(buf, h);
                    }
                }
                // closestDescendantMerkleValue: Nullable(Hex())
                match &item.closest_descendant_merkle_value {
                    None => encode_option_none(buf),
                    Some(v) => {
                        encode_option_some(buf);
                        encode_var_bytes(buf, v);
                    }
                }
            }
        }

        ChainHeadEvent::OperationStorageDone { operation_id } => {
            encode_tag(buf, 7);
            encode_string(buf, operation_id);
        }

        ChainHeadEvent::OperationWaitingForContinue { operation_id } => {
            encode_tag(buf, 8);
            encode_string(buf, operation_id);
        }

        ChainHeadEvent::OperationInaccessible { operation_id } => {
            encode_tag(buf, 9);
            encode_string(buf, operation_id);
        }

        ChainHeadEvent::OperationError {
            operation_id,
            error,
        } => {
            encode_tag(buf, 10);
            encode_string(buf, operation_id);
            encode_string(buf, error);
        }

        ChainHeadEvent::Stop => {
            encode_tag(buf, 11);
            // void — no payload
        }
    }
}

/// Write the standard message envelope: `discriminator + request_id + response_tag + v1(0)`.
fn encode_envelope(buf: &mut Vec<u8>, request_id: &str, response_tag: u8) {
    buf.push(crate::protocol::PROTOCOL_DISCRIMINATOR);
    encode_string(buf, request_id);
    encode_tag(buf, response_tag);
    encode_tag(buf, 0); // v1
}

/// Write the `GenericError` payload for Result::Err.
///
/// Encoding: `0x01 (Err) + 0x00 (Unknown variant) + SCALE string(reason)`.
fn encode_generic_error(buf: &mut Vec<u8>, reason: &str) {
    encode_result_err(buf);
    encode_tag(buf, 0); // Unknown variant
    encode_string(buf, reason);
}

// ---------------------------------------------------------------------------
// Public encode functions
// ---------------------------------------------------------------------------

/// Encode a `chainHead_v1_followEvent` receive message (tag 79).
///
/// Wire format: `request_id + 0x4F (79) + 0x00 (v1) + ChainHeadEvent_SCALE`
pub fn encode_chain_head_event(request_id: &str, event: &ChainHeadEvent) -> Vec<u8> {
    let mut buf = Vec::with_capacity(128);
    encode_envelope(&mut buf, request_id, TAG_CHAIN_HEAD_FOLLOW_RECEIVE);
    encode_event_payload(&mut buf, event);
    buf
}

/// Encode a `Result(void, GenericError)` response.
///
/// Used by tags 89 (unpin), 91 (continue), 93 (stop-operation), 103 (tx-stop).
pub fn encode_chain_response_void(
    request_id: &str,
    response_tag: u8,
    error: Option<&str>,
) -> Vec<u8> {
    let mut buf = Vec::with_capacity(32);
    encode_envelope(&mut buf, request_id, response_tag);
    match error {
        None => encode_result_ok_void(&mut buf),
        Some(reason) => encode_generic_error(&mut buf, reason),
    }
    buf
}

/// Encode a `Result(Nullable(Hex()), GenericError)` response.
///
/// Used by tag 81 (header).
pub fn encode_chain_response_nullable_hex(
    request_id: &str,
    response_tag: u8,
    result: Result<Option<&[u8]>, &str>,
) -> Vec<u8> {
    let mut buf = Vec::with_capacity(64);
    encode_envelope(&mut buf, request_id, response_tag);
    match result {
        Ok(maybe_bytes) => {
            encode_result_ok(&mut buf);
            match maybe_bytes {
                None => encode_option_none(&mut buf),
                Some(bytes) => {
                    encode_option_some(&mut buf);
                    encode_var_bytes(&mut buf, bytes);
                }
            }
        }
        Err(reason) => encode_generic_error(&mut buf, reason),
    }
    buf
}

/// Encode a `Result(OperationStartedResult, GenericError)` response.
///
/// `Ok(Some(id))` encodes as `Started { operationId: id }` (variant 0).
/// `Ok(None)` encodes as `LimitReached` (variant 1).
///
/// Used by tags 83 (body), 85 (storage), 87 (call).
pub fn encode_chain_response_operation_started(
    request_id: &str,
    response_tag: u8,
    result: Result<Option<&str>, &str>,
) -> Vec<u8> {
    let mut buf = Vec::with_capacity(64);
    encode_envelope(&mut buf, request_id, response_tag);
    match result {
        Ok(Some(op_id)) => {
            encode_result_ok(&mut buf);
            encode_tag(&mut buf, 0); // Started variant
            encode_string(&mut buf, op_id);
        }
        Ok(None) => {
            encode_result_ok(&mut buf);
            encode_tag(&mut buf, 1); // LimitReached variant (void)
        }
        Err(reason) => encode_generic_error(&mut buf, reason),
    }
    buf
}

/// Encode a `Result(Hex(), GenericError)` response.
///
/// Used by tag 95 (genesis hash).
pub fn encode_chain_response_hex(
    request_id: &str,
    response_tag: u8,
    result: Result<&[u8], &str>,
) -> Vec<u8> {
    let mut buf = Vec::with_capacity(64);
    encode_envelope(&mut buf, request_id, response_tag);
    match result {
        Ok(bytes) => {
            encode_result_ok(&mut buf);
            encode_var_bytes(&mut buf, bytes);
        }
        Err(reason) => encode_generic_error(&mut buf, reason),
    }
    buf
}

/// Encode a `Result(str, GenericError)` response.
///
/// Used by tags 97 (chain name), 99 (chain properties).
pub fn encode_chain_response_string(
    request_id: &str,
    response_tag: u8,
    result: Result<&str, &str>,
) -> Vec<u8> {
    let mut buf = Vec::with_capacity(64);
    encode_envelope(&mut buf, request_id, response_tag);
    match result {
        Ok(s) => {
            encode_result_ok(&mut buf);
            encode_string(&mut buf, s);
        }
        Err(reason) => encode_generic_error(&mut buf, reason),
    }
    buf
}

/// Encode a `Result(Nullable(str), GenericError)` response.
///
/// Used by tag 101 (transaction broadcast).
pub fn encode_chain_response_nullable_string(
    request_id: &str,
    response_tag: u8,
    result: Result<Option<&str>, &str>,
) -> Vec<u8> {
    let mut buf = Vec::with_capacity(64);
    encode_envelope(&mut buf, request_id, response_tag);
    match result {
        Ok(maybe_str) => {
            encode_result_ok(&mut buf);
            match maybe_str {
                None => encode_option_none(&mut buf),
                Some(s) => {
                    encode_option_some(&mut buf);
                    encode_string(&mut buf, s);
                }
            }
        }
        Err(reason) => encode_generic_error(&mut buf, reason),
    }
    buf
}

fn encode_chain_error_for_request(request_id: &str, request_tag: u8, reason: &str) -> Vec<u8> {
    match request_tag {
        TAG_CHAIN_HEAD_HEADER_REQ => {
            encode_chain_response_nullable_hex(request_id, TAG_CHAIN_HEAD_HEADER_RESP, Err(reason))
        }
        TAG_CHAIN_HEAD_BODY_REQ => encode_chain_response_operation_started(
            request_id,
            TAG_CHAIN_HEAD_BODY_RESP,
            Err(reason),
        ),
        TAG_CHAIN_HEAD_STORAGE_REQ => encode_chain_response_operation_started(
            request_id,
            TAG_CHAIN_HEAD_STORAGE_RESP,
            Err(reason),
        ),
        TAG_CHAIN_HEAD_CALL_REQ => encode_chain_response_operation_started(
            request_id,
            TAG_CHAIN_HEAD_CALL_RESP,
            Err(reason),
        ),
        TAG_CHAIN_HEAD_UNPIN_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_HEAD_UNPIN_RESP, Some(reason))
        }
        TAG_CHAIN_HEAD_CONTINUE_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_HEAD_CONTINUE_RESP, Some(reason))
        }
        TAG_CHAIN_HEAD_STOP_OP_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_HEAD_STOP_OP_RESP, Some(reason))
        }
        TAG_CHAIN_SPEC_GENESIS_HASH_REQ => {
            encode_chain_response_hex(request_id, TAG_CHAIN_SPEC_GENESIS_HASH_RESP, Err(reason))
        }
        TAG_CHAIN_SPEC_CHAIN_NAME_REQ => {
            encode_chain_response_string(request_id, TAG_CHAIN_SPEC_CHAIN_NAME_RESP, Err(reason))
        }
        TAG_CHAIN_SPEC_PROPERTIES_REQ => {
            encode_chain_response_string(request_id, TAG_CHAIN_SPEC_PROPERTIES_RESP, Err(reason))
        }
        TAG_CHAIN_TX_BROADCAST_REQ => encode_chain_response_nullable_string(
            request_id,
            TAG_CHAIN_TX_BROADCAST_RESP,
            Err(reason),
        ),
        TAG_CHAIN_TX_STOP_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_TX_STOP_RESP, Some(reason))
        }
        _ => crate::protocol::encode_jsonrpc_send_error(request_id),
    }
}

/// Encode a chain-head follow event notification from raw JSON-RPC text.
pub fn encode_chain_follow_json_event(request_id: &str, json_rpc: &str) -> Option<Vec<u8>> {
    parse_chain_head_json_rpc(json_rpc).map(|event| encode_chain_head_event(request_id, &event))
}

/// Encode a synthetic follow stop event for unsupported/disconnected chains.
pub fn encode_chain_follow_stop(request_id: &str) -> Vec<u8> {
    encode_chain_head_event(request_id, &ChainHeadEvent::Stop)
}

/// Encode a chain RPC error using the correct response tag for `request_tag`.
pub fn encode_chain_rpc_error(request_id: &str, request_tag: u8, reason: &str) -> Vec<u8> {
    encode_chain_error_for_request(request_id, request_tag, reason)
}

/// Encode a chain RPC response from raw JSON-RPC text using the correct
/// chain protocol envelope for `request_tag`.
pub fn encode_chain_rpc_json_response(
    request_id: &str,
    request_tag: u8,
    json_rpc: &str,
) -> Vec<u8> {
    let root: serde_json::Value = match serde_json::from_str(json_rpc) {
        Ok(value) => value,
        Err(_) => {
            return encode_chain_error_for_request(
                request_id,
                request_tag,
                "invalid json-rpc response",
            )
        }
    };

    if let Some(reason) = root
        .get("error")
        .and_then(|error| error.get("message"))
        .and_then(|message| message.as_str())
    {
        return encode_chain_error_for_request(request_id, request_tag, reason);
    }

    let Some(result) = root.get("result") else {
        return encode_chain_error_for_request(request_id, request_tag, "missing json-rpc result");
    };

    match request_tag {
        TAG_CHAIN_HEAD_HEADER_REQ => {
            if result.is_null() {
                encode_chain_response_nullable_hex(request_id, TAG_CHAIN_HEAD_HEADER_RESP, Ok(None))
            } else if let Some(hex) = result.as_str() {
                let bytes = hex_to_bytes(hex);
                encode_chain_response_nullable_hex(
                    request_id,
                    TAG_CHAIN_HEAD_HEADER_RESP,
                    Ok(Some(bytes.as_slice())),
                )
            } else {
                encode_chain_error_for_request(request_id, request_tag, "invalid header result")
            }
        }
        TAG_CHAIN_HEAD_BODY_REQ => {
            if result.is_null() {
                encode_chain_response_operation_started(
                    request_id,
                    TAG_CHAIN_HEAD_BODY_RESP,
                    Ok(None),
                )
            } else if let Some(operation_id) = result.as_str() {
                encode_chain_response_operation_started(
                    request_id,
                    TAG_CHAIN_HEAD_BODY_RESP,
                    Ok(Some(operation_id)),
                )
            } else {
                encode_chain_error_for_request(request_id, request_tag, "invalid body result")
            }
        }
        TAG_CHAIN_HEAD_STORAGE_REQ => {
            if result.is_null() {
                encode_chain_response_operation_started(
                    request_id,
                    TAG_CHAIN_HEAD_STORAGE_RESP,
                    Ok(None),
                )
            } else if let Some(operation_id) = result.as_str() {
                encode_chain_response_operation_started(
                    request_id,
                    TAG_CHAIN_HEAD_STORAGE_RESP,
                    Ok(Some(operation_id)),
                )
            } else {
                encode_chain_error_for_request(request_id, request_tag, "invalid storage result")
            }
        }
        TAG_CHAIN_HEAD_CALL_REQ => {
            if result.is_null() {
                encode_chain_response_operation_started(
                    request_id,
                    TAG_CHAIN_HEAD_CALL_RESP,
                    Ok(None),
                )
            } else if let Some(operation_id) = result.as_str() {
                encode_chain_response_operation_started(
                    request_id,
                    TAG_CHAIN_HEAD_CALL_RESP,
                    Ok(Some(operation_id)),
                )
            } else {
                encode_chain_error_for_request(request_id, request_tag, "invalid call result")
            }
        }
        TAG_CHAIN_HEAD_UNPIN_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_HEAD_UNPIN_RESP, None)
        }
        TAG_CHAIN_HEAD_CONTINUE_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_HEAD_CONTINUE_RESP, None)
        }
        TAG_CHAIN_HEAD_STOP_OP_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_HEAD_STOP_OP_RESP, None)
        }
        TAG_CHAIN_SPEC_GENESIS_HASH_REQ => {
            if let Some(hex) = result.as_str() {
                let bytes = hex_to_bytes(hex);
                encode_chain_response_hex(
                    request_id,
                    TAG_CHAIN_SPEC_GENESIS_HASH_RESP,
                    Ok(bytes.as_slice()),
                )
            } else {
                encode_chain_error_for_request(
                    request_id,
                    request_tag,
                    "invalid genesis hash result",
                )
            }
        }
        TAG_CHAIN_SPEC_CHAIN_NAME_REQ => {
            if let Some(name) = result.as_str() {
                encode_chain_response_string(request_id, TAG_CHAIN_SPEC_CHAIN_NAME_RESP, Ok(name))
            } else {
                encode_chain_error_for_request(request_id, request_tag, "invalid chain name result")
            }
        }
        TAG_CHAIN_SPEC_PROPERTIES_REQ => {
            let properties = serde_json::to_string(result).unwrap_or_else(|_| "{}".to_string());
            encode_chain_response_string(
                request_id,
                TAG_CHAIN_SPEC_PROPERTIES_RESP,
                Ok(properties.as_str()),
            )
        }
        TAG_CHAIN_TX_BROADCAST_REQ => {
            if result.is_null() {
                encode_chain_response_nullable_string(
                    request_id,
                    TAG_CHAIN_TX_BROADCAST_RESP,
                    Ok(None),
                )
            } else if let Some(operation_id) = result.as_str() {
                encode_chain_response_nullable_string(
                    request_id,
                    TAG_CHAIN_TX_BROADCAST_RESP,
                    Ok(Some(operation_id)),
                )
            } else {
                encode_chain_error_for_request(
                    request_id,
                    request_tag,
                    "invalid transaction result",
                )
            }
        }
        TAG_CHAIN_TX_STOP_REQ => {
            encode_chain_response_void(request_id, TAG_CHAIN_TX_STOP_RESP, None)
        }
        _ => crate::protocol::encode_jsonrpc_send_error(request_id),
    }
}