gRPC Ledger API Reference

The specification for the services, methods, and messages for interacting with the gRPC-based Ledger API.

com/daml/ledger/api/scalapb/package.proto

com/daml/ledger/api/v2/admin/command_inspection_service.proto

CommandInspectionService, v2/admin

Status: experimental interface, will change before it is deemed production ready

The inspection service provides methods for the ledger administrator to look under the hood of a running system. In V2 Ledger API this service is not available.

GetCommandStatus method, v2/admin

Inquire about the status of a command. This service is used for debugging only. The command status is only tracked in memory and is not persisted. The service can be used to understand the failure status and the structure of a command. Requires admin privileges The service is alpha without backward compatibility guarantees.

CommandStatus message, v2/admin

started : google.protobuf.Timestamp

completed : google.protobuf.Timestamp

completion : com.daml.ledger.api.v2.Completion

state : CommandState

commands : com.daml.ledger.api.v2.Command (repeated)

request_statistics : RequestStatistics

updates : CommandUpdates

CommandUpdates message, v2/admin

created : Contract (repeated)

archived : Contract (repeated)

exercised : uint32

fetched : uint32

looked_up_by_key : uint32

Contract message, v2/admin

template_id : com.daml.ledger.api.v2.Identifier

The identifier of the template used to create the contract. The identifier uses the package-id reference format.

Required

contract_id : string

The contract’s ID

Required

contract_key : com.daml.ledger.api.v2.Value

The contract key, if defined

Optional

GetCommandStatusRequest message, v2/admin

command_id_prefix : string

optional filter by command id

state : CommandState

optional filter by state

limit : uint32

optional limit of returned statuses, defaults to 100

GetCommandStatusResponse message, v2/admin

command_status : CommandStatus (repeated)

RequestStatistics message, v2/admin

envelopes : uint32

request_size : uint32

recipients : uint32

CommandState enum, v2/admin

COMMAND_STATE_UNSPECIFIED

0

This value acts as wildcard in the queries

COMMAND_STATE_PENDING

1

COMMAND_STATE_SUCCEEDED

2

COMMAND_STATE_FAILED

3

com/daml/ledger/api/v2/admin/identity_provider_config_service.proto

IdentityProviderConfigService, v2/admin

Identity Provider Config Service makes it possible for participant node administrators to setup and manage additional identity providers at runtime.

This allows using access tokens from identity providers unknown at deployment time. When an identity provider is configured, independent IDP administrators can manage their own set of parties and users. Such parties and users have a matching identity_provider_id defined and are inaccessible to administrators from other identity providers. A user will only be authenticated if the corresponding JWT token is issued by the appropriate identity provider. Users and parties without identity_provider_id defined are assumed to be using the default identity provider, which is configured statically at the participant node’s deployment time.

The Ledger API uses the “iss” claim of a JWT token to match the token to a specific IDP. If there is no match, the default IDP is assumed.

The fields of request messages (and sub-messages) are marked either as Optional or Required:

  1. Optional denoting the client may leave the field unset when sending a request.

  2. Required denoting the client must set the field to a non-default value when sending a request.

An identity provider config resource is described by the IdentityProviderConfig message, An identity provider config resource, once it has been created, can be modified. In order to update the properties represented by the IdentityProviderConfig message use the UpdateIdentityProviderConfig RPC. The only fields that can be modified are those marked as Modifiable.

CreateIdentityProviderConfig method, v2/admin

Create a new identity provider configuration. The request will fail if the maximum allowed number of separate configurations is reached.

GetIdentityProviderConfig method, v2/admin

Get the identity provider configuration data by id.

UpdateIdentityProviderConfig method, v2/admin

Update selected modifiable attribute of an identity provider config resource described by the IdentityProviderConfig message.

ListIdentityProviderConfigs method, v2/admin

List all existing identity provider configurations.

DeleteIdentityProviderConfig method, v2/admin

Delete an existing identity provider configuration.

CreateIdentityProviderConfigRequest message, v2/admin

identity_provider_config : IdentityProviderConfig

Required

CreateIdentityProviderConfigResponse message, v2/admin

identity_provider_config : IdentityProviderConfig

DeleteIdentityProviderConfigRequest message, v2/admin

identity_provider_id : string

The identity provider config to delete. Required

DeleteIdentityProviderConfigResponse message, v2/admin

Does not (yet) contain any data.

Message has no fields.

GetIdentityProviderConfigRequest message, v2/admin

identity_provider_id : string

Required

GetIdentityProviderConfigResponse message, v2/admin

identity_provider_config : IdentityProviderConfig

IdentityProviderConfig message, v2/admin

identity_provider_id : string

The identity provider identifier Must be a valid LedgerString (as describe in value.proto). Required

is_deactivated : bool

When set, the callers using JWT tokens issued by this identity provider are denied all access to the Ledger API. Optional, Modifiable

issuer : string

Specifies the issuer of the JWT token. The issuer value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. Required Modifiable

jwks_url : string

The JWKS (JSON Web Key Set) URL. The Ledger API uses JWKs (JSON Web Keys) from the provided URL to verify that the JWT has been signed with the loaded JWK. Only RS256 (RSA Signature with SHA-256) signing algorithm is supported. Required Modifiable

audience : string

Specifies the audience of the JWT token. When set, the callers using JWT tokens issued by this identity provider are allowed to get an access only if the “aud” claim includes the string specified here Optional, Modifiable

ListIdentityProviderConfigsRequest message, v2/admin

Pagination is not required as the resulting data set is small enough to be returned in a single call

Message has no fields.

ListIdentityProviderConfigsResponse message, v2/admin

identity_provider_configs : IdentityProviderConfig (repeated)

UpdateIdentityProviderConfigRequest message, v2/admin

identity_provider_config : IdentityProviderConfig

The identity provider config to update. Required, Modifiable

update_mask : google.protobuf.FieldMask

An update mask specifies how and which properties of the IdentityProviderConfig message are to be updated. An update mask consists of a set of update paths. A valid update path points to a field or a subfield relative to the IdentityProviderConfig message. A valid update mask must:

  1. contain at least one update path,

  2. contain only valid update paths.

Fields that can be updated are marked as Modifiable. For additional information see the documentation for standard protobuf3’s google.protobuf.FieldMask. Required

UpdateIdentityProviderConfigResponse message, v2/admin

identity_provider_config : IdentityProviderConfig

Updated identity provider config

com/daml/ledger/api/v2/admin/object_meta.proto

ObjectMeta message, v2/admin

Represents metadata corresponding to a participant resource (e.g. a participant user or participant local information about a party).

Based on ObjectMeta meta used in Kubernetes API. See https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/generated.proto#L640

resource_version : string

An opaque, non-empty value, populated by a participant server which represents the internal version of the resource this ObjectMeta message is attached to. The participant server will change it to a unique value each time the corresponding resource is updated. You must not rely on the format of resource version. The participant server might change it without notice. You can obtain the newest resource version value by issuing a read request. You may use it for concurrent change detection by passing it back unmodified in an update request. The participant server will then compare the passed value with the value maintained by the system to determine if any other updates took place since you had read the resource version. Upon a successful update you are guaranteed that no other update took place during your read-modify-write sequence. However, if another update took place during your read-modify-write sequence then your update will fail with an appropriate error. Concurrent change control is optional. It will be applied only if you include a resource version in an update request. When creating a new instance of a resource you must leave the resource version empty. Its value will be populated by the participant server upon successful resource creation. Optional

annotations : ObjectMeta.AnnotationsEntry (repeated)

A set of modifiable key-value pairs that can be used to represent arbitrary, client-specific metadata. Constraints:

  1. The total size over all keys and values cannot exceed 256kb in UTF-8 encoding.

  2. Keys are composed of an optional prefix segment and a required name segment such that:

    • key prefix, when present, must be a valid DNS subdomain with at most 253 characters, followed by a ‘/’ (forward slash) character,

    • name segment must have at most 63 characters that are either alphanumeric ([a-z0-9A-Z]), or a ‘.’ (dot), ‘-’ (dash) or ‘_’ (underscore); and it must start and end with an alphanumeric character.

  3. Values can be any non-empty strings.

Keys with empty prefix are reserved for end-users. Properties set by external tools or internally by the participant server must use non-empty key prefixes. Duplicate keys are disallowed by the semantics of the protobuf3 maps. See: https://developers.google.com/protocol-buffers/docs/proto3#maps Annotations may be a part of a modifiable resource. Use the resource’s update RPC to update its annotations. In order to add a new annotation or update an existing one using an update RPC, provide the desired annotation in the update request. In order to remove an annotation using an update RPC, provide the target annotation’s key but set its value to the empty string in the update request. Optional Modifiable

ObjectMeta.AnnotationsEntry message, v2/admin

key : string

value : string

com/daml/ledger/api/v2/admin/package_management_service.proto

PackageManagementService, v2/admin

Status: experimental interface, will change before it is deemed production ready

Query the Daml-LF packages supported by the ledger participant and upload DAR files. We use ‘backing participant’ to refer to this specific participant in the methods of this API.

ListKnownPackages method, v2/admin

Returns the details of all Daml-LF packages known to the backing participant.

UploadDarFile method, v2/admin

Upload a DAR file to the backing participant. Depending on the ledger implementation this might also make the package available on the whole ledger. This call might not be supported by some ledger implementations. Canton could be an example, where uploading a DAR is not sufficient to render it usable, it must be activated first. This call may:

  • Succeed, if the package was successfully uploaded, or if the same package was already uploaded before.

  • Respond with a gRPC error

ValidateDarFile method, v2/admin

Performs the same checks that UploadDarFile call perform, but doesn’t upload the DAR and does not make it available on the whole ledger. This call may:

  • Succeed if the package is valid

  • Respond with a gRPC error if the package is not valid

ListKnownPackagesRequest message, v2/admin

Message has no fields.

ListKnownPackagesResponse message, v2/admin

package_details : PackageDetails (repeated)

The details of all Daml-LF packages known to backing participant. Required

PackageDetails message, v2/admin

package_id : string

The identity of the Daml-LF package. Must be a valid PackageIdString (as describe in value.proto). Required

package_size : uint64

Size of the package in bytes. The size of the package is given by the size of the daml_lf ArchivePayload. See further details in daml_lf.proto. Required

known_since : google.protobuf.Timestamp

Indicates since when the package is known to the backing participant. Required

name : string

Name of the package as defined by the package metadata

version : string

Version of the package as defined by the package metadata

UploadDarFileRequest message, v2/admin

dar_file : bytes

Contains a Daml archive DAR file, which in turn is a jar like zipped container for daml_lf archives. See further details in daml_lf.proto. Required

submission_id : string

Unique submission identifier. Optional, defaults to a random identifier.

UploadDarFileResponse message, v2/admin

A message that is received when the upload operation succeeded.

Message has no fields.

ValidateDarFileRequest message, v2/admin

Performs the same checks that UploadDarFileRequest would perform, but doesn’t upload the DAR.

dar_file : bytes

Contains a Daml archive DAR file, which in turn is a jar like zipped container for daml_lf archives. See further details in daml_lf.proto. Required

submission_id : string

Unique submission identifier. Optional, defaults to a random identifier.

ValidateDarFileResponse message, v2/admin

Message has no fields.

com/daml/ledger/api/v2/admin/participant_pruning_service.proto

ParticipantPruningService, v2/admin

Prunes/truncates the “oldest” transactions from the participant (the participant Ledger Api Server plus any other participant-local state) by removing a portion of the ledger in such a way that the set of future, allowed commands are not affected.

This enables:

  1. keeping the “inactive” portion of the ledger to a manageable size and

  2. removing inactive state to honor the right to be forgotten.

Prune method, v2/admin

Prune the ledger specifying the offset before and at which ledger transactions should be removed. Only returns when the potentially long-running prune request ends successfully or with an error.

PruneRequest message, v2/admin

prune_up_to : int64

Inclusive valid absolute offset (positive integer) up to which the ledger is to be pruned. By default the following data is pruned:

  1. All normal and divulged contracts that have been archived before prune_up_to.

  2. All transaction events and completions before prune_up_to

submission_id : string

Unique submission identifier. Optional, defaults to a random identifier, used for logging.

prune_all_divulged_contracts : bool

Prune all immediately and retroactively divulged contracts created before prune_up_to independent of whether they were archived before prune_up_to. Useful to avoid leaking storage on participant nodes that can see a divulged contract but not its archival.

Application developers SHOULD write their Daml applications such that they do not rely on divulged contracts; i.e., no warnings from using divulged contracts as inputs to transactions are emitted.

Participant node operators SHOULD set the prune_all_divulged_contracts flag to avoid leaking storage due to accumulating unarchived divulged contracts PROVIDED that:

  1. no application using this participant node relies on divulgence OR

  2. divulged contracts on which applications rely have been re-divulged after the prune_up_to offset.

PruneResponse message, v2/admin

Empty for now, but may contain fields in the future

Message has no fields.

com/daml/ledger/api/v2/admin/party_management_service.proto

PartyManagementService, v2/admin

This service allows inspecting the party management state of the ledger known to the participant and managing the participant-local party metadata.

The authorization rules for its RPCs are specified on the <RpcName>Request messages as boolean expressions over these facts:

  1. HasRight(r) denoting whether the authenticated user has right r and

  2. IsAuthenticatedIdentityProviderAdmin(idp) denoting whether idp is equal to the identity_provider_id of the authenticated user and the user has an IdentityProviderAdmin right.

If identity_provider_id is set to an empty string, then it’s effectively set to the value of access token’s ‘iss’ field if that is provided. If identity_provider_id remains an empty string, the default identity provider will be assumed.

The fields of request messages (and sub-messages) are marked either as Optional or Required:

  1. Optional denoting the client may leave the field unset when sending a request.

  2. Required denoting the client must set the field to a non-default value when sending a request.

A party details resource is described by the PartyDetails message, A party details resource, once it has been created, can be modified using the UpdatePartyDetails RPC. The only fields that can be modified are those marked as Modifiable.

GetParticipantId method, v2/admin

Return the identifier of the participant. All horizontally scaled replicas should return the same id. daml-on-kv-ledger: returns an identifier supplied on command line at launch time canton: returns globally unique identifier of the participant

GetParties method, v2/admin

Get the party details of the given parties. Only known parties will be returned in the list.

ListKnownParties method, v2/admin

List the parties known by the participant. The list returned contains parties whose ledger access is facilitated by the participant and the ones maintained elsewhere.

AllocateParty method, v2/admin

Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may:

  • Succeed, in which case the actual allocated identifier is visible in the response.

  • Respond with a gRPC error

daml-on-kv-ledger: suggestion’s uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars

UpdatePartyDetails method, v2/admin

Update selected modifiable participant-local attributes of a party details resource. Can update the participant’s local information for local parties.

UpdatePartyIdentityProviderId method, v2/admin

Update the assignment of a party from one IDP to another.

AllocatePartyRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

party_id_hint : string

A hint to the participant which party ID to allocate. It can be ignored. Must be a valid PartyIdString (as described in value.proto). Optional

local_metadata : ObjectMeta

Participant-local metadata to be stored in the PartyDetails of this newly allocated party. Optional

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the party is managed by the default identity provider or party is not hosted by the participant.

AllocatePartyResponse message, v2/admin

party_details : PartyDetails

GetParticipantIdRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin)

Message has no fields.

GetParticipantIdResponse message, v2/admin

participant_id : string

Identifier of the participant, which SHOULD be globally unique. Must be a valid LedgerString (as describe in value.proto).

GetPartiesRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

parties : string (repeated)

The stable, unique identifier of the Daml parties. Must be valid PartyIdStrings (as described in value.proto). Required

identity_provider_id : string

The id of the Identity Provider whose parties should be retrieved. Optional, if not set, assume the party is managed by the default identity provider or party is not hosted by the participant.

GetPartiesResponse message, v2/admin

party_details : PartyDetails (repeated)

The details of the requested Daml parties by the participant, if known. The party details may not be in the same order as requested. Required

ListKnownPartiesRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

page_token : string

Pagination token to determine the specific page to fetch. Using the token guarantees that parties on a subsequent page are all lexically greater than the last party on a previous page. Server does not store intermediate results between calls chained by a series of page tokens. As a consequence, if new parties are being added and a page is requested twice using the same token, more parties can be returned on the second call. Leave empty to fetch the first page. Optional

page_size : int32

Maximum number of results to be returned by the server. The server will return no more than that many results, but it might return fewer. If the page_size is 0, the server will decide the number of results to be returned. If the page_size exceeds the maximum supported by the server, an error will be returned. To obtain the server’s maximum consult the PartyManagementFeature descriptor available in the VersionService. Optional

identity_provider_id : string

The id of the Identity Provider whose parties should be retrieved. Optional, if not set, assume the party is managed by the default identity provider or party is not hosted by the participant.

ListKnownPartiesResponse message, v2/admin

party_details : PartyDetails (repeated)

The details of all Daml parties known by the participant. Required

next_page_token : string

Pagination token to retrieve the next page. Empty, if there are no further results.

PartyDetails message, v2/admin

party : string

The stable unique identifier of a Daml party. Must be a valid PartyIdString (as described in value.proto). Required

is_local : bool

true if party is hosted by the participant and the party shares the same identity provider as the user issuing the request. Optional

local_metadata : ObjectMeta

Participant-local metadata of this party. Optional, Modifiable

identity_provider_id : string

The id of the Identity Provider Optional, if not set, there could be 3 options:

  1. the party is managed by the default identity provider.

  2. party is not hosted by the participant.

  3. party is hosted by the participant, but is outside of the user’s identity provider.

UpdatePartyDetailsRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(party_details.identity_provider_id)

party_details : PartyDetails

Party to be updated Required, Modifiable

update_mask : google.protobuf.FieldMask

An update mask specifies how and which properties of the PartyDetails message are to be updated. An update mask consists of a set of update paths. A valid update path points to a field or a subfield relative to the PartyDetails message. A valid update mask must:

  1. contain at least one update path,

  2. contain only valid update paths.

Fields that can be updated are marked as Modifiable. An update path can also point to non-Modifiable fields such as ‘party’ and ‘local_metadata.resource_version’ because they are used:

  1. to identify the party details resource subject to the update,

  2. for concurrent change control.

An update path can also point to non-Modifiable fields such as ‘is_local’ as long as the values provided in the update request match the server values. Examples of update paths: ‘local_metadata.annotations’, ‘local_metadata’. For additional information see the documentation for standard protobuf3’s google.protobuf.FieldMask. For similar Ledger API see com.daml.ledger.api.v2.admin.UpdateUserRequest. Required

UpdatePartyDetailsResponse message, v2/admin

party_details : PartyDetails

Updated party details

UpdatePartyIdentityProviderIdRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin)

party : string

Party to update

source_identity_provider_id : string

Current identity provider id of the party

target_identity_provider_id : string

Target identity provider id of the party

UpdatePartyIdentityProviderIdResponse message, v2/admin

Message has no fields.

com/daml/ledger/api/v2/admin/user_management_service.proto

UserManagementService, v2/admin

Service to manage users and their rights for interacting with the Ledger API served by a participant node.

The authorization rules for its RPCs are specified on the <RpcName>Request messages as boolean expressions over these facts:

  1. HasRight(r) denoting whether the authenticated user has right r and

  2. IsAuthenticatedUser(uid) denoting whether uid is the empty string or equal to the id of the authenticated user.

  3. IsAuthenticatedIdentityProviderAdmin(idp) denoting whether idp is equal to the identity_provider_id of the authenticated user and the user has an IdentityProviderAdmin right.

If user_id is set to the empty string (the default), then the data for the authenticated user will be retrieved. If identity_provider_id is set to an empty string, then it’s effectively set to the value of access token’s ‘iss’ field if that is provided. If identity_provider_id remains an empty string, the default identity provider will be assumed.

The fields of request messages (and sub-messages) are marked either as Optional or Required:

  1. Optional denoting the client may leave the field unset when sending a request.

  2. Required denoting the client must set the field to a non-default value when sending a request.

A user resource consists of:

  1. a set of properties represented by the User message,

  2. a set of user rights, where each right is represented by the Right message.

A user resource, once it has been created, can be modified. In order to update the properties represented by the User message use the UpdateUser RPC. The only fields that can be modified are those marked as Modifiable. In order to grant or revoke user rights use GrantRights' and ``RevokeRights RPCs.

CreateUser method, v2/admin

Create a new user.

GetUser method, v2/admin

Get the user data of a specific user or the authenticated user.

UpdateUser method, v2/admin

Update selected modifiable attribute of a user resource described by the User message.

DeleteUser method, v2/admin

Delete an existing user and all its rights.

ListUsers method, v2/admin

List all existing users.

GrantUserRights method, v2/admin

Grant rights to a user. Granting rights does not affect the resource version of the corresponding user.

RevokeUserRights method, v2/admin

Revoke rights from a user. Revoking rights does not affect the resource version of the corresponding user.

ListUserRights method, v2/admin

List the set of all rights granted to a user.

UpdateUserIdentityProviderId method, v2/admin

Update the assignment of a user from one IDP to another.

CreateUserRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(user.identity_provider_id)

user : User

The user to create. Required

rights : Right (repeated)

The rights to be assigned to the user upon creation, which SHOULD include appropriate rights for the user.primary_party. Optional

CreateUserResponse message, v2/admin

user : User

Created user.

DeleteUserRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

user_id : string

The user to delete. Required

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the user is managed by the default identity provider.

DeleteUserResponse message, v2/admin

Does not (yet) contain any data.

Message has no fields.

GetUserRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)

user_id : string

The user whose data to retrieve. If set to empty string (the default), then the data for the authenticated user will be retrieved. Optional

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the user is managed by the default identity provider.

GetUserResponse message, v2/admin

user : User

Retrieved user.

GrantUserRightsRequest message, v2/admin

Add the rights to the set of rights granted to the user.

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

user_id : string

The user to whom to grant rights. Required

rights : Right (repeated)

The rights to grant. Optional

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the user is managed by the default identity provider.

GrantUserRightsResponse message, v2/admin

newly_granted_rights : Right (repeated)

The rights that were newly granted by the request.

ListUserRightsRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)

user_id : string

The user for which to list the rights. If set to empty string (the default), then the rights for the authenticated user will be listed. Required

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the user is managed by the default identity provider.

ListUserRightsResponse message, v2/admin

rights : Right (repeated)

All rights of the user.

ListUsersRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

page_token : string

Pagination token to determine the specific page to fetch. Leave empty to fetch the first page. Optional

page_size : int32

Maximum number of results to be returned by the server. The server will return no more than that many results, but it might return fewer. If 0, the server will decide the number of results to be returned. Optional

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the user is managed by the default identity provider.

ListUsersResponse message, v2/admin

users : User (repeated)

A subset of users of the participant node that fit into this page.

next_page_token : string

Pagination token to retrieve the next page. Empty, if there are no further results.

RevokeUserRightsRequest message, v2/admin

Remove the rights from the set of rights granted to the user.

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)

user_id : string

The user from whom to revoke rights. Required

rights : Right (repeated)

The rights to revoke. Optional

identity_provider_id : string

The id of the Identity Provider Optional, if not set, assume the user is managed by the default identity provider.

RevokeUserRightsResponse message, v2/admin

newly_revoked_rights : Right (repeated)

The rights that were actually revoked by the request.

Right message, v2/admin

A right granted to a user.

oneof kind.participant_admin : Right.ParticipantAdmin

The user can administer the participant node.

oneof kind.can_act_as : Right.CanActAs

The user can act as a specific party.

oneof kind.can_read_as : Right.CanReadAs

The user can read ledger data visible to a specific party.

oneof kind.identity_provider_admin : Right.IdentityProviderAdmin

The user can administer users and parties assigned to the same identity provider as the one of the user.

oneof kind.can_read_as_any_party : Right.CanReadAsAnyParty

The user can read as any party on a participant

Right.CanActAs message, v2/admin

party : string

The right to authorize commands for this party.

Right.CanReadAs message, v2/admin

party : string

The right to read ledger data visible to this party.

Right.CanReadAsAnyParty message, v2/admin

The rights of a participant’s super reader. Its utility is predominantly for feeding external tools, such as PQS, continually without the need to change subscriptions as new parties pop in and out of existence.

Message has no fields.

Right.IdentityProviderAdmin message, v2/admin

The right to administer the identity provider that the user is assigned to. It means, being able to manage users and parties that are also assigned to the same identity provider.

Message has no fields.

Right.ParticipantAdmin message, v2/admin

The right to administer the participant node.

Message has no fields.

UpdateUserIdentityProviderIdRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin)

user_id : string

User to update

source_identity_provider_id : string

Current identity provider ID of the user

target_identity_provider_id : string

Target identity provider ID of the user

UpdateUserIdentityProviderIdResponse message, v2/admin

Message has no fields.

UpdateUserRequest message, v2/admin

Required authorization: HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(user.identity_provider_id)

user : User

The user to update. Required, Modifiable

update_mask : google.protobuf.FieldMask

An update mask specifies how and which properties of the User message are to be updated. An update mask consists of a set of update paths. A valid update path points to a field or a subfield relative to the User message. A valid update mask must:

  1. contain at least one update path,

  2. contain only valid update paths.

Fields that can be updated are marked as Modifiable. An update path can also point to a non-Modifiable fields such as ‘id’ and ‘metadata.resource_version’ because they are used:

  1. to identify the user resource subject to the update,

  2. for concurrent change control.

Examples of valid update paths: ‘primary_party’, ‘metadata’, ‘metadata.annotations’. For additional information see the documentation for standard protobuf3’s google.protobuf.FieldMask. For similar Ledger API see com.daml.ledger.api.v2.admin.UpdatePartyDetailsRequest. Required

UpdateUserResponse message, v2/admin

user : User

Updated user

User message, v2/admin

Users are used to dynamically manage the rights given to Daml applications. They are stored and managed per participant node.

id : string

The user identifier, which must be a non-empty string of at most 128 characters that are either alphanumeric ASCII characters or one of the symbols “@^$.!`-#+’~_|:”. Required

primary_party : string

The primary party as which this user reads and acts by default on the ledger provided it has the corresponding CanReadAs(primary_party) or CanActAs(primary_party) rights. Ledger API clients SHOULD set this field to a non-empty value for all users to enable the users to act on the ledger using their own Daml party. Users for participant administrators MAY have an associated primary party. Optional, Modifiable

is_deactivated : bool

When set, then the user is denied all access to the Ledger API. Otherwise, the user has access to the Ledger API as per the user’s rights. Optional, Modifiable

metadata : ObjectMeta

The metadata of this user. Note that the metadata.resource_version tracks changes to the properties described by the User message and not the user’s rights. Optional, Modifiable

identity_provider_id : string

The ID of the identity provider configured by Identity Provider Config Optional, if not set, assume the user is managed by the default identity provider.

com/daml/ledger/api/v2/command_completion_service.proto

CommandCompletionService, v2

Allows clients to observe the status of their submissions. Commands may be submitted via the Command Submission Service. The on-ledger effects of their submissions are disclosed by the Update Service.

Commands may fail in 2 distinct manners:

  1. Failure communicated synchronously in the gRPC error of the submission.

  2. Failure communicated asynchronously in a Completion, see completion.proto.

Note that not only successfully submitted commands MAY produce a completion event. For example, the participant MAY choose to produce a completion event for a rejection of a duplicate command.

Clients that do not receive a successful completion about their submission MUST NOT assume that it was successful. Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions.

CompletionStream method, v2

Subscribe to command completion events.

CompletionStreamRequest message, v2

user_id : string

Only completions of commands submitted with the same user_id will be visible in the stream. Must be a valid UserIdString (as described in value.proto). Required unless authentication is used with a user token. In that case, the token’s user-id will be used for the request’s user_id.

parties : string (repeated)

Non-empty list of parties whose data should be included. The stream shows only completions of commands for which at least one of the act_as parties is in the given set of parties. Must be a valid PartyIdString (as described in value.proto). Required

begin_exclusive : int64

This optional field indicates the minimum offset for completions. This can be used to resume an earlier completion stream. If not set the ledger uses the ledger begin offset instead. If specified, it must be a valid absolute offset (positive integer) or zero (ledger begin offset). If the ledger has been pruned, this parameter must be specified and greater than the pruning offset.

CompletionStreamResponse message, v2

oneof completion_response.completion : Completion

oneof completion_response.offset_checkpoint : OffsetCheckpoint

com/daml/ledger/api/v2/command_service.proto

CommandService, v2

Command Service is able to correlate submitted commands with completion data, identify timeouts, and return contextual information with each tracking result. This supports the implementation of stateless clients.

Note that submitted commands generally produce completion events as well, even in case a command gets rejected. For example, the participant SHOULD produce a completion event for a rejection of a duplicate command.

SubmitAndWait method, v2

Submits a single composite command and waits for its result. Propagates the gRPC error of failed submissions including Daml interpretation errors.

SubmitAndWaitForTransaction method, v2

Submits a single composite command, waits for its result, and returns the transaction. Propagates the gRPC error of failed submissions including Daml interpretation errors.

SubmitAndWaitForTransactionTree method, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Submits a single composite command, waits for its result, and returns the transaction tree. Propagates the gRPC error of failed submissions including Daml interpretation errors.

SubmitAndWaitForReassignment method, v2

Submits a single composite reassignment command, waits for its result, and returns the reassignment. Propagates the gRPC error of failed submission.

SubmitAndWaitForReassignmentRequest message, v2

This reassignment is executed as a single atomic update.

reassignment_commands : ReassignmentCommands

The reassignment commands to be submitted. Required

event_format : EventFormat

Optional If no event_format provided, the result will contain no events. The events in the result, will take shape TRANSACTION_SHAPE_ACS_DELTA.

SubmitAndWaitForReassignmentResponse message, v2

reassignment : Reassignment

The reassignment that resulted from the submitted reassignment command. The reassignment might contain no events (request conditions result in filtering out all of them). Required

SubmitAndWaitForTransactionRequest message, v2

These commands are executed as a single atomic transaction.

commands : Commands

The commands to be submitted. Required

transaction_format : TransactionFormat

If no transaction_format is provided, a default will be used where transaction_shape is set to TRANSACTION_SHAPE_ACS_DELTA, event_format is defined with filters_by_party containing wildcard-template filter for all original act_as and read_as parties and the verbose flag is set. Optional

SubmitAndWaitForTransactionResponse message, v2

transaction : Transaction

The transaction that resulted from the submitted command. The transaction might contain no events (request conditions result in filtering out all of them). Required

SubmitAndWaitForTransactionTreeResponse message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0.

transaction : TransactionTree

The transaction tree that resulted from the submitted command. The transaction might contain no events (request conditions result in filtering out all of them). Required

SubmitAndWaitRequest message, v2

These commands are executed as a single atomic transaction.

commands : Commands

The commands to be submitted. Required

SubmitAndWaitResponse message, v2

update_id : string

The id of the transaction that resulted from the submitted command. Must be a valid LedgerString (as described in value.proto). Required

completion_offset : int64

The details of the offset field are described in community/ledger-api/README.md. Required

com/daml/ledger/api/v2/command_submission_service.proto

CommandSubmissionService, v2

Allows clients to attempt advancing the ledger’s state by submitting commands. The final states of their submissions are disclosed by the Command Completion Service. The on-ledger effects of their submissions are disclosed by the Update Service.

Commands may fail in 2 distinct manners:

  1. Failure communicated synchronously in the gRPC error of the submission.

  2. Failure communicated asynchronously in a Completion, see completion.proto.

Note that not only successfully submitted commands MAY produce a completion event. For example, the participant MAY choose to produce a completion event for a rejection of a duplicate command.

Clients that do not receive a successful completion about their submission MUST NOT assume that it was successful. Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions.

Submit method, v2

Submit a single composite command.

SubmitReassignment method, v2

Submit a single reassignment.

SubmitReassignmentRequest message, v2

reassignment_commands : ReassignmentCommands

The reassignment command to be submitted. Required

SubmitReassignmentResponse message, v2

Message has no fields.

SubmitRequest message, v2

The submitted commands will be processed atomically in a single transaction. Moreover, each Command in commands will be executed in the order specified by the request.

commands : Commands

The commands to be submitted in a single transaction. Required

SubmitResponse message, v2

Message has no fields.

com/daml/ledger/api/v2/commands.proto

Command message, v2

A command can either create a new contract or exercise a choice on an existing contract.

oneof command.create : CreateCommand

oneof command.exercise : ExerciseCommand

oneof command.exercise_by_key : ExerciseByKeyCommand

oneof command.create_and_exercise : CreateAndExerciseCommand

Commands message, v2

A composite command that groups multiple commands together.

workflow_id : string

Identifier of the on-ledger workflow that this command is a part of. Must be a valid LedgerString (as described in value.proto). Optional

user_id : string

Uniquely identifies the participant user that issued the command. Must be a valid UserIdString (as described in value.proto). Required unless authentication is used with a user token. In that case, the token’s user-id will be used for the request’s user_id.

command_id : string

Uniquely identifies the command. The triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change, where act_as is interpreted as a set of party names. The change ID can be used for matching the intended ledger changes with all their completions. Must be a valid LedgerString (as described in value.proto). Required

commands : Command (repeated)

Individual elements of this atomic command. Must be non-empty. Required

oneof deduplication_period.deduplication_duration : google.protobuf.Duration

Specifies the length of the deduplication period. It is interpreted relative to the local clock at some point during the submission’s processing. Must be non-negative. Must not exceed the maximum deduplication time.

oneof deduplication_period.deduplication_offset : int64

Specifies the start of the deduplication period by a completion stream offset (exclusive). Must be a valid absolute offset (positive integer) or participant begin (zero).

min_ledger_time_abs : google.protobuf.Timestamp

Lower bound for the ledger time assigned to the resulting transaction. Note: The ledger time of a transaction is assigned as part of command interpretation. Use this property if you expect that command interpretation will take a considerate amount of time, such that by the time the resulting transaction is sequenced, its assigned ledger time is not valid anymore. Must not be set at the same time as min_ledger_time_rel. Optional

min_ledger_time_rel : google.protobuf.Duration

Same as min_ledger_time_abs, but specified as a duration, starting from the time the command is received by the server. Must not be set at the same time as min_ledger_time_abs. Optional

act_as : string (repeated)

Set of parties on whose behalf the command should be executed. If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request to act on behalf of each of the given parties. Each element must be a valid PartyIdString (as described in value.proto). Required, must be non-empty.

read_as : string (repeated)

Set of parties on whose behalf (in addition to all parties listed in act_as) contracts can be retrieved. This affects Daml operations such as fetch, fetchByKey, lookupByKey, exercise, and exerciseByKey. Note: A participant node of a Daml network can host multiple parties. Each contract present on the participant node is only visible to a subset of these parties. A command can only use contracts that are visible to at least one of the parties in act_as or read_as. This visibility check is independent from the Daml authorization rules for fetch operations. If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request to read contract data on behalf of each of the given parties. Optional

submission_id : string

A unique identifier to distinguish completions for different submissions with the same change ID. Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission with the same change ID. Must be a valid LedgerString (as described in value.proto).

If omitted, the participant or the committer may set a value of their choice. Optional

disclosed_contracts : DisclosedContract (repeated)

Additional contracts used to resolve contract & contract key lookups. Optional

synchronizer_id : string

Must be a valid synchronizer id Optional

package_id_selection_preference : string (repeated)

The package-id selection preference of the client for resolving package names and interface instances in command submission and interpretation

prefetch_contract_keys : PrefetchContractKey (repeated)

Fetches the contract keys into the caches to speed up the command processing. Should only contain contract keys that are expected to be resolved during interpretation of the commands. Keys of disclosed contracts do not need prefetching.

Optional

CreateAndExerciseCommand message, v2

Create a contract and exercise a choice on it in the same transaction.

template_id : Identifier

The template of the contract the client wants to create. Both package-name and package-id reference identifier formats for the template-id are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.

Required

create_arguments : Record

The arguments required for creating a contract from this template. Required

choice : string

The name of the choice the client wants to exercise. Must be a valid NameString (as described in value.proto). Required

choice_argument : Value

The argument for this choice. Required

CreateCommand message, v2

Create a new contract instance based on a template.

template_id : Identifier

The template of contract the client wants to create. Both package-name and package-id reference identifier formats for the template-id are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.

Required

create_arguments : Record

The arguments required for creating a contract from this template. Required

DisclosedContract message, v2

An additional contract that is used to resolve contract & contract key lookups.

template_id : Identifier

The template id of the contract. The identifier uses the package-id reference format.

Required

contract_id : string

The contract id Required

created_event_blob : bytes

Opaque byte string containing the complete payload required by the Daml engine to reconstruct a contract not known to the receiving participant. Required

synchronizer_id : string

The ID of the synchronizer where the contract is currently assigned Optional

ExerciseByKeyCommand message, v2

Exercise a choice on an existing contract specified by its key.

template_id : Identifier

The template of contract the client wants to exercise. Both package-name and package-id reference identifier formats for the template-id are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.

Required

contract_key : Value

The key of the contract the client wants to exercise upon. Required

choice : string

The name of the choice the client wants to exercise. Must be a valid NameString (as described in value.proto) Required

choice_argument : Value

The argument for this choice. Required

ExerciseCommand message, v2

Exercise a choice on an existing contract.

template_id : Identifier

The template or interface of the contract the client wants to exercise. Both package-name and package-id reference identifier formats for the template-id are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. To exercise a choice on an interface, specify the interface identifier in the template_id field.

Required

contract_id : string

The ID of the contract the client wants to exercise upon. Must be a valid LedgerString (as described in value.proto). Required

choice : string

The name of the choice the client wants to exercise. Must be a valid NameString (as described in value.proto) Required

choice_argument : Value

The argument for this choice. Required

PrefetchContractKey message, v2

Preload contracts

template_id : Identifier

The template of contract the client wants to prefetch. Both package-name and package-id reference identifier formats for the template-id are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.

Required

contract_key : Value

The key of the contract the client wants to prefetch. Required

com/daml/ledger/api/v2/completion.proto

Completion message, v2

A completion represents the status of a submitted command on the ledger: it can be successful or failed.

command_id : string

The ID of the succeeded or failed command. Must be a valid LedgerString (as described in value.proto). Required

status : google.rpc.Status

Identifies the exact type of the error. It uses the same format of conveying error details as it is used for the RPC responses of the APIs. Optional

update_id : string

The update_id of the transaction or reassignment that resulted from the command with command_id. Only set for successfully executed commands. Must be a valid LedgerString (as described in value.proto).

user_id : string

The user-id that was used for the submission, as described in commands.proto. Must be a valid UserIdString (as described in value.proto). Optional for historic completions where this data is not available.

act_as : string (repeated)

The set of parties on whose behalf the commands were executed. Contains the act_as parties from commands.proto filtered to the requesting parties in CompletionStreamRequest. The order of the parties need not be the same as in the submission. Each element must be a valid PartyIdString (as described in value.proto). Optional for historic completions where this data is not available.

submission_id : string

The submission ID this completion refers to, as described in commands.proto. Must be a valid LedgerString (as described in value.proto). Optional

oneof deduplication_period.deduplication_offset : int64

Specifies the start of the deduplication period by a completion stream offset (exclusive).

Must be a valid absolute offset (positive integer) or participant begin (zero).

oneof deduplication_period.deduplication_duration : google.protobuf.Duration

Specifies the length of the deduplication period. It is measured in record time of completions.

Must be non-negative.

trace_context : TraceContext

Optional; ledger API trace context

The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead.

offset : int64

May be used in a subsequent CompletionStreamRequest to resume the consumption of this stream at a later time. Required, must be a valid absolute offset (positive integer).

synchronizer_time : SynchronizerTime

The synchronizer along with its record time. The synchronizer id provided, in case of

  • successful/failed transactions: identifies the synchronizer of the transaction

  • for successful/failed unassign commands: identifies the source synchronizer

  • for successful/failed assign commands: identifies the target synchronizer

Required

com/daml/ledger/api/v2/event.proto

ArchivedEvent message, v2

Records that a contract has been archived, and choices may no longer be exercised on it.

offset : int64

The offset of origin. Offsets are managed by the participant nodes. Transactions can thus NOT be assumed to have the same offsets on different participant nodes. Required, it is a valid absolute offset (positive integer)

node_id : int32

The position of this event in the originating transaction or reassignment. Node IDs are not necessarily equal across participants, as these may see different projections/parts of transactions. Required, must be valid node ID (non-negative integer)

contract_id : string

The ID of the archived contract. Must be a valid LedgerString (as described in value.proto). Required

template_id : Identifier

The template of the archived contract. The identifier uses the package-id reference format.

Required

witness_parties : string (repeated)

The parties that are notified of this event. For an ArchivedEvent, these are the intersection of the stakeholders of the contract in question and the parties specified in the TransactionFilter. The stakeholders are the union of the signatories and the observers of the contract. Each one of its elements must be a valid PartyIdString (as described in value.proto). Required

package_name : string

The package name of the contract. Required

implemented_interfaces : Identifier (repeated)

The interfaces implemented by the target template that have been matched from the interface filter query. Populated only in case interface filters with include_interface_view set.

If defined, the identifier uses the package-id reference format.

Optional

CreatedEvent message, v2

Records that a contract has been created, and choices may now be exercised on it.

offset : int64

The offset of origin, which has contextual meaning, please see description at messages that include a CreatedEvent. Offsets are managed by the participant nodes. Transactions can thus NOT be assumed to have the same offsets on different participant nodes. Required, it is a valid absolute offset (positive integer)

node_id : int32

The position of this event in the originating transaction or reassignment. The origin has contextual meaning, please see description at messages that include a CreatedEvent. Node IDs are not necessarily equal across participants, as these may see different projections/parts of transactions. Required, must be valid node ID (non-negative integer)

contract_id : string

The ID of the created contract. Must be a valid LedgerString (as described in value.proto). Required

template_id : Identifier

The template of the created contract. The identifier uses the package-id reference format.

Required

contract_key : Value

The key of the created contract. This will be set if and only if create_arguments is set and template_id defines a contract key. Optional

create_arguments : Record

The arguments that have been used to create the contract. Set either:

  • if there was a party, which is in the witness_parties of this event, and for which a CumulativeFilter exists with the template_id of this event among the template_filters,

  • or if there was a party, which is in the witness_parties of this event, and for which a wildcard filter exists (Filters with a CumulativeFilter of WildcardFilter).

Optional

created_event_blob : bytes

Opaque representation of contract create event payload intended for forwarding to an API server as a contract disclosed as part of a command submission. Optional

interface_views : InterfaceView (repeated)

Interface views specified in the transaction filter. Includes an InterfaceView for each interface for which there is a InterfaceFilter with

  • its party in the witness_parties of this event,

  • and which is implemented by the template of this event,

  • and which has include_interface_view set.

Optional

witness_parties : string (repeated)

The parties that are notified of this event. When a CreatedEvent is returned as part of a transaction tree or ledger-effects transaction, this will include all the parties specified in the TransactionFilter that are informees of the event. If served as part of a ACS delta transaction those will be limited to all parties specified in the TransactionFilter that are stakeholders of the contract (i.e. either signatories or observers). If the CreatedEvent is returned as part of an AssignedEvent, ActiveContract or IncompleteUnassigned (so the event is related to an assignment or unassignment): this will include all parties of the TransactionFilter that are stakeholders of the contract.

The behavior of reading create events visible to parties not hosted on the participant node serving the Ledger API is undefined. Concretely, there is neither a guarantee that the participant node will serve all their create events on the ACS stream, nor is there a guarantee that matching archive events are delivered for such create events.

For most clients this is not a problem, as they only read events for parties that are hosted on the participant node. If you need to read events for parties that may not be hosted at all times on the participant node, subscribe to the TopologyEvent``s for that party by setting a corresponding ``UpdateFormat. Using these events, query the ACS as-of an offset where the party is hosted on the participant node, and ignore create events at offsets where the party is not hosted on the participant node. Required

signatories : string (repeated)

The signatories for this contract as specified by the template. Required

observers : string (repeated)

The observers for this contract as specified explicitly by the template or implicitly as choice controllers. This field never contains parties that are signatories. Required

created_at : google.protobuf.Timestamp

Ledger effective time of the transaction that created the contract. Required

package_name : string

The package name of the created contract. Required

Event message, v2

Events in transactions can have two primary shapes:

  • ACS delta: events can be CreatedEvent or ArchivedEvent

  • ledger effects: events can be CreatedEvent or ExercisedEvent

In the update service the events are restricted to the events visible for the parties specified in the transaction filter. Each event message type below contains a witness_parties field which indicates the subset of the requested parties that can see the event in question.

oneof event.created : CreatedEvent

The event as it appeared in the context of its original daml transaction on this participant node. In particular, the offset, node_id pair of the daml transaction are preserved.

oneof event.archived : ArchivedEvent

oneof event.exercised : ExercisedEvent

ExercisedEvent message, v2

Records that a choice has been exercised on a target contract.

offset : int64

The offset of origin. Offsets are managed by the participant nodes. Transactions can thus NOT be assumed to have the same offsets on different participant nodes. Required, it is a valid absolute offset (positive integer)

node_id : int32

The position of this event in the originating transaction or reassignment. Node IDs are not necessarily equal across participants, as these may see different projections/parts of transactions. Required, must be valid node ID (non-negative integer)

contract_id : string

The ID of the target contract. Must be a valid LedgerString (as described in value.proto). Required

template_id : Identifier

The template of the target contract. The identifier uses the package-id reference format.

Required

interface_id : Identifier

The interface where the choice is defined, if inherited. If defined, the identifier uses the package-id reference format.

Optional

choice : string

The choice that was exercised on the target contract. Must be a valid NameString (as described in value.proto). Required

choice_argument : Value

The argument of the exercised choice. Required

acting_parties : string (repeated)

The parties that exercised the choice. Each element must be a valid PartyIdString (as described in value.proto). Required

consuming : bool

If true, the target contract may no longer be exercised. Required

witness_parties : string (repeated)

The parties that are notified of this event. The witnesses of an exercise node will depend on whether the exercise was consuming or not. If consuming, the witnesses are the union of the stakeholders and the actors. If not consuming, the witnesses are the union of the signatories and the actors. Note that the actors might not necessarily be observers and thus signatories. This is the case when the controllers of a choice are specified using “flexible controllers”, using the choice ... controller syntax, and said controllers are not explicitly marked as observers. Each element must be a valid PartyIdString (as described in value.proto). Required

last_descendant_node_id : int32

Specifies the upper boundary of the node ids of the events in the same transaction that appeared as a result of this ExercisedEvent. This allows unambiguous identification of all the members of the subtree rooted at this node. A full subtree can be constructed when all descendant nodes are present in the stream. If nodes are heavily filtered, it is only possible to determine if a node is in a consequent subtree or not. Required

exercise_result : Value

The result of exercising the choice. Required

package_name : string

The package name of the contract. Required

implemented_interfaces : Identifier (repeated)

If the event is consuming, the interfaces implemented by the target template that have been matched from the interface filter query. Populated only in case interface filters with include_interface_view set.

The identifier uses the package-id reference format.

Optional

InterfaceView message, v2

View of a create event matched by an interface filter.

interface_id : Identifier

The interface implemented by the matched event. The identifier uses the package-id reference format.

Required

view_status : google.rpc.Status

Whether the view was successfully computed, and if not, the reason for the error. The error is reported using the same rules for error codes and messages as the errors returned for API requests. Required

view_value : Record

The value of the interface’s view method on this event. Set if it was requested in the InterfaceFilter and it could be sucessfully computed. Optional

com/daml/ledger/api/v2/event_query_service.proto

EventQueryService, v2

Query events by contract id.

Note that querying by contract key is not (yet) supported, as contract keys are not supported (yet) in multi-synchronizer scenarios.

GetEventsByContractId method, v2

Get the create and the consuming exercise event for the contract with the provided ID. No events will be returned for contracts that have been pruned because they have already been archived before the latest pruning offset. If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised.

Archived message, v2

archived_event : ArchivedEvent

Required

synchronizer_id : string

Required The synchronizer which sequenced the archival of the contract

Created message, v2

created_event : CreatedEvent

Required The event as it appeared in the context of its original update (i.e. daml transaction or reassignment) on this participant node. You can use its offset and node_id to find the corresponding update and the node within it.

synchronizer_id : string

The synchronizer which sequenced the creation of the contract Required

GetEventsByContractIdRequest message, v2

contract_id : string

The contract id being queried. Required

requesting_parties : string (repeated)

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. The parties whose events the client expects to see. The events associated with the contract id will only be returned if the requesting parties includes at least one party that is a stakeholder of the event. For a definition of stakeholders see https://docs.daml.com/concepts/ledger-model/ledger-privacy.html#contract-observers-and-stakeholders Optional, if some parties specified, event_format needs to be unset.

event_format : EventFormat

Format of the events in the result, the presentation will be of TRANSACTION_SHAPE_ACS_DELTA. Optional for backwards compatibility, defaults to an EventFormat where:

  • filters_by_party is a template-wildcard filter for all requesting_parties

  • filters_for_any_party is unset

  • verbose is set

GetEventsByContractIdResponse message, v2

created : Created

The create event for the contract with the contract_id given in the request provided it exists and has not yet been pruned. Optional

archived : Archived

The archive event for the contract with the contract_id given in the request provided such an archive event exists and it has not yet been pruned. Optional

com/daml/ledger/api/v2/experimental_features.proto

ExperimentalCommandInspectionService message, v2

Whether the Ledger API supports command inspection service

supported : bool

ExperimentalFeatures message, v2

See the feature message definitions for descriptions.

static_time : ExperimentalStaticTime

command_inspection_service : ExperimentalCommandInspectionService

ExperimentalPartyTopologyEvents message, v2

Whether the Ledger API supports party events

supported : bool

ExperimentalStaticTime message, v2

Ledger is in the static time mode and exposes a time service.

supported : bool

com/daml/ledger/api/v2/interactive/interactive_submission_common_data.proto

GlobalKey message, v2/interactive

template_id : com.daml.ledger.api.v2.Identifier

The identifier uses the package-id reference format.

package_name : string

key : com.daml.ledger.api.v2.Value

hash : bytes

com/daml/ledger/api/v2/interactive/interactive_submission_service.proto

InteractiveSubmissionService, v2/interactive

Service allowing interactive construction of command submissions

The prepare and execute endpoints allow to submit commands in 2-steps:

  1. prepare transaction from commands,

  2. submit the prepared transaction

This gives callers the ability to sign the daml transaction with their own signing keys

PrepareSubmission method, v2/interactive

Requires readAs scope for the submitting party when LAPI User authorization is enabled

ExecuteSubmission method, v2/interactive

GetPreferredPackageVersion method, v2/interactive

A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties.

Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred package, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract

Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled.

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0

GetPreferredPackages method, v2/interactive

Compute the preferred packages for the vetting requirements in the request. A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties.

Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred packages, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract

If the package preferences could not be computed due to no selection satisfying the requirements, a FAILED_PRECONDITION error will be returned.

Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled.

Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases

DamlTransaction message, v2/interactive

Daml Transaction. This represents the effect on the ledger if this transaction is successfully committed.

version : string

Transaction version, will be >= max(nodes version)

roots : string (repeated)

Root nodes of the transaction

nodes : DamlTransaction.Node (repeated)

List of nodes in the transaction

node_seeds : DamlTransaction.NodeSeed (repeated)

Node seeds are values associated with certain nodes used for generating cryptographic salts

DamlTransaction.Node message, v2/interactive

A transaction may contain nodes with different versions. Each node must be hashed using the hashing algorithm corresponding to its specific version. [docs-entry-start: DamlTransaction.Node]

node_id : string

oneof versioned_node.v1 : transaction.v1.Node

Start at 1000 so we can add more fields before if necessary When new versions will be added, they will show here

DamlTransaction.NodeSeed message, v2/interactive

node_id : int32

seed : bytes

ExecuteSubmissionRequest message, v2/interactive

prepared_transaction : PreparedTransaction

the prepared transaction Typically this is the value of the prepared_transaction field in PrepareSubmissionResponse obtained from calling prepareSubmission.

party_signatures : PartySignatures

The party(ies) signatures that authorize the prepared submission to be executed by this node. Each party can provide one or more signatures.. and one or more parties can sign. Note that currently, only single party submissions are supported.

oneof deduplication_period.deduplication_duration : google.protobuf.Duration

Specifies the length of the deduplication period. It is interpreted relative to the local clock at some point during the submission’s processing. Must be non-negative. Must not exceed the maximum deduplication time.

oneof deduplication_period.deduplication_offset : int64

Specifies the start of the deduplication period by a completion stream offset (exclusive). Must be a valid absolute offset (positive integer).

submission_id : string

A unique identifier to distinguish completions for different submissions with the same change ID. Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission with the same change ID. Must be a valid LedgerString (as described in value.proto).

Required

user_id : string

See [PrepareSubmissionRequest.user_id]

hashing_scheme_version : HashingSchemeVersion

The hashing scheme version used when building the hash

min_ledger_time : MinLedgerTime

If set will influence the chosen ledger effective time but will not result in a submission delay so any override should be scheduled to executed within the window allowed by synchronizer.

Optional

ExecuteSubmissionResponse message, v2/interactive

Message has no fields.

GetPreferredPackageVersionRequest message, v2/interactive

parties : string (repeated)

The parties whose participants’ vetting state should be considered when resolving the preferred package. Required

package_name : string

The package-name for which the preferred package should be resolved. Required

synchronizer_id : string

The synchronizer whose vetting state to use for resolving this query. If not specified, the vetting state of all the synchronizers the participant is connected to will be used. Optional

vetting_valid_at : google.protobuf.Timestamp

The timestamp at which the package vetting validity should be computed on the latest topology snapshot as seen by the participant. If not provided, the participant’s current clock time is used. Optional

GetPreferredPackageVersionResponse message, v2/interactive

package_preference : PackagePreference

Not populated when no preferred package is found Optional

GetPreferredPackagesRequest message, v2/interactive

package_vetting_requirements : PackageVettingRequirement (repeated)

The package-name vetting requirements for which the preferred packages should be resolved.

Generally it is enough to provide the requirements for the intended command’s root package-names. Additional package-name requirements can be provided when additional Daml transaction informees need to use package dependencies of the command’s root packages.

Required

synchronizer_id : string

The synchronizer whose vetting state to use for resolving this query. If not specified, the vetting state of all the synchronizers the participant is connected to will be used. Optional

vetting_valid_at : google.protobuf.Timestamp

The timestamp at which the package vetting validity should be computed on the latest topology snapshot as seen by the participant. If not provided, the participant’s current clock time is used. Optional

GetPreferredPackagesResponse message, v2/interactive

package_references : com.daml.ledger.api.v2.PackageReference (repeated)

The package references of the preferred packages. Must contain one package reference for each requested package-name.

If you build command submissions whose content depends on the returned preferred packages, then we recommend submitting the preferred package-ids in the package_id_selection_preference of the command submission to avoid race conditions with concurrent changes of the on-ledger package vetting state.

Required

synchronizer_id : string

The synchronizer for which the package preferences are computed. If the synchronizer_id was specified in the request, then it matches the request synchronizer_id. Required

Metadata message, v2/interactive

Transaction Metadata Refer to the hashing documentation for information on how it should be hashed.

submitter_info : Metadata.SubmitterInfo

synchronizer_id : string

mediator_group : uint32

transaction_uuid : string

preparation_time : uint64

input_contracts : Metadata.InputContract (repeated)

oneof _min_ledger_effective_time.min_ledger_effective_time : uint64 (optional)

Where ledger time constraints are imposed during the execution of the contract they will be populated in the fields below. These are optional because if the transaction does NOT depend on time, these values do not need to be set. The final ledger effective time used will be chosen when the command is submitted through the [execute] RPC. If the ledger effective time is outside of any populated min/max bounds then a different transaction can result, that will cause a confirmation message rejection.

oneof _max_ledger_effective_time.max_ledger_effective_time : uint64 (optional)

global_key_mapping : Metadata.GlobalKeyMappingEntry (repeated)

Contextual information needed to process the transaction but not signed, either because it’s already indirectly signed by signing the transaction, or because it doesn’t impact the ledger state

Metadata.GlobalKeyMappingEntry message, v2/interactive

key : GlobalKey

oneof _value.value : com.daml.ledger.api.v2.Value (optional)

Metadata.InputContract message, v2/interactive

oneof contract.v1 : transaction.v1.Create

When new versions will be added, they will show here

created_at : uint64

event_blob : bytes

Metadata.SubmitterInfo message, v2/interactive

act_as : string (repeated)

command_id : string

MinLedgerTime message, v2/interactive

oneof time.min_ledger_time_abs : google.protobuf.Timestamp

Lower bound for the ledger time assigned to the resulting transaction. The ledger time of a transaction is assigned as part of command interpretation. Important note: for interactive submissions, if the transaction depends on time, it must be signed and submitted within a time window around the ledger time assigned to the transaction during the prepare method. The time delta around that ledger time is a configuration of the ledger, usually short, around 1 minute. If however the transaction does not depend on time, the available time window to sign and submit the transaction is bound by the preparation time, which is also assigned in the “prepare” step (this request), but can be configured with a much larger skew, allowing for more time to sign the request (in the order of hours). Must not be set at the same time as min_ledger_time_rel. Optional

oneof time.min_ledger_time_rel : google.protobuf.Duration

Same as min_ledger_time_abs, but specified as a duration, starting from the time this request is received by the server. Must not be set at the same time as min_ledger_time_abs. Optional

PackagePreference message, v2/interactive

package_reference : com.daml.ledger.api.v2.PackageReference

The package reference of the preferred package. Required

synchronizer_id : string

The synchronizer for which the preferred package was computed. If the synchronizer_id was specified in the request, then it matches the request synchronizer_id. Required

PackageVettingRequirement message, v2/interactive

Defines a package-name for which the commonly vetted package with the highest version must be found.

parties : string (repeated)

The parties whose participants’ vetting state should be considered when resolving the preferred package. Required

package_name : string

The package-name for which the preferred package should be resolved. Required

PartySignatures message, v2/interactive

Additional signatures provided by the submitting parties

signatures : SinglePartySignatures (repeated)

Additional signatures provided by all individual parties

PrepareSubmissionRequest message, v2/interactive

user_id : string

Uniquely identifies the participant user that prepares the transaction. Must be a valid UserIdString (as described in value.proto). Required unless authentication is used with a user token. In that case, the token’s user-id will be used for the request’s user_id.

command_id : string

Uniquely identifies the command. The triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change, where act_as is interpreted as a set of party names. The change ID can be used for matching the intended ledger changes with all their completions. Must be a valid LedgerString (as described in value.proto). Required

commands : com.daml.ledger.api.v2.Command (repeated)

Individual elements of this atomic command. Must be non-empty. Required

min_ledger_time : MinLedgerTime

Optional

act_as : string (repeated)

Set of parties on whose behalf the command should be executed, if submitted. If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request to read (not act) on behalf of each of the given parties. This is because this RPC merely prepares a transaction and does not execute it. Therefore read authorization is sufficient even for actAs parties. Note: This may change, and more specific authorization scope may be introduced in the future. Each element must be a valid PartyIdString (as described in value.proto). Required, must be non-empty.

read_as : string (repeated)

Set of parties on whose behalf (in addition to all parties listed in act_as) contracts can be retrieved. This affects Daml operations such as fetch, fetchByKey, lookupByKey, exercise, and exerciseByKey. Note: A command can only use contracts that are visible to at least one of the parties in act_as or read_as. This visibility check is independent from the Daml authorization rules for fetch operations. If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request to read contract data on behalf of each of the given parties. Optional

disclosed_contracts : com.daml.ledger.api.v2.DisclosedContract (repeated)

Additional contracts used to resolve contract & contract key lookups. Optional

synchronizer_id : string

Must be a valid synchronizer id Required

package_id_selection_preference : string (repeated)

The package-id selection preference of the client for resolving package names and interface instances in command submission and interpretation

verbose_hashing : bool

When true, the response will contain additional details on how the transaction was encoded and hashed This can be useful for troubleshooting of hash mismatches. Should only be used for debugging.

prefetch_contract_keys : com.daml.ledger.api.v2.PrefetchContractKey (repeated)

Fetches the contract keys into the caches to speed up the command processing. Should only contain contract keys that are expected to be resolved during interpretation of the commands. Keys of disclosed contracts do not need prefetching.

Optional

PrepareSubmissionResponse message, v2/interactive

prepared_transaction : PreparedTransaction

The interpreted transaction, it represents the ledger changes necessary to execute the commands specified in the request. Clients MUST display the content of the transaction to the user for them to validate before signing the hash if the preparing participant is not trusted.

prepared_transaction_hash : bytes

Hash of the transaction, this is what needs to be signed by the party to authorize the transaction. Only provided for convenience, clients MUST recompute the hash from the raw transaction if the preparing participant is not trusted. May be removed in future versions

hashing_scheme_version : HashingSchemeVersion

The hashing scheme version used when building the hash

oneof _hashing_details.hashing_details : string (optional)

Optional additional details on how the transaction was encoded and hashed. Only set if verbose_hashing = true in the request Note that there are no guarantees on the stability of the format or content of this field. Its content should NOT be parsed and should only be used for troubleshooting purposes.

PreparedTransaction message, v2/interactive

Prepared Transaction Message

transaction : DamlTransaction

Daml Transaction representing the ledger effect if executed. See below

metadata : Metadata

Metadata context necessary to execute the transaction

Signature message, v2/interactive

format : SignatureFormat

signature : bytes

signed_by : string

The fingerprint/id of the keypair used to create this signature and needed to verify.

signing_algorithm_spec : SigningAlgorithmSpec

The signing algorithm specification used to produce this signature

SinglePartySignatures message, v2/interactive

Signatures provided by a single party

party : string

Submitting party

signatures : Signature (repeated)

Signatures

HashingSchemeVersion enum, v2/interactive

[docs-entry-start: HashingSchemeVersion] The hashing scheme version used when building the hash of the PreparedTransaction

HASHING_SCHEME_VERSION_UNSPECIFIED

0

HASHING_SCHEME_VERSION_V2

2

SignatureFormat enum, v2/interactive

SIGNATURE_FORMAT_UNSPECIFIED

0

SIGNATURE_FORMAT_RAW

1

Signature scheme specific signature format Legacy format no longer used, except for migrations

SIGNATURE_FORMAT_DER

2

ASN.1 + DER-encoding of the r and s integers, as defined in https://datatracker.ietf.org/doc/html/rfc3279#section-2.2.3 Used for ECDSA signatures

SIGNATURE_FORMAT_CONCAT

3

Concatenation of the integers r || s in little-endian form, as defined in https://datatracker.ietf.org/doc/html/rfc8032#section-3.3 Note that this is different from the format defined in IEEE P1363, which uses concatenation in big-endian form. Used for EdDSA signatures

SIGNATURE_FORMAT_SYMBOLIC

10000

Symbolic crypto, must only be used for testing

SigningAlgorithmSpec enum, v2/interactive

SIGNING_ALGORITHM_SPEC_UNSPECIFIED

0

SIGNING_ALGORITHM_SPEC_ED25519

1

EdDSA Signature based on Curve25519 with SHA-512 http://ed25519.cr.yp.to/

SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_256

2

Elliptic Curve Digital Signature Algorithm with SHA256

SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_384

3

Elliptic Curve Digital Signature Algorithm with SHA384

com/daml/ledger/api/v2/interactive/transaction/v1/interactive_submission_data.proto

Create message, v2/interactive/transaction/v1

Create Node

lf_version : string

Specific LF version of the node

contract_id : string

package_name : string

template_id : com.daml.ledger.api.v2.Identifier

The identifier uses the package-id reference format.

argument : com.daml.ledger.api.v2.Value

signatories : string (repeated)

stakeholders : string (repeated)

Exercise message, v2/interactive/transaction/v1

Exercise node

lf_version : string

Specific LF version of the node

contract_id : string

package_name : string

template_id : com.daml.ledger.api.v2.Identifier

The identifier uses the package-id reference format.

signatories : string (repeated)

stakeholders : string (repeated)

acting_parties : string (repeated)

interface_id : com.daml.ledger.api.v2.Identifier

The identifier uses the package-id reference format.

choice_id : string

chosen_value : com.daml.ledger.api.v2.Value

consuming : bool

children : string (repeated)

exercise_result : com.daml.ledger.api.v2.Value

choice_observers : string (repeated)

Fetch message, v2/interactive/transaction/v1

Fetch node

lf_version : string

Specific LF version of the node

contract_id : string

package_name : string

template_id : com.daml.ledger.api.v2.Identifier

The identifier uses the package-id reference format.

signatories : string (repeated)

stakeholders : string (repeated)

acting_parties : string (repeated)

interface_id : com.daml.ledger.api.v2.Identifier

Optional

Node message, v2/interactive/transaction/v1

oneof node_type.create : Create

oneof node_type.fetch : Fetch

oneof node_type.exercise : Exercise

oneof node_type.rollback : Rollback

Rollback message, v2/interactive/transaction/v1

Rollback Node

children : string (repeated)

com/daml/ledger/api/v2/offset_checkpoint.proto

OffsetCheckpoint message, v2

OffsetCheckpoints may be used to:

  • detect time out of commands.

  • provide an offset which can be used to restart consumption.

offset : int64

The participant’s offset, the details of the offset field are described in community/ledger-api/README.md. Required, must be a valid absolute offset (positive integer).

synchronizer_times : SynchronizerTime (repeated)

SynchronizerTime message, v2

synchronizer_id : string

The id of the synchronizer. Required

record_time : google.protobuf.Timestamp

All commands with a maximum record time below this value MUST be considered lost if their completion has not arrived before this checkpoint. Required

com/daml/ledger/api/v2/package_reference.proto

PackageReference message, v2

package_id : string

Required

package_name : string

Required

package_version : string

Required

com/daml/ledger/api/v2/package_service.proto

PackageService, v2

Allows clients to query the Daml-LF packages that are supported by the server.

ListPackages method, v2

Returns the identifiers of all supported packages.

GetPackage method, v2

Returns the contents of a single package.

GetPackageStatus method, v2

Returns the status of a single package.

GetPackageRequest message, v2

package_id : string

The ID of the requested package. Must be a valid PackageIdString (as described in value.proto). Required

GetPackageResponse message, v2

hash_function : HashFunction

The hash function we use to calculate the hash. Required

archive_payload : bytes

Contains a daml_lf ArchivePayload. See further details in daml_lf.proto. Required

hash : string

The hash of the archive payload, can also used as a package_id. Must be a valid PackageIdString (as described in value.proto). Required

GetPackageStatusRequest message, v2

package_id : string

The ID of the requested package. Must be a valid PackageIdString (as described in value.proto). Required

GetPackageStatusResponse message, v2

package_status : PackageStatus

The status of the package.

ListPackagesRequest message, v2

Message has no fields.

ListPackagesResponse message, v2

package_ids : string (repeated)

The IDs of all Daml-LF packages supported by the server. Each element must be a valid PackageIdString (as described in value.proto). Required

HashFunction enum, v2

HASH_FUNCTION_SHA256

0

PackageStatus enum, v2

PACKAGE_STATUS_UNSPECIFIED

0

The server is not aware of such a package.

PACKAGE_STATUS_REGISTERED

1

The server is able to execute Daml commands operating on this package.

com/daml/ledger/api/v2/reassignment.proto

AssignedEvent message, v2

Records that a contract has been assigned, and it can be used on the target synchronizer.

source : string

The ID of the source synchronizer. Must be a valid synchronizer id. Required

target : string

The ID of the target synchronizer. Must be a valid synchronizer id. Required

unassign_id : string

The ID from the unassigned event. For correlation capabilities. For one contract the (unassign_id, source synchronizer) pair is unique. Must be a valid LedgerString (as described in value.proto). Required

submitter : string

Party on whose behalf the assign command was executed. Empty if the assignment happened offline via the repair service. Must be a valid PartyIdString (as described in value.proto). Optional

reassignment_counter : uint64

Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter equals zero. Required

created_event : CreatedEvent

Required The offset of this event refers to the offset of the assignment, while the node_id is the index of within the batch.

Reassignment message, v2

Complete view of an on-ledger reassignment.

update_id : string

Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in value.proto). Required

command_id : string

The ID of the command which resulted in this reassignment. Missing for everyone except the submitting party on the submitting participant. Must be a valid LedgerString (as described in value.proto). Optional

workflow_id : string

The workflow ID used in reassignment command submission. Only set if the workflow_id for the command was set. Must be a valid LedgerString (as described in value.proto). Optional

offset : int64

The participant’s offset. The details of this field are described in community/ledger-api/README.md. Required, must be a valid absolute offset (positive integer).

events : ReassignmentEvent (repeated)

The collection of reassignment events. Required.

trace_context : TraceContext

Optional; ledger API trace context

The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead.

record_time : google.protobuf.Timestamp

The time at which the reassignment was recorded. The record time refers to the source/target synchronizer for an unassign/assign event respectively. Required

ReassignmentEvent message, v2

oneof event.unassigned : UnassignedEvent

oneof event.assigned : AssignedEvent

UnassignedEvent message, v2

Records that a contract has been unassigned, and it becomes unusable on the source synchronizer

unassign_id : string

The ID of the unassignment. This needs to be used as an input for a assign ReassignmentCommand. For one contract the (unassign_id, source synchronizer) pair is unique. Must be a valid LedgerString (as described in value.proto). Required

contract_id : string

The ID of the reassigned contract. Must be a valid LedgerString (as described in value.proto). Required

template_id : Identifier

The template of the reassigned contract. The identifier uses the package-id reference format.

Required

source : string

The ID of the source synchronizer Must be a valid synchronizer id Required

target : string

The ID of the target synchronizer Must be a valid synchronizer id Required

submitter : string

Party on whose behalf the unassign command was executed. Empty if the unassignment happened offline via the repair service. Must be a valid PartyIdString (as described in value.proto). Optional

reassignment_counter : uint64

Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter equals zero. Required

assignment_exclusivity : google.protobuf.Timestamp

Assignment exclusivity Before this time (measured on the target synchronizer), only the submitter of the unassignment can initiate the assignment Defined for reassigning participants. Optional

witness_parties : string (repeated)

The parties that are notified of this event. Required

package_name : string

The package name of the contract. Required

offset : int64

The offset of origin. Offsets are managed by the participant nodes. Reassignments can thus NOT be assumed to have the same offsets on different participant nodes. Required, it is a valid absolute offset (positive integer)

node_id : int32

The position of this event in the originating reassignment. Node IDs are not necessarily equal across participants, as these may see different projections/parts of reassignments. Required, must be valid node ID (non-negative integer)

com/daml/ledger/api/v2/reassignment_commands.proto

AssignCommand message, v2

Assign a contract

unassign_id : string

The ID from the unassigned event to be completed by this assignment. Must be a valid LedgerString (as described in value.proto). Required

source : string

The ID of the source synchronizer Must be a valid synchronizer id Required

target : string

The ID of the target synchronizer Must be a valid synchronizer id Required

ReassignmentCommand message, v2

oneof command.unassign_command : UnassignCommand

oneof command.assign_command : AssignCommand

ReassignmentCommands message, v2

workflow_id : string

Identifier of the on-ledger workflow that this command is a part of. Must be a valid LedgerString (as described in value.proto). Optional

user_id : string

Uniquely identifies the participant user that issued the command. Must be a valid UserIdString (as described in value.proto). Required unless authentication is used with a user token. In that case, the token’s user-id will be used for the request’s user_id.

command_id : string

Uniquely identifies the command. The triple (user_id, submitter, command_id) constitutes the change ID for the intended ledger change. The change ID can be used for matching the intended ledger changes with all their completions. Must be a valid LedgerString (as described in value.proto). Required

submitter : string

Party on whose behalf the command should be executed. If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request to act on behalf of the given party. Must be a valid PartyIdString (as described in value.proto). Required

submission_id : string

A unique identifier to distinguish completions for different submissions with the same change ID. Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission with the same change ID. Must be a valid LedgerString (as described in value.proto).

If omitted, the participant or the committer may set a value of their choice. Optional

commands : ReassignmentCommand (repeated)

Individual elements of this reassignment. Must be non-empty.

UnassignCommand message, v2

Unassign a contract

contract_id : string

The ID of the contract the client wants to unassign. Must be a valid LedgerString (as described in value.proto). Required

source : string

The ID of the source synchronizer Must be a valid synchronizer id Required

target : string

The ID of the target synchronizer Must be a valid synchronizer id Required

com/daml/ledger/api/v2/state_service.proto

StateService, v2

Allows clients to get state from the ledger.

GetActiveContracts method, v2

Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. If there are no active contracts, the stream returns a single response message with the offset at which the snapshot has been taken. Clients SHOULD use the offset in the last GetActiveContractsResponse message to continue streaming transactions with the update service. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end.

GetConnectedSynchronizers method, v2

Get the list of connected synchronizers at the time of the query.

GetLedgerEnd method, v2

Get the current ledger end. Subscriptions started with the returned offset will serve events after this RPC was called.

GetLatestPrunedOffsets method, v2

Get the latest successfully pruned ledger offsets

ActiveContract message, v2

created_event : CreatedEvent

Required The event as it appeared in the context of its last update (i.e. daml transaction or reassignment). In particular, the last offset, node_id pair is preserved. The last update is the most recent update created or assigned this contract on synchronizer_id synchronizer. The offset of the CreatedEvent might point to an already pruned update, therefore it cannot necessarily be used for lookups.

synchronizer_id : string

A valid synchronizer id Required

reassignment_counter : uint64

Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter equals zero. This field will be the reassignment_counter of the latest observable activation event on this synchronizer, which is before the active_at_offset. Required

GetActiveContractsRequest message, v2

If the given offset is different than the ledger end, and there are (un)assignments in-flight at the given offset, the snapshot may fail with “FAILED_PRECONDITION/PARTICIPANT_PRUNED_DATA_ACCESSED”. Note that it is ok to request acs snapshots for party migration with offsets other than ledger end, because party migration is not concerned with incomplete (un)assignments.

filter : TransactionFilter

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Templates to include in the served snapshot, per party. Optional, if specified event_format must be unset, if not specified event_format must be set.

verbose : bool

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. If enabled, values served over the API will contain more information than strictly necessary to interpret the data. In particular, setting the verbose flag to true triggers the ledger to include labels for record fields. Optional, if specified event_format must be unset.

active_at_offset : int64

The offset at which the snapshot of the active contracts will be computed. Must be no greater than the current ledger end offset. Must be greater than or equal to the last pruning offset. Required, must be a valid absolute offset (positive integer) or ledger begin offset (zero). If zero, the empty set will be returned.

event_format : EventFormat

Format of the contract_entries in the result. In case of CreatedEvent the presentation will be of TRANSACTION_SHAPE_ACS_DELTA. Optional for backwards compatibility, defaults to an EventFormat where:

  • filters_by_party is the filter.filters_by_party from this request

  • filters_for_any_party is the filter.filters_for_any_party from this request

  • verbose is the verbose field from this request

GetActiveContractsResponse message, v2

workflow_id : string

The workflow ID used in command submission which corresponds to the contract_entry. Only set if the workflow_id for the command was set. Must be a valid LedgerString (as described in value.proto). Optional

oneof contract_entry.active_contract : ActiveContract

The contract is active on the assigned synchronizer, meaning: there was an activation event on the given synchronizer ( created, assigned), which is not followed by a deactivation event (archived, unassigned) on the same synchronizer, until the active_at_offset. Since activeness is defined as a per synchronizer concept, it is possible, that a contract is active on one synchronizer, but already archived on another. There will be one such message for each synchronizer the contract is active on.

oneof contract_entry.incomplete_unassigned : IncompleteUnassigned

Included iff the unassigned event was before or at the active_at_offset, but there was no corresponding assigned event before or at the active_at_offset.

oneof contract_entry.incomplete_assigned : IncompleteAssigned

Important: this message is not indicating that the contract is active on the target synchronizer! Included iff the assigned event was before or at the active_at_offset, but there was no corresponding unassigned event before or at the active_at_offset.

GetConnectedSynchronizersRequest message, v2

party : string

The party of interest Must be a valid PartyIdString (as described in value.proto). Required

participant_id : string

The id of a participant whose mapping of a party to connected synchronizers is requested. Must be a valid participant-id retrieved through a prior call to getParticipantId. Defaults to the participant id of the host participant. Optional

GetConnectedSynchronizersResponse message, v2

connected_synchronizers : GetConnectedSynchronizersResponse.ConnectedSynchronizer (repeated)

GetConnectedSynchronizersResponse.ConnectedSynchronizer message, v2

synchronizer_alias : string

The alias of the synchronizer Required

synchronizer_id : string

The ID of the synchronizer Required

permission : ParticipantPermission

The permission on the synchronizer Required

GetLatestPrunedOffsetsRequest message, v2

Empty for now, but may contain fields in the future.

Message has no fields.

GetLatestPrunedOffsetsResponse message, v2

participant_pruned_up_to_inclusive : int64

It will always be a non-negative integer. If positive, the absolute offset up to which the ledger has been pruned, disregarding the state of all divulged contracts pruning. If zero, the ledger has not been pruned yet.

all_divulged_contracts_pruned_up_to_inclusive : int64

It will always be a non-negative integer. If positive, the absolute offset up to which all divulged events have been pruned on the ledger. It can be at or before the participant_pruned_up_to_inclusive offset. For more details about all divulged events pruning, see PruneRequest.prune_all_divulged_contracts in participant_pruning_service.proto. If zero, the divulged events have not been pruned yet.

GetLedgerEndRequest message, v2

Message has no fields.

GetLedgerEndResponse message, v2

offset : int64

It will always be a non-negative integer. If zero, the participant view of the ledger is empty. If positive, the absolute offset of the ledger as viewed by the participant.

IncompleteAssigned message, v2

assigned_event : AssignedEvent

Required

IncompleteUnassigned message, v2

created_event : CreatedEvent

Required The event as it appeared in the context of its last activation update (i.e. daml transaction or reassignment). In particular, the last activation offset, node_id pair is preserved. The last activation update is the most recent update created or assigned this contract on synchronizer_id synchronizer before the unassigned_event. The offset of the CreatedEvent might point to an already pruned update, therefore it cannot necessarily be used for lookups.

unassigned_event : UnassignedEvent

Required

ParticipantPermission enum, v2

Enum indicating the permission level that the participant has for the party whose connected synchronizers are being listed.

PARTICIPANT_PERMISSION_UNSPECIFIED

0

PARTICIPANT_PERMISSION_SUBMISSION

1

PARTICIPANT_PERMISSION_CONFIRMATION

2

participant can only confirm transactions

PARTICIPANT_PERMISSION_OBSERVATION

3

participant can only observe transactions

com/daml/ledger/api/v2/testing/time_service.proto

TimeService, v2/testing

Optional service, exposed for testing static time scenarios.

GetTime method, v2/testing

Returns the current time according to the ledger server.

SetTime method, v2/testing

Allows clients to change the ledger’s clock in an atomic get-and-set operation.

GetTimeRequest message, v2/testing

Message has no fields.

GetTimeResponse message, v2/testing

current_time : google.protobuf.Timestamp

The current time according to the ledger server.

SetTimeRequest message, v2/testing

current_time : google.protobuf.Timestamp

MUST precisely match the current time as it’s known to the ledger server.

new_time : google.protobuf.Timestamp

The time the client wants to set on the ledger. MUST be a point int time after current_time.

com/daml/ledger/api/v2/topology_transaction.proto

ParticipantAuthorizationAdded message, v2

party_id : string

Required

participant_id : string

Required

participant_permission : ParticipantPermission

Required

ParticipantAuthorizationChanged message, v2

party_id : string

Required

participant_id : string

Required

participant_permission : ParticipantPermission

Required

ParticipantAuthorizationRevoked message, v2

party_id : string

Required

participant_id : string

Required

TopologyEvent message, v2

oneof event.participant_authorization_changed : ParticipantAuthorizationChanged

oneof event.participant_authorization_revoked : ParticipantAuthorizationRevoked

oneof event.participant_authorization_added : ParticipantAuthorizationAdded

TopologyTransaction message, v2

update_id : string

Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in value.proto). Required

offset : int64

The absolute offset. The details of this field are described in community/ledger-api/README.md. Required, it is a valid absolute offset (positive integer).

synchronizer_id : string

A valid synchronizer id. Identifies the synchronizer that synchronized the topology transaction. Required

record_time : google.protobuf.Timestamp

The time at which the changes in the topology transaction become effective. There is a small delay between a topology transaction being sequenced and the changes it contains becoming effective. Topology transactions appear in order relative to a synchronizer based on their effective time rather than their sequencing time. Required

events : TopologyEvent (repeated)

A non-empty list of topology events. Required

trace_context : TraceContext

Optional; ledger API trace context

The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead.

com/daml/ledger/api/v2/trace_context.proto

TraceContext message, v2

oneof _traceparent.traceparent : string (optional)

https://www.w3.org/TR/trace-context/

oneof _tracestate.tracestate : string (optional)

com/daml/ledger/api/v2/transaction.proto

Transaction message, v2

Filtered view of an on-ledger transaction’s create and archive events.

update_id : string

Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in value.proto). Required

command_id : string

The ID of the command which resulted in this transaction. Missing for everyone except the submitting party. Must be a valid LedgerString (as described in value.proto). Optional

workflow_id : string

The workflow ID used in command submission. Must be a valid LedgerString (as described in value.proto). Optional

effective_at : google.protobuf.Timestamp

Ledger effective time. Required

events : Event (repeated)

The collection of events. Contains:

  • CreatedEvent or ArchivedEvent in case of ACS_DELTA transaction shape

  • CreatedEvent or ExercisedEvent in case of LEDGER_EFFECTS transaction shape

Required

offset : int64

The absolute offset. The details of this field are described in community/ledger-api/README.md. Required, it is a valid absolute offset (positive integer).

synchronizer_id : string

A valid synchronizer id. Identifies the synchronizer that synchronized the transaction. Required

trace_context : TraceContext

Optional; ledger API trace context

The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead.

record_time : google.protobuf.Timestamp

The time at which the transaction was recorded. The record time refers to the synchronizer which synchronized the transaction. Required

TransactionTree message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Complete view of an on-ledger transaction.

update_id : string

Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in value.proto). Required

command_id : string

The ID of the command which resulted in this transaction. Missing for everyone except the submitting party. Must be a valid LedgerString (as described in value.proto). Optional

workflow_id : string

The workflow ID used in command submission. Only set if the workflow_id for the command was set. Must be a valid LedgerString (as described in value.proto). Optional

effective_at : google.protobuf.Timestamp

Ledger effective time. Required

offset : int64

The absolute offset. The details of this field are described in community/ledger-api/README.md. Required, it is a valid absolute offset (positive integer).

events_by_id : TransactionTree.EventsByIdEntry (repeated)

Changes to the ledger that were caused by this transaction. Nodes of the transaction tree. Each key must be a valid node ID (non-negative integer). Required

synchronizer_id : string

A valid synchronizer id. Identifies the synchronizer that synchronized the transaction. Required

trace_context : TraceContext

Optional; ledger API trace context

The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead.

record_time : google.protobuf.Timestamp

The time at which the transaction was recorded. The record time refers to the synchronizer which synchronized the transaction. Required

TransactionTree.EventsByIdEntry message, v2

key : int32

value : TreeEvent

TreeEvent message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Each tree event message type below contains a witness_parties field which indicates the subset of the requested parties that can see the event in question.

Note that transaction trees might contain events with _no_ witness parties, which were included simply because they were children of events which have witnesses.

oneof kind.created : CreatedEvent

The event as it appeared in the context of its original daml transaction on this participant node. In particular, the offset, node_id pair of the daml transaction are preserved.

oneof kind.exercised : ExercisedEvent

com/daml/ledger/api/v2/transaction_filter.proto

CumulativeFilter message, v2

A filter that matches all contracts that are either an instance of one of the template_filters or that match one of the interface_filters.

oneof identifier_filter.wildcard_filter : WildcardFilter

A wildcard filter that matches all templates Optional

oneof identifier_filter.interface_filter : InterfaceFilter

Include an InterfaceView for every InterfaceFilter matching a contract. The InterfaceFilter instances MUST each use a unique interface_id. Optional

oneof identifier_filter.template_filter : TemplateFilter

A template for which the data will be included in the create_arguments of a matching CreatedEvent. If a contract is simultaneously selected by a template filter and one or more interface filters, the corresponding include_created_event_blob are consolidated using an OR operation. Optional

EventFormat message, v2

A format for events which defines both which events should be included and what data should be computed and included for them.

Note that some of the filtering behavior depends on the TransactionShape, which is expected to be specified alongside usages of EventFormat.

filters_by_party : EventFormat.FiltersByPartyEntry (repeated)

Each key must be a valid PartyIdString (as described in value.proto). The interpretation of the filter depends on the transaction-shape being filtered:

  1. For ledger-effects create and exercise events are returned, for which the witnesses include at least one of the listed parties and match the per-party filter.

  2. For transaction and active-contract-set streams create and archive events are returned for all contracts whose stakeholders include at least one of the listed parties and match the per-party filter.

Optional

filters_for_any_party : Filters

Wildcard filters that apply to all the parties existing on the participant. The interpretation of the filters is the same with the per-party filter as described above. Optional

verbose : bool

If enabled, values served over the API will contain more information than strictly necessary to interpret the data. In particular, setting the verbose flag to true triggers the ledger to include labels for record fields. Optional

EventFormat.FiltersByPartyEntry message, v2

key : string

value : Filters

Filters message, v2

The union of a set of template filters, interface filters, or a wildcard.

cumulative : CumulativeFilter (repeated)

Every filter in the cumulative list expands the scope of the resulting stream. Each interface, template or wildcard filter means additional events that will match the query. The impact of include_interface_view and include_created_event_blob fields in the filters will also be accumulated. At least one cumulative filter MUST be specified. A template or an interface SHOULD NOT appear twice in the accumulative field. A wildcard filter SHOULD NOT be defined more than once in the accumulative field. Optional

InterfaceFilter message, v2

This filter matches contracts that implement a specific interface.

interface_id : Identifier

The interface that a matching contract must implement. The interface_id needs to be valid: corresponding interface should be defined in one of the available packages at the time of the query. Both package-name and package-id reference formats for the identifier are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.

Required

include_interface_view : bool

Whether to include the interface view on the contract in the returned CreatedEvent. Use this to access contract data in a uniform manner in your API client. Optional

include_created_event_blob : bool

Whether to include a created_event_blob in the returned CreatedEvent. Use this to access the contract create event payload in your API client for submitting it as a disclosed contract with future commands. Optional

ParticipantAuthorizationTopologyFormat message, v2

A format specifying which participant authorization topology transactions to include and how to render them.

parties : string (repeated)

List of parties for which the topology transactions should be sent. Empty means: for all parties.

TemplateFilter message, v2

This filter matches contracts of a specific template.

template_id : Identifier

A template for which the payload should be included in the response. The template_id needs to be valid: corresponding template should be defined in one of the available packages at the time of the query. Both package-name and package-id reference formats for the identifier are supported. Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.

Required

include_created_event_blob : bool

Whether to include a created_event_blob in the returned CreatedEvent. Use this to access the contract event payload in your API client for submitting it as a disclosed contract with future commands. Optional

TopologyFormat message, v2

A format specifying which topology transactions to include and how to render them.

include_participant_authorization_events : ParticipantAuthorizationTopologyFormat

Include participant authorization topology events in streams. Optional, if unset no participant authorization topology events are emitted in the stream.

TransactionFilter message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Used both for filtering create and archive events as well as for filtering transaction trees.

filters_by_party : TransactionFilter.FiltersByPartyEntry (repeated)

Each key must be a valid PartyIdString (as described in value.proto). The interpretation of the filter depends on the transaction-shape being filtered:

  1. For transaction trees (used in GetUpdateTreesResponse for backwards compatibility) all party keys used as wildcard filters, and all subtrees whose root has one of the listed parties as an informee are returned. If there are CumulativeFilter``s, those will control returned ``CreatedEvent fields where applicable, but will not be used for template/interface filtering.

  2. For ledger-effects create and exercise events are returned, for which the witnesses include at least one of the listed parties and match the per-party filter.

  3. For transaction and active-contract-set streams create and archive events are returned for all contracts whose stakeholders include at least one of the listed parties and match the per-party filter.

Required

filters_for_any_party : Filters

Wildcard filters that apply to all the parties existing on the participant. The interpretation of the filters is the same with the per-party filter as described above.

TransactionFilter.FiltersByPartyEntry message, v2

key : string

value : Filters

TransactionFormat message, v2

A format that specifies what events to include in Daml transactions and what data to compute and include for them.

event_format : EventFormat

Required

transaction_shape : TransactionShape

What transaction shape to use for interpreting the filters of the event format. Required

UpdateFormat message, v2

A format specifying what updates to include and how to render them.

include_transactions : TransactionFormat

Include Daml transactions in streams. Optional, if unset, no transactions are emitted in the stream.

include_reassignments : EventFormat

Include (un)assignments in the stream. The events in the result take the shape TRANSACTION_SHAPE_ACS_DELTA. Optional, if unset, no (un)assignments are emitted in the stream.

include_topology_events : TopologyFormat

Include topology events in streams. Optional, if unset no topology events are emitted in the stream.

WildcardFilter message, v2

This filter matches all templates.

include_created_event_blob : bool

Whether to include a created_event_blob in the returned CreatedEvent. Use this to access the contract create event payload in your API client for submitting it as a disclosed contract with future commands. Optional

TransactionShape enum, v2

Event shape for Transactions. Shapes are exclusive and only one of them can be defined in queries.

TRANSACTION_SHAPE_UNSPECIFIED

0

Following official proto3 convention, not intended for actual use.

TRANSACTION_SHAPE_ACS_DELTA

1

Transaction shape that is sufficient to maintain an accurate ACS view. The field witness_parties in events are populated as stakeholders, transaction filter will apply accordingly. This translates to create and archive events.

TRANSACTION_SHAPE_LEDGER_EFFECTS

2

Transaction shape that allows maintaining an ACS and also conveys detailed information about all exercises. The field witness_parties in events are populated as cumulative informees, transaction filter will apply accordingly. This translates to create, consuming exercise and non-consuming exercise.

com/daml/ledger/api/v2/update_service.proto

UpdateService, v2

Allows clients to read updates (transactions, (un)assignments, topology events) from the ledger.

GetUpdates and GetUpdateTrees provide a comprehensive stream of updates/changes which happened on the virtual shared ledger. These streams are indexed with ledger offsets, which are strictly increasing. The virtual shared ledger consist of changes happening on multiple synchronizers which are connected to the serving participant. Each update belongs to one synchronizer, this is provided in the result (the synchronizer_id field in Transaction and TransactionTree for transactions, the source field in UnassignedEvent and the target field in AssignedEvent). Consumers can rely on strong causal guarantees on the virtual shared ledger for a single synchronizer: updates which have greater offsets are happened after than updates with smaller offsets for the same synchronizer. Across different synchronizers this is not guaranteed.

GetUpdates method, v2

Read the ledger’s filtered update stream for the specified contents and filters. It returns the event types in accordance with the stream contents selected. Also the selection criteria for individual events depends on the transaction shape chosen.

  • ACS delta: a requesting party must be a stakeholder of an event for it to be included.

  • ledger effects: a requesting party must be a witness of an en event for it to be included.

GetUpdateTrees method, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Read the ledger’s complete transaction tree stream and related (un)assignments for a set of parties. The stream will be filtered only by the parties as wildcard parties. The template/interface filters describe the respective fields in the CreatedEvent results.

GetTransactionTreeByOffset method, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Lookup a transaction tree by its offset. For looking up a transaction instead of a transaction tree, please see GetTransactionByEventId If the transaction cannot be found for the request, or all the events are filtered, a TRANSACTION_NOT_FOUND error will be raised.

GetTransactionTreeById method, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Lookup a transaction tree by its ID. For looking up a transaction instead of a transaction tree, please see GetTransactionById If the transaction cannot be found for the request, or all the events are filtered, a TRANSACTION_NOT_FOUND error will be raised.

GetTransactionByOffset method, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Lookup a transaction by its offset. If there is no transaction with this offset, or all the events are filtered, a TRANSACTION_NOT_FOUND error will be raised. Use a wildcard template filter if you want to retrieve any transaction visible to the parties you can read as.

GetTransactionById method, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Lookup a transaction by its ID. If there is no transaction with this id, or all the events are filtered, a TRANSACTION_NOT_FOUND error will be raised. Use a wildcard template filter if you want to retrieve any transaction visible to the parties you can read as.

GetUpdateByOffset method, v2

Lookup an update by its offset. If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised.

GetUpdateById method, v2

Lookup an update by its ID. If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised.

GetTransactionByIdRequest message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0.

update_id : string

The ID of a particular transaction. Must be a valid LedgerString (as described in value.proto). Required

requesting_parties : string (repeated)

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. The parties whose events the client expects to see. Events that are not visible for the parties in this collection will not be present in the response. Each element must be a valid PartyIdString (as described in value.proto). Must be set for GetTransactionTreeById request. Optional for backwards compatibility for GetTransactionById request: if defined transaction_format must be unset (falling back to defaults).

transaction_format : TransactionFormat

Must be unset for GetTransactionTreeById request. Optional for GetTransactionById request for backwards compatibility: defaults to a transaction_format, where:

  • event_format.filters_by_party will have template-wildcard filters for all the requesting_parties

  • event_format.filters_for_any_party is unset

  • event_format.verbose = true

  • transaction_shape = TRANSACTION_SHAPE_ACS_DELTA

GetTransactionByOffsetRequest message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0.

offset : int64

The offset of the transaction being looked up. Must be a valid absolute offset (positive integer). Required

requesting_parties : string (repeated)

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. The parties whose events the client expects to see. Events that are not visible for the parties in this collection will not be present in the response. Each element must be a valid PartyIdString (as described in value.proto). Must be set for GetTransactionTreeByOffset request. Optional for backwards compatibility for GetTransactionByOffset request: if defined transaction_format must be unset (falling back to defaults).

transaction_format : TransactionFormat

Must be unset for GetTransactionTreeByOffset request. Optional for GetTransactionByOffset request for backwards compatibility: defaults to a TransactionFormat, where:

  • event_format.filters_by_party will have template-wildcard filters for all the requesting_parties

  • event_format.filters_for_any_party is unset

  • event_format.verbose = true

  • transaction_shape = TRANSACTION_SHAPE_ACS_DELTA

GetTransactionResponse message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0.

transaction : Transaction

Required

GetTransactionTreeResponse message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0.

transaction : TransactionTree

Required

GetUpdateByIdRequest message, v2

update_id : string

The ID of a particular update. Must be a valid LedgerString (as described in value.proto). Required

update_format : UpdateFormat

The format for the update. Required

GetUpdateByOffsetRequest message, v2

offset : int64

The offset of the update being looked up. Must be a valid absolute offset (positive integer). Required

update_format : UpdateFormat

The format for the update. Required

GetUpdateResponse message, v2

oneof update.transaction : Transaction

oneof update.reassignment : Reassignment

oneof update.topology_transaction : TopologyTransaction

GetUpdateTreesResponse message, v2

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0.

oneof update.transaction_tree : TransactionTree

oneof update.reassignment : Reassignment

oneof update.offset_checkpoint : OffsetCheckpoint

GetUpdatesRequest message, v2

begin_exclusive : int64

Beginning of the requested ledger section (non-negative integer). The response will only contain transactions whose offset is strictly greater than this. If zero, the stream will start from the beginning of the ledger. If positive, the streaming will start after this absolute offset. If the ledger has been pruned, this parameter must be specified and be greater than the pruning offset.

oneof _end_inclusive.end_inclusive : int64 (optional)

End of the requested ledger section. The response will only contain transactions whose offset is less than or equal to this. Optional, if empty, the stream will not terminate. If specified, the stream will terminate after this absolute offset (positive integer) is reached.

filter : TransactionFilter

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. Requesting parties with template filters. Template filters must be empty for GetUpdateTrees requests. Optional for backwards compatibility, if defined update_format must be unset

verbose : bool

Provided for backwards compatibility, it will be removed in the Canton version 3.4.0. If enabled, values served over the API will contain more information than strictly necessary to interpret the data. In particular, setting the verbose flag to true triggers the ledger to include labels, record and variant type ids for record fields. Optional for backwards compatibility, if defined update_format must be unset

update_format : UpdateFormat

Must be unset for GetUpdateTrees request. Optional for backwards compatibility for GetUpdates request: defaults to an UpdateFormat where:

  • include_transactions.event_format.filters_by_party = the filter.filters_by_party on this request

  • include_transactions.event_format.filters_for_any_party = the filter.filters_for_any_party on this request

  • include_transactions.event_format.verbose = the same flag specified on this request

  • include_transactions.transaction_shape = TRANSACTION_SHAPE_ACS_DELTA

  • include_reassignments.filter = the same filter specified on this request

  • include_reassignments.verbose = the same flag specified on this request

  • include_topology_events.include_participant_authorization_events.parties = all the parties specified in filter

GetUpdatesResponse message, v2

oneof update.transaction : Transaction

oneof update.reassignment : Reassignment

oneof update.offset_checkpoint : OffsetCheckpoint

oneof update.topology_transaction : TopologyTransaction

com/daml/ledger/api/v2/version_service.proto

VersionService, v2

Allows clients to retrieve information about the ledger API version

GetLedgerApiVersion method, v2

Read the Ledger API version

FeaturesDescriptor message, v2

experimental : ExperimentalFeatures

Features under development or features that are used for ledger implementation testing purposes only.

Daml applications SHOULD not depend on these in production.

user_management : UserManagementFeature

If set, then the Ledger API server supports user management. It is recommended that clients query this field to gracefully adjust their behavior for ledgers that do not support user management.

party_management : PartyManagementFeature

If set, then the Ledger API server supports party management configurability. It is recommended that clients query this field to gracefully adjust their behavior to maximum party page size.

offset_checkpoint : OffsetCheckpointFeature

It contains the timeouts related to the periodic offset checkpoint emission

GetLedgerApiVersionRequest message, v2

Message has no fields.

GetLedgerApiVersionResponse message, v2

version : string

The version of the ledger API.

features : FeaturesDescriptor

The features supported by this Ledger API endpoint.

Daml applications CAN use the feature descriptor on top of version constraints on the Ledger API version to determine whether a given Ledger API endpoint supports the features required to run the application.

See the feature descriptions themselves for the relation between Ledger API versions and feature presence.

OffsetCheckpointFeature message, v2

max_offset_checkpoint_emission_delay : google.protobuf.Duration

The maximum delay to emmit a new OffsetCheckpoint if it exists

PartyManagementFeature message, v2

max_parties_page_size : int32

The maximum number of parties the server can return in a single response (page).

UserManagementFeature message, v2

supported : bool

Whether the Ledger API server provides the user management service.

max_rights_per_user : int32

The maximum number of rights that can be assigned to a single user. Servers MUST support at least 100 rights per user. A value of 0 means that the server enforces no rights per user limit.

max_users_page_size : int32

The maximum number of users the server can return in a single response (page). Servers MUST support at least a 100 users per page. A value of 0 means that the server enforces no page size limit.

com/daml/ledger/api/v2/value.proto

Enum message, v2

A value with finite set of alternative representations.

enum_id : Identifier

Omitted from the transaction stream when verbose streaming is not enabled. Optional when submitting commands.

constructor : string

Determines which of the Variant’s alternatives is encoded in this message. Must be a valid NameString. Required

GenMap message, v2

entries : GenMap.Entry (repeated)

GenMap.Entry message, v2

key : Value

value : Value

Identifier message, v2

Unique identifier of an entity. Throughout this API, the following terminology is being used:

  • if a Daml package-id is encoded in the package_id field, it is referred to as using a “package-id reference format”

  • if a Daml package-name is encoded in the package_id field, it is referred to as using a “package-name reference format”

package_id : string

Generally, the identifier of the Daml package that contains the entity. When encoding a package-id, it must be a valid PackageIdString.

The field is overloaded to also be able to contain the package-name of the Daml package. This is supported if the entity referenced is either an interface or template. When representing the Daml package-name, the encoding is of form #<package-name> where # (not a valid package-id character) is used as a discriminator for signalling a package-name encoding.

Required

module_name : string

The dot-separated module name of the identifier. Required

entity_name : string

The dot-separated name of the entity (e.g. record, template, …) within the module. Required

List message, v2

A homogenous collection of values.

elements : Value (repeated)

The elements must all be of the same concrete value type. Optional

Optional message, v2

Corresponds to Java’s Optional type, Scala’s Option, and Haskell’s Maybe. The reason why we need to wrap this in an additional message is that we need to be able to encode the None case in the Value oneof.

value : Value

optional

Record message, v2

Contains nested values.

record_id : Identifier

Omitted from the transaction stream when verbose streaming is not enabled. Optional when submitting commands.

fields : RecordField (repeated)

The nested values of the record. Required

RecordField message, v2

A named nested value within a record.

label : string

When reading a transaction stream, it’s omitted if verbose streaming is not enabled. When submitting a command, it’s optional:

  • if all keys within a single record are present, the order in which fields appear does not matter. however, each key must appear exactly once.

  • if any of the keys within a single record are omitted, the order of fields MUST match the order of declaration in the Daml template.

Must be a valid NameString

value : Value

A nested value of a record. Required

TextMap message, v2

entries : TextMap.Entry (repeated)

TextMap.Entry message, v2

key : string

value : Value

Value message, v2

Encodes values that the ledger accepts as command arguments and emits as contract arguments.

The values encoding use different classes of non-empty strings as identifiers. Those classes are defined as follows:

  • NameStrings are strings with length <= 1000 that match the regexp [A-Za-z\$_][A-Za-z0-9\$_]*.

  • PackageIdStrings are strings with length <= 64 that match the regexp [A-Za-z0-9\-_ ]+.

  • PartyIdStrings are strings with length <= 255 that match the regexp [A-Za-z0-9:\-_ ]+.

  • LedgerStrings are strings with length <= 255 that match the regexp [A-Za-z0-9#:\-_/ ]+.

  • UserIdStrings are strings with length <= 128 that match the regexp [a-zA-Z0-9@^$.!`\-#+'~_|:]+.

oneof sum.unit : google.protobuf.Empty

This value is used for example for choices that don’t take any arguments.

oneof sum.bool : bool

True or false.

oneof sum.int64 : sint64

oneof sum.date : int32

Days since the unix epoch. Can go backwards. Limited from 0001-01-01 to 9999-12-31, also to be compatible with https://www.ietf.org/rfc/rfc3339.txt

oneof sum.timestamp : sfixed64

Microseconds since the UNIX epoch. Can go backwards. Fixed since the vast majority of values will be greater than 2^28, since currently the number of microseconds since the epoch is greater than that. Range: 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999Z, so that we can convert to/from https://www.ietf.org/rfc/rfc3339.txt

oneof sum.numeric : string

A Numeric, that is a decimal value with precision 38 (at most 38 significant digits) and a scale between 0 and 37 (significant digits on the right of the decimal point). The field has to match the regex

[+-]?\d{1,38}(.\d{0,37})?

and should be representable by a Numeric without loss of precision.

oneof sum.party : string

An agent operating on the ledger. Must be a valid PartyIdString.

oneof sum.text : string

A string.

oneof sum.contract_id : string

Identifier of an on-ledger contract. Commands which reference an unknown or already archived contract ID will fail. Must be a valid LedgerString.

oneof sum.optional : Optional

The Optional type, None or Some

oneof sum.list : List

Represents a homogeneous list of values.

oneof sum.text_map : TextMap

The TextMap type

oneof sum.gen_map : GenMap

The GenMap type

oneof sum.record : Record

oneof sum.variant : Variant

oneof sum.enum : Enum

The Enum type

Variant message, v2

A value with alternative representations.

variant_id : Identifier

Omitted from the transaction stream when verbose streaming is not enabled. Optional when submitting commands.

constructor : string

Determines which of the Variant’s alternatives is encoded in this message. Must be a valid NameString. Required

value : Value

The value encoded within the Variant. Required

Scalar Value Types

double

Java

Python

C++

C#

double

float

double

double

float

Java

Python

C++

C#

float

float

float

float

int32

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.

Java

Python

C++

C#

int

int

int32

int

int64

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.

Java

Python

C++

C#

long

int/long

int64

long

uint32

Uses variable-length encoding.

Java

Python

C++

C#

int

int/long

uint32

uint

uint64

Uses variable-length encoding.

Java

Python

C++

C#

long

int/long

uint64

ulong

sint32

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.

Java

Python

C++

C#

int

int

int32

int

sint64

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.

Java

Python

C++

C#

long

int/long

int64

long

fixed32

Always four bytes. More efficient than uint32 if values are often greater than 2^28.

Java

Python

C++

C#

int

int

uint32

uint

fixed64

Always eight bytes. More efficient than uint64 if values are often greater than 2^56.

Java

Python

C++

C#

long

int/long

uint64

ulong

sfixed32

Always four bytes.

Java

Python

C++

C#

int

int

int32

int

sfixed64

Always eight bytes.

Java

Python

C++

C#

long

int/long

int64

long

bool

Java

Python

C++

C#

boolean

boolean

bool

bool

string

A string must always contain UTF-8 encoded or 7-bit ASCII text.

Java

Python

C++

C#

String

str/unicode

string

string

bytes

May contain any arbitrary sequence of bytes.

Java

Python

C++

C#

ByteString

str

string

ByteString