From 7e5c6716c78fd39ccbd31681aac18a6a9a6a9957 Mon Sep 17 00:00:00 2001 From: Alex Matson Date: Wed, 4 Mar 2026 14:07:26 -0500 Subject: [PATCH 1/2] CIP-0103: update ledgerApi specification --- cip-0103/cip-0103.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/cip-0103/cip-0103.md b/cip-0103/cip-0103.md index 5639aaa5..11a164c8 100644 --- a/cip-0103/cip-0103.md +++ b/cip-0103/cip-0103.md @@ -177,7 +177,7 @@ Overview of supported methods: | getPrimaryAccount | Account | Single Account that is subject to the dApp | | signMessage | string | Signs an arbitrary string | | prepareExecute | Void | Prepares, signs, and executes the commands | -| ledgerApi | string | Proxies Ledger API | +| ledgerApi | object | Proxies Ledger API | Overview of supported events: @@ -291,22 +291,29 @@ This method returns void, and once the commands are passed the preparation stage ##### ledgerApi -Enables submitting requests to the validator node's JSON Ledger API associated with the account. The requests are authenticated to read as the party associated with the account. The request parameter defines the method, resource, and, depending on the method, a body. The body and response are generic and correspond to the expected Ledger API type, encoded as a JSON `string`. +Enables submitting requests to the validator node's JSON Ledger API associated with the account. The requests are authenticated to read as the party associated with the account. ```typescript -// LedgerApiRequest -{ - requestMethod: string, // GET, POST, PUT, DELETE +type LedgerApiRequest = { + requestMethod: "get" | "post" | "put" | "delete" | "patch", resource: string, - body: string + path: object | undefined, + query: object | undefined, + body: object | undefined, } -// LedgerApiResponse -{ - response: string -} +// responses are returned exactly according to the OpenAPI spec defining the JSON Ledger API +type LedgerApiResponse = object ``` +Note the following assumptions about the request arguments: + +- `requestMethod`: Any HTTP method supported by the Ledger API, in all lowercase. +- `resource`: Corresponds to the path of the Ledger API operation, as defined by the OpenAPI document. This may contain string templated path parameters delimited with `{}`. The template is resolved by the `path` request object. +- `path`: (optional) A map of values whose keys correspond to path parameters for a given Ledger API operation. +- `query`: (optional) A map of values whose keys correspond to additional query parameters for a given Ledger API operation. +- `body`: (optional) A map of values corresponding to the request body submitted for a given Ledger API operation. + ##### accountsChanged Carries a list of accounts (see `listAccounts` for type definition) that the user has access to. A wallet provider **MUST** at least include all accounts that changed. @@ -491,6 +498,10 @@ Normative definition of the synchronous and asynchronous dApp API - dApp API Specification (Synchronous): [OpenRPC JSON](https://github.com/hyperledger-labs/splice-wallet-kernel/blob/main/api-specs/openrpc-dapp-api.json) - dApp API Specification (Asynchronous): [OpenRPC JSON](https://github.com/hyperledger-labs/splice-wallet-kernel/blob/main/api-specs/openrpc-dapp-remote-api.json) +Specification for the Ledger JSON API. Refer here to determine request/response bodies for the `ledgerApi` dApp API method. Note that the spec linked below is for Canton 3.5.x. Definitions may vary between Canton versions, so use the specification corresponding to the version supported by the node provider. + +- Ledger JSON API (v3.5): [OpenAPI YAML](https://docs.digitalasset.com/build/3.5/explanations/json-api/index.html) + ### Reference Implementations - Provider: [NPM package](https://www.npmjs.com/package/@canton-network/core-splice-provider) | [GitHub source](https://github.com/hyperledger-labs/splice-wallet-kernel) @@ -508,3 +519,4 @@ Normative definition of the synchronous and asynchronous dApp API * **2025-11-28**: Initial draft of the proposal. * **2026-01-29**: CIP Approved. +* **2026-03-05**: Amendment to the `ledgerApi` method specification. \ No newline at end of file From fa4b6260e8104706302881828d4cdabca571a12e Mon Sep 17 00:00:00 2001 From: Alex Matson Date: Tue, 10 Mar 2026 09:08:28 -0400 Subject: [PATCH 2/2] include headers --- cip-0103/cip-0103.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cip-0103/cip-0103.md b/cip-0103/cip-0103.md index 11a164c8..f3b59a42 100644 --- a/cip-0103/cip-0103.md +++ b/cip-0103/cip-0103.md @@ -300,6 +300,7 @@ type LedgerApiRequest = { path: object | undefined, query: object | undefined, body: object | undefined, + headers: object | undefined } // responses are returned exactly according to the OpenAPI spec defining the JSON Ledger API @@ -313,6 +314,7 @@ Note the following assumptions about the request arguments: - `path`: (optional) A map of values whose keys correspond to path parameters for a given Ledger API operation. - `query`: (optional) A map of values whose keys correspond to additional query parameters for a given Ledger API operation. - `body`: (optional) A map of values corresponding to the request body submitted for a given Ledger API operation. +- `headers`: (optional) Additional HTTP headers to include with the request. ##### accountsChanged @@ -519,4 +521,4 @@ Specification for the Ledger JSON API. Refer here to determine request/response * **2025-11-28**: Initial draft of the proposal. * **2026-01-29**: CIP Approved. -* **2026-03-05**: Amendment to the `ledgerApi` method specification. \ No newline at end of file +* **2026-03-10**: Amendment to the `ledgerApi` method specification. \ No newline at end of file