JSON Ledger API Migration to V2 guide

Migration guide for existing JSON Ledger API V1 users. JSON Ledger API V2 is a mirror of a gRPC Ledger API, thus it diverges substantially in some aspects from V1 API. Some v1 endpoints have simple corresponding v2 endpoints, while some need more calls or extra processing in order to simulate v1 behavior. Chapters below only point out the endpoints that should be used in v2. Consult the JSON Ledger API reference for exact details and usage.

​

Create a New Contract

• v1 endpoint: POST /v1/create
• v2 equivalent: POST /v2/commands/submit-and-wait

In the JsCommands request body, add a CreateCommand object (wrapping your v1 create payload) as an element of the commands array. There is also an alternate endpoint, /v2/commands/submit-and-wait-for-transaction, which can be used instead of /v2/commands/submit-and-wait to get more data about the processed transaction. To receive tree-equivalent data, set transactionFormat.transactionShape to TRANSACTION_SHAPE_LEDGER_EFFECTS in the request. (/v2/commands/submit-and-wait-for-transaction-tree is deprecated and slated for removal; do not migrate to it.)

​

Create a Contract with a Command ID

• v1 endpoint: POST /v1/create
  {
    "templateId": "...",
    "payload": { ... },
    "meta": { "commandId": "my-unique-id" }
  }
  
• v2 equivalent: POST /v2/commands/submit-and-wait
  {
    "commandId": "my-unique-id",
    "actAs": ["..."],
    "commands": [
        { "CreateCommand": { "templateId": "...", "createArguments": { ... } } }
    ]
  }
  

Same as Create a New Contract, except for where the command ID lives: in v1 it was the optional meta.commandId field, while in v2 commandId is a required top-level field of the JsCommands object.

​

Exercise by Contract ID

• v1 endpoint: POST /v1/exercise
• v2 equivalent: POST /v2/commands/submit-and-wait

In the JsCommands request body, add an ExerciseCommand object as an element of the commands array.

​

Exercise by Contract Key

• v1 endpoint: POST /v1/exercise (with a key in place of a contractId)
• v2 equivalent: POST /v2/commands/submit-and-wait

In the JsCommands request body, add an ExerciseByKeyCommand object as an element of the commands array. Contract keys in Canton 3.x require the template to be compiled against Daml-LF 2.3 or later (the default target is 2.2, which has no contract keys) and a synchronizer running protocol version 3.5 or later. Unlike v1, contract keys are non-unique: key uniqueness is not enforced.

​

Create and Exercise in the Same Transaction

• v1 endpoint: POST /v1/create-and-exercise
• v2 equivalent: POST /v2/commands/submit-and-wait

In the JsCommands request body, add a CreateAndExerciseCommand object as an element of the commands array.

​

Fetch Contract by Contract ID

• v1 endpoint: POST /v1/fetch
• v2 equivalent: POST /v2/events/events-by-contract-id

​

Fetch Contract by Key

• v1 endpoint: POST /v1/fetch
• v2 equivalent: no direct replacement

​

Get All Active Contracts

• v1 endpoint: GET /v1/query
• v2 equivalent: /v2/state/active-contracts

If you do not have desired ledger offset (activeAtOffset), obtain it via a call to /v2/state/ledger-end. There is also a streaming version of this endpoint in V2, which uses websockets. It provides better scalability for large results. Alternatively, POST /v2/state/active-contracts-page returns the active contract set in pages over plain HTTP.

​

Get All Active Contracts Matching a Given Query

• v1 endpoint: GET /v1/query
• v2 equivalent: no direct replacement
  • Option 1: use /v2/state/active-contracts and query result in client code
  • Option 2: use PQS (suitable for more demanding use cases)

​

Fetch Parties by Identifiers

• v1 endpoint: POST /v1/parties
• v2 equivalent: GET /v2/parties/<party-id>

​

Fetch All Known Parties

• v1 endpoint: GET /v1/parties
• v2 equivalent: GET /v2/parties

​

Allocate a New Party

• v1 endpoint: POST /v1/parties/allocate
• v2 equivalent: POST /v2/parties

​

Create a New User

• v1 endpoint: POST /v1/user/create
• v2 equivalent: POST /v2/users

​

Get Authenticated User Information

• v1 endpoint: GET /v1/user
• v2 equivalent: GET /v2/authenticated-user

​

Get Specific User Information

• v1 endpoint: POST /v1/user
• v2 equivalent: GET /v2/users/<user-id>

​

Delete Specific User

• v1 endpoint: POST /v1/user/delete
• v2 equivalent: DELETE /v2/users/<user-id>

​

List Users

• v1 endpoint: GET /v1/users
• v2 equivalent: GET /v2/users

​

Grant User Rights

• v1 endpoint: POST /v1/user/rights/grant
• v2 equivalent: POST /v2/users/<user-id>/rights

​

Revoke User Rights

• v1 endpoint: POST /v1/user/rights/revoke
• v2 equivalent: PATCH /v2/users/<user-id>/rights

​

List Authenticated User Rights

• v1 endpoint: GET /v1/user/rights
• v2 equivalent: GET /v2/users/<user-id>/rights

​

List Specific User Rights

• v1 endpoint: POST /v1/user/rights
• v2 equivalent: GET /v2/users/<user-id>/rights

​

List All DALF Packages

• v1 endpoint: GET /v1/packages
• v2 equivalent: GET /v2/packages

​

Download a DALF Package

• v1 endpoint: GET /v1/packages/<package-id>
• v2 equivalent: GET /v2/packages/<package-id>

​

Upload a DAR File

• v1 endpoint: POST /v1/packages
• v2 equivalent: POST /v2/dars

POST /v2/packages behaves identically; prefer /v2/dars.

​

Metering Report

• v1 endpoint: /v1/metering-report
• v2: no direct replacement, metering has been removed

​

Streaming API

​

Contracts Query Stream

• v1 endpoint: websocket /v1/stream/query
• v2 equivalent: websocket /v2/state/active-contracts

​

Fetch by Key Contracts Stream

• v1 endpoint: websocket /v1/stream/fetch
• v2: no direct replacement
  • Option 1: Use PQS
  • Option 2: Use /v2/state/active-contracts with client-side filtering (for infrequent queries).