Validator APIs

Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt

Use this file to discover all available pages before exploring further.

The Validator App exposing the validator APIs is part of a CN Validator or CN Supervalidator node. It connects to a Canton participant and provides the following functionality:

• It manages the Canton participant. Examples are automatically setting up the participant’s connection to Canton Network synchronizer, uploading DAR files, or managing daml parties.
• It automates core Canton Network daml workflows (except those related to supervalidator operations). Examples are minting validator rewards or executing recurring Canton Coin payments.
• It exposes a REST API for interacting with core Canton Network daml workflows (except those related to supervalidator operations). Examples are users programmatically managing their CN Wallet.

The different validator APIs and their purpose are listed below. Please see app_dev_openapi_conventions to learn about the API stability annotations and the contract payload encoding used in the OpenAPI specifications referenced below.

​

User wallet API

These endpoints are intended for users to programmatically interact with their wallets. Authorization: Authentication with a JWT token as described in app-auth, where the subject claim of the token is the user whose wallet the endpoint operates on. Backwards compatibility: External API with backwards compatibility guarantees. Reference: For details, see the wallet-external.yaml OpenAPI spec.

​

Splice Wallet Transfer Offers (deprecated)

Splice Wallet transfer offers are a legacy two-step workflow to transfer Canton Coin between users. They work as follows:

• The sender creates a Splice.Wallet.TransferOffer daml contract.
• The receiver accepts the offer, which immediately transfers the agreed coin.

This specific transfer offer workflow is deprecated in favor of the two-step workflow supported by Canton Coin implementation of the Canton Network Token Standard. Use the endpoints below to create and manage Splice Wallet transfer offers. Use the Ledger API directly to create and manage Canton Network Token Standard transfer offers.

​

Buying Traffic

Traffic on the CN Global Synchronizer is limited. Every validator has a budget of traffic that they can use, and daml transactions submitted to the synchronizer consume this traffic. A certain amount of traffic is free, additional traffic has to be bought with Canton Coin. Any user can buy traffic for any validator. Buying traffic is a multi-step process:

• The user creates a Splice.Wallet.BuyTrafficRequest daml contract.
• The users wallet automation picks up the request, burns the required coin from the users wallet, and increases the traffic budget of the target validator.

​

Internal user wallet API

These endpoints are used internally by the frontend of the Splice Wallet to interact with a user Canton Coin holdings. Authorization: Authentication with a JWT token as described in app-auth, where the subject claim of the token is the user whose wallet the endpoint operates on. Backwards compatibility: Internal API with no guarantees. Reference: For details, see the wallet-internal.yaml OpenAPI spec.

​

External Signing API

These endpoints are used to implement external signing of Canton Coin transactions. External signing is a Canton feature allows setting up a party such that transaction submissions must be signed by keys held outside of the participant. For more information on external signing in general, see the example, service protobuf definition, and readme in Canton. For the common case of wanting to set up an external party in a topology where the executing, preparing and confirming participant are the same node and that party should hold and transfer Canton Coin, the validator provides high-level APIs.

1. Use /v0/admin/external-party/topology/* to set up an external party
2. Use /v0/admin/external-party/setup-proposal to start setting up a Splice.Wallet.TransferPreapproval daml contract for the external party, which allows the party to send and receive Canton Coin without having to approve individual transfer offers.
3. Use /v0/admin/external-party/setup-proposal/* to finish setting up the transfer preapproval.
4. Use /v0/admin/external-party/transfer-preapproval/* to send Canton Coin to other parties.
5. Use /v0/admin/external-party/balance to check the balance of the external party.

Authorization: Authentication with any valid JWT token as described in app-auth. Backwards compatibility: Internal API with no guarantees. Reference: For details, see the validator-internal.yaml OpenAPI spec.

​

User management API

These endpoints are used to manage users hosted on the validator node. Users can either onboard themselves (/v0/register), or an admin may onboard arbitrary users (/v0/admin/users). Authorization: Authentication with a JWT token as described in app-auth, where the subject claim of the token is the validator operator user (for /v0/admin/users), or the user onboarding itself (for /v0/register). Backwards compatibility: Internal API with no guarantees. Reference: For details, see the validator-internal.yaml OpenAPI spec.

​

Validator management API

These endpoints are used by validator and supervalidator operators to manage their node. There is no need to call these endpoints unless instructed so by an operational manual, such as validator_operator or sv_operator. Authorization: Authentication with a JWT token as described in app-auth, where the subject claim of the token is the validator operator user. Backwards compatibility: Internal API with no guarantees. Reference: For details, see the validator-internal.yaml OpenAPI spec.

​

ANS API

These endpoints are used to interact with the Amulet Name Service (ANS). The (ANS) is a service that allows parties to buy a globally unique, human readable name for a time period mapped to their party. Users can request the creation of new ANS entries, upon which a subscription payment request is created. Once the payment is accepted in the wallet UI, the entry is created and the user can use it to refer to their party. Authorization: Authentication with a JWT token as described in app-auth, where the subject claim of the token is the user who is requesting the new ANS entry. Backwards compatibility: External API with backwards compatibility guarantees. Reference: For details, see the ans-external.yaml OpenAPI spec.

​

Scan Proxy API

These endpoints implement a BFT proxy to the public scan API. They have the same interfaces as the equally named endpoints in the public app_dev_scan_api. If the validator app is part of a CN Validator node, then each call to one of these endpoints is broadcast to the scan services of multiple supervalidator nodes, and the consensus result is returned to the caller. Use these endpoints instead of calling a scan service directly to avoid the need to trust a single supervalidator node. If the validator app is part of a CN Supervalidator node, then each call to one of these endpoints is simply forwarded to the scan service of the same node. Authorization: Authentication with any valid JWT token as described in app-auth. Backwards compatibility: See the corresponding endpoint in the app_dev_scan_api. Reference: For details, see the scan-proxy.yaml OpenAPI spec.