Request metadata

This page describes Lasso RPC Core v0.5.0 metadata. It is opt-in and describes request execution, not an upstream-capacity or availability guarantee. Cloud RPC behavior and versions and evidence separate managed-service fields and deployment state from this Core contract.

Request metadata

Choose include_meta=body or include_meta=headers. The equivalent request header is X-Lasso-Include-Meta: body or headers; the query parameter takes precedence. Omit both to keep the ordinary response format.

curl 'http://localhost:4000/rpc/ethereum?include_meta=body' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Metadata fields

The released metadata builder removes top-level nil values. Nested attempt fields can still be null. Treat missing optional evidence as unknown, and tolerate additional fields.

Field	Meaning
`version`	Metadata schema version, currently `"1.0"`.
`request_id`	Opaque bounded correlation string, not a UUID-v4 contract.
`chain_id`	Numeric chain identity, not a chain-name `chain` field.
`profile_id`, `service_profile_id`	Effective and service file-profile identities; Core uses the same profile value for both.
`strategy`	Strategy name, such as `priority`, `fastest` or `load_balanced`.
`transport`	Request transport. The selected/executed channel identifies the upstream transport.
`candidate_providers`	Candidate labels considered by selection; not a dispatch log.
`selected_provider`	Optional selected provider identity (`id`) and `protocol`; no guaranteed name or region.
`executed_channel`	Optional channel that successfully executed the request.
`attempted_channels`	Ordered recorded success/error attempts, with channel identity and error category/code where present.
`selection_latency_ms`	Optional selection timing.
`upstream_latency_ms`	Optional measured upstream I/O timing.
`end_to_end_latency_ms`	Optional end-to-end timing; not `total_latency_ms`.
`lasso_overhead_ms`	Optional computed internal overhead.
`retries`	Pipeline retry counter; not a count of candidate providers or proof of exact dispatch count.
`circuit_breaker_state`	Reported circuit state, or `unknown`.
`head_policy`	Optional block protection evidence.

A channel identity contains profile, provider_id, instance_id, transport and route_generation. Instance/profile identifiers are opaque. The recorded attempt contains channel, outcome, category and code; successful attempts can have null category/code. See the released request context. Core generates an opaque request ID when needed; its fallback is 32 lowercase hexadecimal characters. Do not validate all IDs against that fallback shape or confuse this correlation ID with the JSON-RPC request’s id.

Body mode

include_meta=body adds lasso_meta beside result or error. Read the raw HTTP JSON response when you need this outer field: SDK methods commonly return only result and discard the envelope. These examples were generated with the v0.4.3 metadata builder and channel-history helpers, which are unchanged in v0.5.0. Provider identities and timings are fixed hermetic fixture inputs, not live performance measurements. The fixtures follow the released success and failover test setup.

Successful first attempt

{
  "id": 1,
  "jsonrpc": "2.0",
  "lasso_meta": {
    "version": "1.0",
    "strategy": "priority",
    "chain_id": 1,
    "transport": "http",
    "request_id": "fixture-request",
    "candidate_providers": [
      "primary:http",
      "backup:http"
    ],
    "circuit_breaker_state": "closed",
    "selection_latency_ms": 1.0,
    "upstream_latency_ms": 20.0,
    "end_to_end_latency_ms": 23.0,
    "lasso_overhead_ms": 3.0,
    "retries": 0,
    "selected_provider": {
      "id": "primary",
      "protocol": "http"
    },
    "attempted_channels": [
      {
        "code": null,
        "category": null,
        "channel": {
          "profile": "public",
          "provider_id": "primary",
          "instance_id": "fixture-primary",
          "transport": "http",
          "route_generation": 7
        },
        "outcome": "success"
      }
    ],
    "executed_channel": {
      "profile": "public",
      "provider_id": "primary",
      "instance_id": "fixture-primary",
      "transport": "http",
      "route_generation": 7
    },
    "profile_id": "public",
    "service_profile_id": "public"
  },
  "result": "0x64"
}

Successful failover

The failed primary and successful backup are both in attempted_channels. executed_channel identifies the backup. A candidate label alone would not establish either attempt.

{
  "id": 1,
  "jsonrpc": "2.0",
  "lasso_meta": {
    "version": "1.0",
    "strategy": "priority",
    "chain_id": 1,
    "transport": "http",
    "request_id": "fixture-request",
    "candidate_providers": [
      "primary:http",
      "backup:http"
    ],
    "circuit_breaker_state": "closed",
    "selection_latency_ms": 1.0,
    "upstream_latency_ms": 20.0,
    "end_to_end_latency_ms": 23.0,
    "lasso_overhead_ms": 3.0,
    "retries": 1,
    "selected_provider": {
      "id": "backup",
      "protocol": "http"
    },
    "attempted_channels": [
      {
        "code": -32000,
        "category": "server_error",
        "channel": {
          "profile": "public",
          "provider_id": "primary",
          "instance_id": "fixture-primary",
          "transport": "http",
          "route_generation": 7
        },
        "outcome": "error"
      },
      {
        "code": null,
        "category": null,
        "channel": {
          "profile": "public",
          "provider_id": "backup",
          "instance_id": "fixture-backup",
          "transport": "http",
          "route_generation": 7
        },
        "outcome": "success"
      }
    ],
    "executed_channel": {
      "profile": "public",
      "provider_id": "backup",
      "instance_id": "fixture-backup",
      "transport": "http",
      "route_generation": 7
    },
    "profile_id": "public",
    "service_profile_id": "public"
  },
  "result": "0x64"
}

Headers mode

include_meta=headers puts the same metadata object in X-Lasso-Meta as base64url-encoded JSON without padding. X-Lasso-Request-ID is the correlation ID. There is no promised X-Lasso-Latency header. Decode the header and handle its absence explicitly:

const encoded = response.headers.get('x-lasso-meta');
let metadata = null;
if (encoded) {
  const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
  const bytes = Uint8Array.from(atob(padded), char => char.charCodeAt(0));
  metadata = JSON.parse(new TextDecoder().decode(bytes));
}
console.log({requestId: response.headers.get('x-lasso-request-id'), metadata});

If the encoded metadata exceeds max_meta_header_bytes (default 4,096 bytes), Core omits X-Lasso-Meta and retains X-Lasso-Request-ID. Body mode avoids this metadata-header limit; it is not a promise of unlimited response size.

config :lasso, :observability, max_meta_header_bytes: 4096

Record evidence safely

Store the correlation ID, result/error, source revision and available timing and channel fields. Record missing metadata explicitly. A successful request proves neither independent operator redundancy nor that every candidate was attempted. Do not use candidate_providers as an upstream amplification counter.

Block protection metadata

These optional fields help diagnose Block regression protection. They are not required to enable protection or read several values at one block. When head_policy.policy is local, a protected latest-block response can include:

Field in `head_policy`	Meaning
`block_number`, `block_hash`, `block_age_ms`	The accepted block and its age.
`instance`, `generation`	The serving Lasso instance and application lifetime. A replacement application starts a new generation.
`minimum_height`	The local floor captured when the request started.
`recovery_height`	A best-effort recovery height hint, or `null` if none was available.
`recovery_gap_blocks`	The gap below the recovered height. A nonzero gap is allowed; hints are not mandatory minimums.

Compare nonoverlapping requests within the same service profile, chain, instance and generation to assess local protection. These fields do not prove that a particular number of peers received an update or predict recovery time. Global policies report policy=global and can include attributed chain-change observations. Their retained number/header responses have no executing upstream provider. Explicit-number/hash requests can legitimately have no head_policy object. State-read results do not independently attest which block the provider used to execute them. For correlation, use x-lasso-request-id, or x-request-id when no routing context was created. service_profile_id identifies the service profile and profile_id identifies the effective route. Core currently uses the same file-profile identity for both fields; treat them as opaque values. HTTP batch headers expose only one item’s routing context. Oversized metadata can be omitted. If complete per-request diagnostics are required, use individual HTTP requests and record missing metadata explicitly; this is a diagnostics choice, not a requirement for consistent reads.

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Request metadata