cardano-rpc: Add quickstart

Author: carbolymer

cardano-rpc/README.md

@@ -5,6 +5,143 @@
 The `cardano-rpc` package provides client and server haskell modules for gRPC interface of `cardano-node`.
 It implements [UTxO RPC](https://utxorpc.org/introduction) protobuf communication protocol specification.
 
+## Quickstart
+
+cardano-rpc is cardano-node's built-in gRPC interface, implementing the [UTxO RPC](https://utxorpc.org) spec.
+It is part of cardano-node itself: you enable it with a configuration flag, there is no extra service to run, and it is built, tested, and released together with cardano-node.
+Because UTxO RPC is a standard, the same client code also works against other servers that implement it, such as Dolos.
+It serves live chain data: the tip, UTxO queries, protocol parameters, and transaction evaluation and submission.
+It is not an indexer: there are no address-history queries; see [UTxO RPC v1beta spec coverage](#utxo-rpc-v1beta-spec-coverage) below for the full method status.
+The same configuration works against any network, from the local cluster used here to mainnet.
+
+### Prerequisites
+
+1. [Nix](https://nixos.org/download/) with flakes enabled; every command below fetches its tools through it.
+   The first invocations download the toolchain, which can take several minutes and a few gigabytes.
+2. A checkout of this repository, for the vendored proto files the CLI example and the TypeScript quickstart load:
+
+   ```bash
+   git clone https://github.com/IntersectMBO/cardano-api
+   cd cardano-api
+   ```
+
+Work through "Start a local cluster" and "Make your first call" below, then follow whichever quickstart in "Language examples" matches your stack.
+
+### Start a local cluster
+
+The cardano-testnet command below bundles the matching cardano-node and cardano-cli binaries, so one command is enough:
+
+```bash
+nix run github:IntersectMBO/cardano-node#cardano-testnet -- \
+  cardano --num-pool-nodes 1 --enable-grpc --output-dir /tmp/demo-cluster
+```
+
+This starts a testnet with a single block-producing cardano-node and its gRPC server enabled, and keeps running in the foreground until you press Ctrl+C.
+The cluster is ready once it logs `Testnet started`; open a second terminal for everything below.
+The cluster comes with funded test wallets, created at startup under `/tmp/demo-cluster/utxo-keys/utxo1` to `utxo3` (`utxo.skey`, `utxo.vkey`, `utxo.addr`); the transaction example below spends from `utxo1`.
+
+The RPC endpoint is a Unix socket at `/tmp/demo-cluster/socket/node1/rpc.sock`, next to cardano-node's IPC socket.
+Most gRPC tooling expects a TCP endpoint, so bridge the socket to `localhost:50051` with socat and leave it running (a second background process, alongside the cluster):
+
+```bash
+socat TCP-LISTEN:50051,fork,reuseaddr UNIX-CONNECT:/tmp/demo-cluster/socket/node1/rpc.sock
+```
+
+Every example below talks to `localhost:50051`.
+Connecting to a cardano-node that listens on TCP directly (`--grpc-listen-port`, see the configuration reference) works the same way, without the bridge; cardano-testnet gets the same ability with `--enable-grpc-http` in [#6685](https://github.com/IntersectMBO/cardano-node/pull/6685).
+
+> [!TIP]
+> To use your own binaries instead of the bundled ones, export `CARDANO_NODE` and `CARDANO_CLI` with their paths before running.
+
+> [!NOTE]
+> Flag names differ between the two CLIs: `cardano-testnet` takes `--enable-grpc`, `cardano-node` itself takes `--grpc-enable`.
+
+> [!WARNING]
+> The output directory must not exist from a previous run; genesis creation fails on leftovers (`Genesis output directory already exists`).
+> Run `rm -rf /tmp/demo-cluster` first when retrying, and make sure no cardano-node processes from an earlier attempt are still alive.
+>
+> Unix socket paths are capped at 108 bytes on Linux, and cardano-testnet fails at startup (`pokeSockAddr: path is too long`) when the output directory is nested too deep.
+> Keep `--output-dir` shallow, e.g. under `/tmp`.
+
+### Make your first call
+
+The CLI examples use the proto files vendored in this repository, so run them from the repository root.
+First enter a subshell that puts the tools on PATH (your prompt changes; run the commands below inside it).
+`.#quickstart` bundles every tool the whole quickstart needs, including both language examples below; the per-language shells (`.#quickstart-rust`, `.#quickstart-typescript`) are minimal alternatives if you only want one:
+
+```bash
+nix develop .#quickstart
+```
+
+or with `nix-shell` (using `cardano-rpc/quickstart/shell.nix`):
+
+```bash
+nix-shell cardano-rpc/quickstart/shell.nix
+```
+
+or fetch them ad hoc:
+
+```bash
+nix shell nixpkgs#buf nixpkgs#grpcurl nixpkgs#socat
+```
+
+Read the chain tip (the most recently adopted block) with [buf](https://buf.build/docs/installation):
+
+```bash
+buf curl \
+  --schema cardano-rpc/proto --protocol grpc --http2-prior-knowledge \
+  http://localhost:50051/utxorpc.v1beta.sync.SyncService/ReadTip
+```
+
+It prints the tip as JSON: slot, hash, height, and timestamp.
+Your values differ per run, and the tip advances between calls.
+
+Then read the protocol parameters (the chain's current fee, size, and cost limits):
+
+```bash
+buf curl \
+  --schema cardano-rpc/proto --protocol grpc --http2-prior-knowledge -d '{}' \
+  http://localhost:50051/utxorpc.v1beta.query.QueryService/ReadParams
+```
+
+With grpcurl instead:
+
+```bash
+grpcurl -plaintext \
+  -import-path cardano-rpc/proto -proto utxorpc/v1beta/sync/sync.proto \
+  localhost:50051 \
+  utxorpc.v1beta.sync.SyncService/ReadTip
+```
+
+### Language examples
+
+- **Rust**: first calls via the `utxorpc-spec` crate. See [quickstart/rust/README.md](quickstart/rust/README.md).
+- **TypeScript**: build and submit a transaction with MeshJS. See [quickstart/typescript/README.md](quickstart/typescript/README.md).
+
+### Clean up
+
+Stop the cluster and the socat bridge with Ctrl+C in their terminals, then remove the cluster directory:
+
+```bash
+rm -rf /tmp/demo-cluster
+```
+
+### Configuration reference
+
+The gRPC server is off by default.
+Enable it with `--grpc-enable` or `EnableRpc: true` in the cardano-node configuration; a node socket path must also be configured.
+
+Exactly one transport is active at a time:
+
+1. Unix socket (default): `rpc.sock` next to the node socket, or `--grpc-socket-path` / `RpcSocketPath`.
+2. HTTP/2 cleartext: `--grpc-listen-port` / `RpcListenPort`, optionally `--grpc-listen-address` / `RpcListenAddress` (default `127.0.0.1`).
+3. HTTP/2 with TLS: add `--grpc-tls-certificate` and `--grpc-tls-private-key` (`RpcTlsCertificateFile`, `RpcTlsPrivateKeyFile`), optionally repeatable `--grpc-tls-chain-certificate` (`RpcTlsChainCertificateFiles`).
+
+The three transports are mutually exclusive.
+TLS additionally requires a listen port, and its certificate and key must be set together; see the [Security](#security) section below before exposing an endpoint beyond localhost.
+
+Clients connect over TCP the same way as in the examples above: replace the Unix-socket connector or `unix://` target with the node's address and port.
+
 ## UTxO RPC v1beta spec coverage
 
 Methods marked ⬜ or ❌ are exposed by the server but respond with the `UNIMPLEMENTED` gRPC status.

cardano-rpc/quickstart/rust/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "cardano-rpc-quickstart"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+utxorpc-spec = { version = "0.19.2", default-features = false, features = [
+    "utxorpc-v1beta-sync",
+    "utxorpc-v1beta-query",
+] }
+tonic = "0.12.3"
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+hex = "0.4"

cardano-rpc/quickstart/rust/README.md

@@ -0,0 +1,47 @@
+# Rust quickstart
+
+The Rust path is the simplest one: the published [`utxorpc-spec`](https://crates.io/crates/utxorpc-spec) crate already ships tonic-generated v1beta bindings, so no proto files and no protoc are needed.
+The files below are already in this directory; no `cargo new` needed.
+
+> [!IMPORTANT]
+> Use `utxorpc-spec` directly, not the higher-level `utxorpc` SDK crate: that wrapper is hardwired to the older `utxorpc.v1alpha` services and cannot talk to cardano-rpc, which serves `v1beta` (v1beta packaging for the SDKs is tracked in utxorpc/spec#209).
+
+## Prerequisites
+
+Start a local cluster and the socat bridge as described in the main [Quickstart](../../README.md#quickstart).
+`Cargo.toml` and `src/main.rs` here connect to `localhost:50051`, the socat bridge address; no repository checkout is required otherwise, the project can live anywhere.
+
+## Run it
+
+Get `cargo`, `rustc` and `gcc` from the repository's flake (run from the repository root; it only provides the toolchain, so `cd` into this directory before running `cargo run` below):
+
+```bash
+nix develop .#quickstart-rust
+```
+
+or with `nix-shell` (using the `shell.nix` in this directory):
+
+```bash
+nix-shell
+```
+
+or fetch them ad hoc:
+
+```bash
+nix shell nixpkgs#cargo nixpkgs#rustc nixpkgs#gcc
+```
+
+Then, from this directory:
+
+```bash
+cargo run
+```
+
+Sample output (your values will differ):
+
+```
+Tip: slot 834 height 37 hash d76df679ffa93ca9d1224cff29b3479c7535a84ed3eb8c17ce1d34aaeb4e774d
+Protocol parameters: max_tx_size 16384 max_block_body_size 65536
+```
+
+tonic can also connect straight to the Unix socket through a custom connector (`Endpoint::connect_with_connector` with a `tokio::net::UnixStream`), skipping the socat bridge; the TCP form used here is the simpler one.

cardano-rpc/quickstart/rust/shell.nix

@@ -0,0 +1 @@
+{ pkgs ? import <nixpkgs> {} }: pkgs.mkShell { packages = with pkgs; [ cargo rustc gcc ]; }

cardano-rpc/quickstart/rust/src/main.rs

@@ -0,0 +1,46 @@
+use tonic::transport::Endpoint;
+
+use utxorpc_spec::utxorpc::v1beta::query::{
+    any_chain_params::Params as AnyChainParamsVariant, query_service_client::QueryServiceClient,
+    ReadParamsRequest,
+};
+use utxorpc_spec::utxorpc::v1beta::sync::{sync_service_client::SyncServiceClient, ReadTipRequest};
+
+const RPC_URL: &str = "http://localhost:50051";
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let channel = Endpoint::try_from(RPC_URL)?.connect().await?;
+
+    let mut sync_client = SyncServiceClient::new(channel.clone());
+    let mut query_client = QueryServiceClient::new(channel);
+
+    let tip = sync_client
+        .read_tip(ReadTipRequest {})
+        .await?
+        .into_inner()
+        .tip
+        .expect("ReadTip response always carries a tip");
+    println!(
+        "Tip: slot {} height {} hash {}",
+        tip.slot,
+        tip.height,
+        hex::encode(&tip.hash)
+    );
+
+    let params = query_client
+        .read_params(ReadParamsRequest { field_mask: None })
+        .await?
+        .into_inner()
+        .values
+        .and_then(|v| v.params)
+        .expect("cardano-rpc always returns Cardano parameters");
+    match params {
+        AnyChainParamsVariant::Cardano(pparams) => println!(
+            "Protocol parameters: max_tx_size {} max_block_body_size {}",
+            pparams.max_tx_size, pparams.max_block_body_size
+        ),
+    }
+
+    Ok(())
+}

cardano-rpc/quickstart/shell.nix

@@ -0,0 +1,2 @@
+# Covers every tool the cardano-rpc quickstart uses: the CLI examples plus both language examples.
+{ pkgs ? import <nixpkgs> {} }: pkgs.mkShell { packages = with pkgs; [ buf grpcurl socat cargo rustc gcc nodejs ]; }

cardano-rpc/quickstart/typescript/README.md

@@ -0,0 +1,61 @@
+# TypeScript quickstart
+
+Build and submit a transaction with [MeshJS](https://meshjs.dev), using cardano-rpc for UTxO queries, protocol parameters, and submission.
+The example sends 5 ADA from the cluster's `utxo1` wallet to the `utxo2` address.
+
+> [!IMPORTANT]
+> `@meshsdk/provider`'s off-the-shelf `U5CProvider` does not work against cardano-rpc: it is pinned to `@utxorpc/sdk` 0.6.x, which speaks the older `utxorpc.v1alpha` services, while cardano-rpc serves `v1beta` (v1beta packaging for the SDKs is tracked in utxorpc/spec#209).
+> Until the SDKs move to v1beta, [`cardano-rpc-provider.mjs`](cardano-rpc-provider.mjs) talks v1beta directly by loading the proto files at runtime.
+>
+> The provider is demo scaffolding for plain ADA and native-asset payments: it maps oversized numeric values onto the `int` variant only, and it does not surface datums, inline datums, or reference scripts.
+> Do not lift it unchanged into a dApp that touches script-locked UTxOs.
+
+## Prerequisites
+
+Start a local cluster and the socat bridge as described in the main [Quickstart](../../README.md#quickstart).
+It talks to the socat bridge at `localhost:50051`; `@grpc/grpc-js` can also target the Unix socket directly with a `unix://` address, skipping the bridge.
+
+## Run it
+
+Get Node.js from the repository's flake (run from the repository root; it only provides the toolchain, so `cd` into this directory before running the commands below):
+
+```bash
+nix develop .#quickstart-typescript
+```
+
+or with `nix-shell` (using the `shell.nix` in this directory):
+
+```bash
+nix-shell
+```
+
+or fetch it ad hoc:
+
+```bash
+nix shell nixpkgs#nodejs
+```
+
+Install the dependencies (pinned versions are in `package.json`):
+
+```bash
+npm install
+```
+
+[`cardano-rpc-provider.mjs`](cardano-rpc-provider.mjs) loads the proto files vendored in this repository, from `../../proto` relative to the current directory by default.
+Run the command below from this directory, or set `CARDANO_RPC_PROTO` to point at a `cardano-rpc/proto` directory elsewhere:
+
+```bash
+node send-lovelace.mjs
+```
+
+Sample output (your addresses and hashes will differ):
+
+```
+Sender address:    addr_test1vp0cg0r2w9xczav4g0txn6suy9z0g24er7h25eqk639hwfgcmtj72
+Recipient address: addr_test1vp0fsh3r9t3zmsfkv27qkwh66vudurnttpy80f8yjagxqyqz27px0
+Spendable UTxOs:   1
+Submitted tx: c8f9332364a81e687599a0b1c4599cd8bff0213c3a4c23a45a7d525ccc124018
+Confirmed: 5000000 lovelace landed at addr_test1vp0fsh3r9t3zmsfkv27qkwh66vudurnttpy80f8yjagxqyqz27px0 (c8f9332364a81e687599a0b1c4599cd8bff0213c3a4c23a45a7d525ccc124018#0)
+```
+
+See [`send-lovelace.mjs`](send-lovelace.mjs) for the full script: building the transaction with `MeshTxBuilder`, then confirming by polling the recipient's UTxOs for the new output.