feat(rpc): add IPC call

[mohanson]

What is changed and how it works?

What's Changed:

Added an ipc_call method in jsonrpc. The method is described in detail in rpc/src/module/ipc.rs's comments.

/// Call the ipc method in the script.
///
/// ## Params
///
/// * script_locator:
///     - out_point - Reference to the cell by transaction hash and output index.
///     - type_id_args - Reference to the cell by type id type script args.
/// * req:
///     - version - IPC protocol version. Default is 0.
///     - method_id - IPC protocol method id. Default is 0.
///     - payload_format - The format of payload.
///     - payload - Payload.
/// * env: The transaction environment that the ipc script depends on. The script specified by script_group_type + script_hash will be executed, but the script binary will be replaced by the ipc script.
///     - tx - The transaction.
///     - script_group_type - Script group type.
///     - script_hash - Script hash.
///
/// ## Returns
///
/// * version - IPC protocol version. Default is 0.
/// * error_code - IPC error code.
/// * payload_format - The format of payload.
/// * payload - Payload.
///
/// ## Examples
///
/// Request
///
/// ```json
/// {
///     "id": 2,
///     "jsonrpc": "2.0",
///     "method": "ipc_call",
///     "params": [
///         {
///             "out_point": {
///                 "tx_hash": "0x4e75e1d4dddc0efe5e028168f627e3af436f1002b61038d695b24aa8441ffaf5",
///                 "index": "0x0"
///             }
///         },
///         {
///             "version": "0x0",
///             "method_id": "0x0",
///             "payload_format": "json",
///             "payload": {
///                 "SyscallLoadScript": {}
///             }
///         },
///         {
///             "tx": {
///                 "version": "0x0",
///                 "cell_deps": [
///                     {
///                         "out_point": {
///                             "tx_hash": "0xe7db03de9c534cb63d951f5378d5a4fbf43a2ebf5e48cb626562d188a3697772",
///                             "index": "0x0"
///                         },
///                         "dep_type": "dep_group"
///                     }
///                 ],
///                 "header_deps": [],
///                 "inputs": [
///                     {
///                         "since": "0x0",
///                         "previous_output": {
///                             "tx_hash": "0x953d1a4b95cefca9588b6d0bf7e97084bb51010ce87d1bcbe65c0ccd621781b8",
///                             "index": "0x0"
///                         }
///                     }
///                 ],
///                 "outputs": [],
///                 "outputs_data": [],
///                 "witnesses": [
///                     "0x55000000100000005500000055000000410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
///                 ]
///             },
///             "script_group_type": "lock",
///             "script_hash": "0x0b1bae4beaf456349c63c3ce67491fc75a1276d7f9eedd7ea84d6a77f9f3f5f7"
///         }
///     ]
/// }
/// ```
///
/// Response
///
/// ```json
/// {
///     "jsonrpc": "2.0",
///     "result": {
///         "error_code": "0x0",
///         "payload": {
///             "SyscallLoadScript": "0x490000001000000030000000310000009bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8011400000075178f34549c5fe9cd1a0c57aebd01e7ddf9249e"
///         },
///         "payload_format": "json",
///         "version": "0x0"
///     }
///     "id": 2
/// }
/// 

Here are some additional points to note:

• Allow calling all syscalls in ipc script, such as exec and spawn.
• How to write an ipc script? Here is a simple example. https://github.com/libraries/ipc/blob/master/ipc_test/src/ipc_test.rs
• There are a few things that are not done yet, I plan to submit them using another PRs
  • Add integration tests. I use python to write test cases during the development stage, I need more time to rewritten it in Rust., @gpBlockchain is responsible for migrating integration testing to project https://github.com/cryptape/ckb-py-integration-test

Check List

Tests

• Unit test
• Integration test
• Manual test (add detailed scripts or steps below)
• No code ci-runs-only: [ quick_checks,linters ]

Release note

Note: Add a note under the PR title in the release note.

[eval-exec]

Please execute make gen-rpc-doc

[mohanson]

Please execute make gen-rpc-doc

Done

[eval-exec]

Maybe we should change the payload's type to String instead of serde_json::Value?

[mohanson]

According to the design document, Payload needs to support two formats. The first is json object, for example:

{
  "Payload": {
    "MethodName": { "Parameter": "Value" } 
  }
}

The second is Hex mode, for example

{
  "Payload": "0x0000000001111111122222..."
}

It seems that only serde_json::Value can be used to define its type.

[Copilot]

Pull Request Overview

This PR adds IPC call functionality to the RPC module by introducing a new ckb-ipc utility crate, updating the RPC service builder to support the IPC module, and extending documentation and tests accordingly.

• Added a new ckb-ipc module with VLQ encoding/decoding utilities, pipe communication, packet definitions, and error types.
• Extended the RPC configuration, service builder, and documentation to support the new IPC module.
• Updated workspace and dependency configurations to include the new ckb-ipc module.

Reviewed Changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
util/ipc/src/vlq.rs	Implements VLQ encoding/decoding functions for IPC messages
util/ipc/src/pipe.rs	Adds a bidirectional pipe implementation for IPC communication
util/ipc/src/packet.rs	Defines IPC packet structures and serialization methods
util/ipc/src/lib.rs	Re-exports IPC components
util/ipc/src/error.rs	Implements custom error types for IPC
util/app-config/src/configs/rpc.rs	Introduces IPC module support in the configuration
script/src/syscalls/mod.rs	Adds syscall id constants for IPC-related operations
rpc/src/tests/setup.rs	Integrates IPC module enablement into the RPC test suite
rpc/src/service_builder.rs	Adds enable_ipc method and related changes to include IPC RPC methods
rpc/src/module/mod.rs	Exposes new IPC module and related RPC method definitions
rpc/src/module/indexer.rs	Adjusts visibility of IndexerRpcImpl affecting module exposure
rpc/src/error.rs	Adds error codes for IPC-related errors
rpc/README.md	Updates documentation with IPC module details and examples
(Other files)	Workspace and dependency updates to include the new ckb-ipc module

Comments suppressed due to low confidence (3)

util/ipc/src/pipe.rs:84

• [nitpick] Consider using a more descriptive error message for the missing receiver channel, e.g., 'Receiver channel not available', to aid debugging.

.rx.as_ref().ok_or_else(|| Error::new(ErrorKind::Other, "channel is not found"))?

util/ipc/src/pipe.rs:110

• [nitpick] Consider revising the error message to clearly indicate that the sender channel is missing, for example, 'Sender channel not available'.

.tx.as_mut().ok_or_else(|| Error::new(ErrorKind::Other, "channel is not found"))?

rpc/src/module/indexer.rs:887

• The visibility of IndexerRpcImpl was changed from 'pub(crate)' to 'pub'. Please ensure this change is intentional to avoid exposing internal implementation details.

pub struct IndexerRpcImpl {

[gpBlockchain]

LGTM

[chenyukang]

any specific reason to don't use chain call style here?

[mohanson]

Here I need to clone a copy of indexer_rpc_impl, which cannot be achieved using chain call.

[chenyukang]

seems from the code, if IPC module is not enabled, ipc_script_data_by_type_id_args will never be called here.
it's not necessary to add a RPCError::IPCIndexerIsDisabled code for it.

[chenyukang]

never mind, it's not IPC module here.

[chenyukang]

so if IPC module is enabled, it will require Index module required, could we just validate this rule when parsed config file.
otherwise user can only figure out this rule when error happened.

[mohanson]

When the script_locator parameter of ipc_call is type_id_args, it will depend on indexer;
When it is out_point, it will not depend on indexer.

So it can only be checked at runtime.

[chenyukang]

do we have a risk of overflow here?

[mohanson]

We are better off using the saturating_sub method

[chenyukang]

if timeout, whether we should report an error for endpoint?