User problem

Status: design proposal, not an announcement that CellScript already supports SSRI. A wallet or SDK developer encountering CellScript for the first time should be able to determine what a deployed Script offers, how a particular instance is configured, and how to construct a candidate transaction without first understanding compiler-internal metadata.

This issue designs an SSRI-compatible entry point and its boundary with the existing builder. The overall decision is tracked under Design workstreams below; it may result in implementation, a narrower scope, or deferral. SSRI need not become the sole entry point.

Build on existing mechanisms rather than reinventing trust

CellScript already has compiled ELF artefacts, typed interfaces, an independent checker, and ProtocolBundle for coordinating multi-contract transactions. #28/#29 check permitted implementations and participating roles; #80 additionally checks full Script args and concrete instances. These answer who may participate. The proposed SSRI entry point answers how tooling can discover and use them.

For example, an issuer may legitimately issue a credential of category 6 while an observer policy accepts only categories 1–5. SSRI may correctly report category 6, but that must not cause the observer to accept it. Discovery and admission remain separate steps.

Primary sources and observed discrepancies

• The original SSRI design describes method paths, Code/Script/Cell/Transaction environments, and off-chain Script execution.
• Pinned ckb-ssri-std @ 93f3a779. The method macro uses short method hashes and hex argv; the fallback distinguishes empty argv from a special off-chain VM version.
• The original design and this library describe the off-chain query syscall numbering differently. The README still contains TODOs for a unified entry point and attribute macros. Reviewers must establish the target server, client, fork/tag/commit, and actual golden vectors rather than synthesising an imaginary “latest SSRI”.
• The original design lists get_cell_deps, whereas the inspected ssri_methods! dispatch table only includes version/get_methods/has_methods. Any compatibility claim must enumerate supported methods rather than imply complete compatibility.

These are source-code observations; no SSRI server interoperability test has yet been performed.

Proposed first use cases and candidate scope

Start with non-financial credentials to avoid mixing asset economics into a generic entry point:

1. Query version and methods using a pinned code OutPoint/data hash; report the exact supported scope.
2. Query a concrete instance using a complete Script, reporting namespace, category, and serial number. A Code environment containing only a code hash must not be treated as a particular instance.
3. Return a candidate revocation transaction against a pinned transaction snapshot, then pass it through existing admission, live resolution, wallet signing, and full Script-group verification.

The first two can be investigated independently. The third depends on the overall decision and the candidate-transaction boundary. Do not add method names or return types to stable CellScript syntax before review. Do not force the generic SSRI UDT trait onto credentials; declare a custom namespace separately.

sequenceDiagram
  autonumber
  participant W as Wallet / SDK
  participant S as SSRI executor
  participant E as Pinned code and context
  participant B as CellScript admission / Builder
  participant C as CKB verification
  W->>S: Query methods and instance details
  S->>E: Execute in pinned environment
  E-->>W: Information + provenance (not transaction authorisation)
  W->>S: Request candidate transaction
  S-->>W: Candidate inputs / outputs / witnesses
  W->>B: Full candidate + user intent
  B->>B: Recheck implementation, instance, live Cells and limits
  B-->>W: Exact bytes to sign
  W->>C: Complete signed transaction
  C-->>W: Results of all required Script groups

Compare all three integration placements

Selection criteria: interoperability with actual consumers, verifiability of identity, behaviour under mismatched upgrades, binary size and runtime budgets, and maintainable complexity. No option is preselected.

Context and result contract

Each method must declare its minimum environment and what it reads. A Code method cannot conjure an instance; a Script method must bind the full code_hash/hash_type/args; a Cell method must bind an OutPoint and snapshot; a Transaction method must bind the complete transaction, input snapshot, network, and required dependencies. Methods requiring live chain queries must additionally specify query results and the observed tip. Identical code need not produce identical results across different chain states.

Result provenance should record at least the executing code hash/OutPoint, interface and method versions, complete context hash, request/response hashes, executor version, and consumed budget. Such records support source verification; a JSON field alone cannot establish authenticity or grant spending authority. The caller must verify the identity or independently replay the execution.

Cache keys must include code, instance, method, arguments, context, and chain snapshot. Invalidate on Type ID changes, consumed Cells, reorganisations, or input-snapshot changes. Do not cache information for all instances solely by code hash. Returned transactions must still be checked against the original signing intent, including amounts, recipients, fees, and capacity. The SSRI server must not hold private keys.

Encoding, error, and budget checklist

• Specify the method-path algorithm, byte order, hex/raw-byte argv boundary, missing/extra argument behaviour, Molecule schema, null values, and trailing-byte rules.
• A short method ID does not uniquely authenticate a complete signature. Detect collisions at publication; never silently change parameters or semantics under the same ID across versions.
• Distinguish unsupported method, insufficient context, malformed input, budget exceeded, stale snapshot, business-rule rejection, and unavailable host. An unknown method must not fall back to successful verification.
• Reconcile the SSRI limit=0 “return all” convention with total host budgets: an internal hard limit still applies. Exceeding it must fail explicitly or use a versioned pagination strategy; never silently truncate and claim completeness.
• Before testing, specify ceilings for method count, argument/response bytes, context reads/queries, VM cycles, host time, and memory. Numeric values await review and measurement; they are not implemented guarantees.
• Off-chain extension syscalls must not enter ordinary on-chain verification. The same-ELF option particularly needs evidence that dispatch cannot bypass the original verifier.

Incremental implementation and validation

1. Pin a reference server/client/source revision and minimal external consumer scenario with SSRI maintainers; retain byte-level vectors.
2. Write an independent native Rust reference contract for equivalent discovery/instance queries, using the same context and budgets as the baseline.
3. Run minimal experiments for all three placements; record whether an unmodified reference client can invoke each. Name every incompatibility.
4. Only after selection, design the CellScript generator/adapter and source→interface→builder mapping. Preserve existing CLI/ABI semantics and version extensions explicitly.
5. Introduce the candidate-transaction flow with pre-signing wallet checks; any byte or live-snapshot change requires fresh admission and signing.
6. Freeze the accepted boundary, provide a tutorial, offline reproductions, and review conclusions, then open explicitly scoped implementation deliverables.

Authoring direction — 2026-10-19

Apply the authoring requirements in #47/#48/#49 to the proposed discovery and construction interface. Review a declaration of named methods, typed parameters/results, required context, and named resource limits before freezing any public syntax. Derive discovery descriptions and client/builder bindings from one canonical interface contract where supported, rather than making authors repeat method signatures, positional limits, or compiler-internal view types at each call. Record every mapping that cannot preserve the selected SSRI protocol's semantics; generated convenience does not establish wire compatibility.

Keep code, concrete Script instance, Cell snapshot, and transaction context distinguishable in author-written examples. A convenient context object must not silently substitute code identity for full instance identity, choose a chain snapshot, or grant signing authority. Use structurally resolved fields and policies rather than encoding ordinary field references in opaque policy strings. Candidate construction must still expose user intent and pass the existing admission and signing checks.

For query/codec helpers, prefer direct reads when no view needs to be retained; use an explicit borrow scope only when its lifetime is meaningful. Target bounded non-escaping helper composition without promising it is already supported. A host response is bounded typed data with provenance to verify, not a borrowed on-chain Cell view or an owned resource. Nested results require their declared #48 codec and bounds; an off-chain SDK's allocation does not imply #47 on-chain heap support.

Before stable API review, show a complete discovery → instance query → candidate transaction example, including author declarations, generated consumer calls, reusable helpers, and malformed/stale-context rejection. Clearly label proposed syntax and unsupported cases. Evaluate the same author-facing workflow for all three placements; a same-ELF, companion, or adapter choice must not itself dictate the public spelling.

Relationship to existing issues

#28/#29/#80 continue to own admission. #47/#48/#49 are neither reopened nor deemed completed by this design. Fixed-size queries do not require a generic allocator. Nested dynamic on-chain results require the specific codec scope of #48; an off-chain host handling dynamic data does not imply corresponding on-chain CellScript support. Cell-collection transfers remain within #49, while owned dynamic collections are relevant to #47.

Closure criteria and questions for reviewers

• Review the complete discovery/instance/construction workflow against the [0.33][Runtime] Add bounded allocation-backed value collections and deterministic Map/Set #47/[0.33][ABI] Support bounded nested dynamic values with canonical codecs #48/[0.33][Runtime] Extend bounded Cell selection and correspondence for heterogeneous and dynamic data #49 authoring direction, including generated-client parity, named context and limits, helper lifetime boundaries, and explicit unsupported cases before stable API freeze.
• Chosen placement and trade-offs of rejected alternatives are explicit; external interoperability targets are pinned to exact versions.
• Per-method context, authorisation, encoding, error, budget, and caching rules are frozen.
• At least one independent-client interoperability experiment is documented; unimplemented candidate-transaction capabilities are clearly labelled.
• Adversarial cases above have test plans and assigned responsibilities; no privilege expansion in ordinary verification.
• The maintainer identifies implementation owners and records review dispositions; design closure is separate from implementation acceptance.

Hanssen, Retric, Guopeng, and other reviewers: which SSRI methods should come first? Can a companion ELF meet the expected semantics? Which specification or implementation governs current discrepancies? Which off-chain context information requires provenance or replay? If we only build an adapter, how should it be named to avoid misleading users? Mentioning reviewers here does not imply that they have reviewed or endorsed the proposal.

Design workstreams

Overall decision: #81. On-chain communication and lifecycle: #83. This issue is #82; it may undertake discovery/context experiments without waiting for general-purpose on-chain IPC.

Further reading

ProtocolBundle end-to-end tutorial.