digital-asset / digital-asset/canton

[Docs] Add comprehensive documentation for External Calls feature

Open
#643 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Scala
Stars
143
Forks
55
Avg merge
2d 9h
Merged PRs (30d)
28

Description

With the recent introduction of external calls (see ExtensionServiceConfig), we need to provide comprehensive documentation for developers and operators prior to the feature release.

This issue covers writing end-to-end usage guides, language references, and security guidelines.

Definition of Done

Please ensure the documentation covers the following areas:

  • End-to-End Guide: A step-by-step tutorial or workflow showing how to configure and use external calls from end to end.
  • Language Reference: Reference documentation for all new Daml keywords such as externalCall (syntax, arguments, and return types).
  • Operational & Security Assumptions: Clear documentation on critical assumptions regarding security and correctness, specifically:
  • Determinism: External services must produce deterministic results.
  • Topology & Connectivity: Which participant nodes need to be connected to an external service.
  • Trust Model: Trust assumptions between participant nodes and their connected external services (and vice versa).

cc @angelol

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the ExtensionServiceConfig implementation and the existing external-call entry points, then trace how externalCall is configured and used. Done means published documentation with an end-to-end workflow, complete keyword syntax and type details, and explicit determinism, connectivity, trust, security, and correctness assumptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
scala
Domain
distributed-systems, documentation, security
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.