Skip to content

CIP-0103 amend ledgerApi specification #173

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexmatson-da wants to merge 2 commits into
base: main
Choose a base branch
from
Open

CIP-0103 amend ledgerApi specification #173

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7e5c671
CIP-0103: update ledgerApi specification
alexmatson-da Mar 4, 2026
fa4b626
include headers
alexmatson-da Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 24 additions & 10 deletions cip-0103/cip-0103.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -291,22 +291,31 @@ 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,
headers: 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.
- `headers`: (optional) Additional HTTP headers to include with the request.

##### 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.
Expand Down Expand Up @@ -491,6 +500,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)
Expand All @@ -508,3 +521,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-10**: Amendment to the `ledgerApi` method specification.