Ledger API Reference

com/daml/ledger/api/v1/active_contracts_service.proto

GetActiveContractsRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

filter

TransactionFilter   Templates to include in the served snapshot, per party. Required

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

GetActiveContractsResponse

Field Type Label Description

offset

string   Included in the last message. The client should start consuming the transactions endpoint with this offset. The format of this field is described in ledger_offset.proto. Required

workflow_id

string   The workflow that created the contracts. Must be a valid LedgerString (as described in value.proto). Optional

active_contracts

CreatedEvent repeated The list of contracts that were introduced by the workflow with workflow_id at the offset. Must be a valid LedgerString (as described in value.proto). Optional

ActiveContractsService

Allows clients to initialize themselves according to a fairly recent state of the ledger without reading through all transactions that were committed since the ledger’s creation.

Method name Request type Response type Description
GetActiveContracts GetActiveContractsRequest GetActiveContractsResponse Returns a stream of the latest snapshot of active contracts. If there are no active contracts, the stream returns a single GetActiveContractsResponse 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 transaction service. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end.

com/daml/ledger/api/v1/admin/config_management_service.proto

GetTimeModelRequest

GetTimeModelResponse

Field Type Label Description

configuration_generation

int64   The current configuration generation. The generation is a monotonically increasing integer that is incremented on each change. Used when setting the time model.

time_model

TimeModel   The current ledger time model.

SetTimeModelRequest

Field Type Label Description

submission_id

string   Submission identifier used for tracking the request and to reject duplicate submissions. Required.

maximum_record_time

google.protobuf.Timestamp   Deadline for the configuration change after which the change is rejected.

configuration_generation

int64   The current configuration generation which we’re submitting the change against. This is used to perform a compare-and-swap of the configuration to safeguard against concurrent modifications. Required.

new_time_model

TimeModel   The new time model that replaces the current one. Required.

SetTimeModelResponse

Field Type Label Description

configuration_generation

int64   The configuration generation of the committed time model.

TimeModel

Field Type Label Description

avg_transaction_latency

google.protobuf.Duration   The expected average latency of a transaction, i.e., the average time from submitting the transaction to a [[WriteService]] and the transaction being assigned a record time. Required.

min_skew

google.protobuf.Duration   The minimimum skew between ledger time and record time: lt_TX >= rt_TX - minSkew Required.

max_skew

google.protobuf.Duration   The maximum skew between ledger time and record time: lt_TX <= rt_TX + maxSkew Required.

ConfigManagementService

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

The ledger configuration management service provides methods for the ledger administrator to change the current ledger configuration. The services provides methods to modify different aspects of the configuration.

Method name Request type Response type Description
GetTimeModel GetTimeModelRequest GetTimeModelResponse Return the currently active time model and the current configuration generation.
SetTimeModel SetTimeModelRequest SetTimeModelResponse Set the ledger time model.

com/daml/ledger/api/v1/admin/metering_report_service.proto

GetMeteringReportRequest

Authorized if and only if the authenticated user is a participant admin.

Field Type Label Description

from

google.protobuf.Timestamp   The from timestamp (inclusive). Required.

to

google.protobuf.Timestamp   The to timestamp (exclusive). If not provided, the server will default to its current time.

application_id

string   If set to a non-empty value, then the report will only be generated for that application. Optional.

GetMeteringReportResponse

Field Type Label Description

request

GetMeteringReportRequest   The actual request that was executed.

report_generation_time

google.protobuf.Timestamp   The time at which the report was computed.

metering_report_json

google.protobuf.Struct   The metering report json

MeteringReportService

Experimental API to retrieve metering reports.

Metering reports aim to provide the information necessary for billing participant and application operators.

Method name Request type Response type Description
GetMeteringReport GetMeteringReportRequest GetMeteringReportResponse Retrieve a metering report.

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

ObjectMeta

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

Field Type Label Description

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. 2. 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

Field Type Label Description

key

string    

value

string    

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

ListKnownPackagesRequest

ListKnownPackagesResponse

Field Type Label Description

package_details

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

PackageDetails

Field Type Label Description

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

source_description

string   Description provided by the backing participant describing where it got the package from. Optional

UploadDarFileRequest

Field Type Label Description

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

An empty message that is received when the upload operation succeeded.

PackageManagementService

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.

Method name Request type Response type Description
ListKnownPackages ListKnownPackagesRequest ListKnownPackagesResponse Returns the details of all Daml-LF packages known to the backing participant.
UploadDarFile UploadDarFileRequest UploadDarFileResponse 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

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

PruneRequest

Field Type Label Description

prune_up_to

string   Inclusive offset 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

Empty for now, but may contain fields in the future

ParticipantPruningService

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.

Method name Request type Response type Description
Prune PruneRequest PruneResponse 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.

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

AllocatePartyRequest

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

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

display_name

string   Human-readable name of the party to be added to the participant. It doesn’t have to be unique. Use of this field is discouraged. Use local_metadata instead. Optional

local_metadata

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

AllocatePartyResponse

Field Type Label Description

party_details

PartyDetails    

GetParticipantIdRequest

Required authorization: HasRight(ParticipantAdmin)

GetParticipantIdResponse

Field Type Label Description

participant_id

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

GetPartiesRequest

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

parties

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

GetPartiesResponse

Field Type Label Description

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

Required authorization: HasRight(ParticipantAdmin)

ListKnownPartiesResponse

Field Type Label Description

party_details

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

PartyDetails

Field Type Label Description

party

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

display_name

string   Human readable name associated with the party at allocation time. Caution, it might not be unique. Use of this field is discouraged. Use the local_metadata field instead. Optional

is_local

bool   true if party is hosted by the participant. Optional

local_metadata

ObjectMeta   Participant-local metadata of this party. Optional, Modifiable

UpdatePartyDetailsRequest

Required authorization: HasRight(ParticipantAdmin) In a scenario when a party is known to this participant but has been allocated through a different participant, the resource version of it might be not set on this participant until after the first update RPC has been completed.

Field Type Label Description

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’ and ‘display_name’ 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.v1.admin.UpdateUserRequest. Required

UpdatePartyDetailsResponse

Field Type Label Description

party_details

PartyDetails   Updated party details

PartyManagementService

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 the fact HasRight(r) denoting whether the authenticated user has right r.

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.

Method name Request type Response type Description
GetParticipantId GetParticipantIdRequest GetParticipantIdResponse 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 GetPartiesRequest GetPartiesResponse Get the party details of the given parties. Only known parties will be returned in the list.
ListKnownParties ListKnownPartiesRequest ListKnownPartiesResponse 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 AllocatePartyRequest AllocatePartyResponse 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 UpdatePartyDetailsRequest UpdatePartyDetailsResponse Update selected modifiable participant-local attributes of a party details resource. Can update the participant’s local information for both local and non-local parties.

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

CreateUserRequest

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

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

Field Type Label Description

user

User   Created user.

DeleteUserRequest

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

user_id

string   The user to delete. Required

DeleteUserResponse

Does not (yet) contain any data.

GetUserRequest

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

Field Type Label Description

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. Required

GetUserResponse

Field Type Label Description

user

User   Retrieved user.

GrantUserRightsRequest

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

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

user_id

string   The user to whom to grant rights. Required

rights

Right repeated The rights to grant. Optional

GrantUserRightsResponse

Field Type Label Description

newly_granted_rights

Right repeated The rights that were newly granted by the request.

ListUserRightsRequest

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

Field Type Label Description

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

ListUserRightsResponse

Field Type Label Description

rights

Right repeated All rights of the user.

ListUsersRequest

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

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

ListUsersResponse

Field Type Label Description

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

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

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

user_id

string   The user from whom to revoke rights. Required

rights

Right repeated The rights to revoke. Optional

RevokeUserRightsResponse

Field Type Label Description

newly_revoked_rights

Right repeated The rights that were actually revoked by the request.

Right.CanActAs

Field Type Label Description

party

string   The right to authorize commands for this party.

Right.CanReadAs

Field Type Label Description

party

string   The right to read ledger data visible to this party.

Right.ParticipantAdmin

The right to administrate the participant node.

UpdateUserRequest

Required authorization: HasRight(ParticipantAdmin)

Field Type Label Description

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.v1.admin.UpdatePartyDetailsRequest. Required

UpdateUserResponse

Field Type Label Description

user

User   Updated user

User

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

Read the Authorization documentation to learn more.

Field Type Label Description

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

UserManagementService

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 two 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.

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.

Method name Request type Response type Description
CreateUser CreateUserRequest CreateUserResponse Create a new user.
GetUser GetUserRequest GetUserResponse Get the user data of a specific user or the authenticated user.
UpdateUser UpdateUserRequest UpdateUserResponse Update selected modifiable attribute of a user resource described by the User message.
DeleteUser DeleteUserRequest DeleteUserResponse Delete an existing user and all its rights.
ListUsers ListUsersRequest ListUsersResponse List all existing users.
GrantUserRights GrantUserRightsRequest GrantUserRightsResponse Grant rights to a user. Granting rights does not affect the resource version of the corresponding user.
RevokeUserRights RevokeUserRightsRequest RevokeUserRightsResponse Revoke rights from a user. Revoking rights does not affect the resource version of the corresponding user.
ListUserRights ListUserRightsRequest ListUserRightsResponse List the set of all rights granted to a user.

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

Checkpoint

Checkpoints may be used to:

  • detect time out of commands.
  • provide an offset which can be used to restart consumption.
Field Type Label Description

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

offset

LedgerOffset   May be used in a subsequent CompletionStreamRequest to resume the consumption of this stream at a later time. Required

CompletionEndRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

CompletionEndResponse

Field Type Label Description

offset

LedgerOffset   This offset can be used in a CompletionStreamRequest message. Required

CompletionStreamRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger id reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

application_id

string   Only completions of commands submitted with the same application_id will be visible in the stream. Must be a valid ApplicationIdString (as described in value.proto). Required unless authentication is used with a user token or a custom token specifying an application-id. In that case, the token’s user-id, respectively application-id, will be used for the request’s application_id.

parties

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

offset

LedgerOffset   This field indicates the minimum offset for completions. This can be used to resume an earlier completion stream. This offset is exclusive: the response will only contain commands whose offset is strictly greater than this. Optional, if not set the ledger uses the current ledger end offset instead.

CompletionStreamResponse

Field Type Label Description

checkpoint

Checkpoint   This checkpoint may be used to restart consumption. The checkpoint is after any completions in this response. Optional

completions

Completion repeated If set, one or more completions.

CommandCompletionService

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 Transaction 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.

Method name Request type Response type Description
CompletionStream CompletionStreamRequest CompletionStreamResponse Subscribe to command completion events.
CompletionEnd CompletionEndRequest CompletionEndResponse Returns the offset after the latest completion.

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

SubmitAndWaitForTransactionIdResponse

Field Type Label Description

transaction_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

string   The format of this field is described in ledger_offset.proto. Optional

SubmitAndWaitForTransactionResponse

Field Type Label Description

transaction

Transaction   The flat transaction that resulted from the submitted command. Required

completion_offset

string   The format of this field is described in ledger_offset.proto. Optional

SubmitAndWaitForTransactionTreeResponse

Field Type Label Description

transaction

TransactionTree   The transaction tree that resulted from the submitted command. Required

completion_offset

string   The format of this field is described in ledger_offset.proto. Optional

SubmitAndWaitRequest

These commands are atomic, and will become transactions.

Field Type Label Description

commands

Commands   The commands to be submitted. Required

CommandService

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 MAY choose to produce a completion event for a rejection of a duplicate command.

Method name Request type Response type Description
SubmitAndWait SubmitAndWaitRequest .google.protobuf.Empty Submits a single composite command and waits for its result. Propagates the gRPC error of failed submissions including Daml interpretation errors.
SubmitAndWaitForTransactionId SubmitAndWaitRequest SubmitAndWaitForTransactionIdResponse Submits a single composite command, waits for its result, and returns the transaction id. Propagates the gRPC error of failed submissions including Daml interpretation errors.
SubmitAndWaitForTransaction SubmitAndWaitRequest SubmitAndWaitForTransactionResponse 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 SubmitAndWaitRequest SubmitAndWaitForTransactionTreeResponse 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.

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

SubmitRequest

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.

Field Type Label Description

commands

Commands   The commands to be submitted in a single transaction. Required

CommandSubmissionService

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 Transaction 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.

Method name Request type Response type Description
Submit SubmitRequest .google.protobuf.Empty Submit a single composite command.

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

Command

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

Field Type Label Description
oneof command.create CreateCommand    
oneof command.exercise ExerciseCommand    
oneof command.exerciseByKey ExerciseByKeyCommand    
oneof command.createAndExercise CreateAndExerciseCommand    

Commands

A composite command that groups multiple commands together.

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

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

application_id

string   Uniquely identifies the application or participant user that issued the command. Must be a valid ApplicationIdString (as described in value.proto). Required unless authentication is used with a user token or a custom token specifying an application-id. In that case, the token’s user-id, respectively application-id, will be used for the request’s application_id.

command_id

string   Uniquely identifies the command. The triple (application_id, party + act_as, command_id) constitutes the change ID for the intended ledger change, where party + 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

party

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). Deprecated in favor of the act_as field. If both are set, then the effective list of parties on whose behalf the command should be executed is the union of all parties listed in party and act_as. Optional

commands

Command repeated Individual elements of this atomic command. Must be non-empty. Required
oneof deduplication_period.deduplication_time google.protobuf.Duration   Specifies the length of the deduplication period. Same semantics apply as for deduplication_duration. Must be non-negative. Must not exceed the maximum deduplication time (see ledger_configuration_service.proto).
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 (see ledger_configuration_service.proto).
oneof deduplication_period.deduplication_offset string   Specifies the start of the deduplication period by a completion stream offset (exclusive). Must be a valid LedgerString (as described in ledger_offset.proto).

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. This field supersedes the party field. The effective set of parties on whose behalf the command should be executed is the union of all parties listed in party and act_as, which must be non-empty. Each element must be a valid PartyIdString (as described in value.proto). Optional

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

CreateAndExerciseCommand

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

Field Type Label Description

template_id

Identifier   The template of the contract the client wants to create. 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

Create a new contract instance based on a template.

Field Type Label Description

template_id

Identifier   The template of contract the client wants to create. Required

create_arguments

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

DisclosedContract

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

Field Type Label Description

template_id

Identifier   The template id of the contract. Required

contract_id

string   The contract id Required
oneof arguments.create_arguments Record   The contract arguments as typed Record
oneof arguments.create_arguments_blob google.protobuf.Any   The contract arguments specified using an opaque blob extracted from the create_arguments_blob field of a com.daml.ledger.api.v1.CreatedEvent.

metadata

ContractMetadata   The contract metadata from the create event. Required

ExerciseByKeyCommand

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

Field Type Label Description

template_id

Identifier   The template of contract the client wants to exercise. 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

Exercise a choice on an existing contract.

Field Type Label Description

template_id

Identifier   The template of contract the client wants to exercise. 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

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

Completion

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

Field Type Label Description

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

transaction_id

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

application_id

string   The application-id or user-id that was used for the submission, as described in commands.proto. Must be a valid ApplicationIdString (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 union of party and act_as from commands.proto. 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 string   Specifies the start of the deduplication period by a completion stream offset (exclusive).
Must be a valid LedgerString (as described in value.proto).
    • 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.

com/daml/ledger/api/v1/contract_metadata.proto

ContractMetadata

Contract-related metadata used in DisclosedContract (that can be included in command submission) or forwarded as part of the CreateEvent in Active Contract Set or Transaction streams.

Field Type Label Description

created_at

google.protobuf.Timestamp   Ledger effective time of the transaction that created the contract. Required

contract_key_hash

bytes   Hash of the contract key if defined. Optional

driver_metadata

bytes   Driver-specific metadata. This is opaque and cannot be decoded. Optional

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

ArchivedEvent

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

Field Type Label Description

event_id

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

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. 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

CreatedEvent

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

Field Type Label Description

event_id

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

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. 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 an InclusiveFilters exists with the template_id of this event among the template_ids, - or if there was a party, which is in the witness_parties of this event, and for which a wildcard filter exists (Filters without InclusiveFilters, or with an InclusiveFilters with empty template_ids and empty interface_filters). Optional

create_arguments_blob

google.protobuf.Any   Opaque representation of contract 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, this will include all the parties specified in the TransactionFilter that are informees of the event. If served as part of a flat transaction those will be limited to all parties specified in the TransactionFilter that are stakeholders of the contract (i.e. either signatories or observers). 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

agreement_text

google.protobuf.StringValue   The agreement text of the contract. We use StringValue to properly reflect optionality on the wire for backwards compatibility. This is necessary since the empty string is an acceptable (and in fact the default) agreement text, but also the default string in protobuf. This means a newer client works with an older sandbox seamlessly. Optional

metadata

ContractMetadata   Metadata of the contract. Required for contracts created after the introduction of explicit disclosure. Optional

Event

An event in the flat transaction stream can either be the creation or the archiving of a contract.

In the transaction 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. In the flat transaction stream you’ll only receive events that have witnesses.

Field Type Label Description
oneof event.created CreatedEvent    
oneof event.archived ArchivedEvent    

ExercisedEvent

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

Field Type Label Description

event_id

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

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. Required

interface_id

Identifier   The interface where the choice is defined, if inherited. 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

child_event_ids

string repeated References to further events in the same transaction that appeared as a result of this ExercisedEvent. It contains only the immediate children of this event, not all members of the subtree rooted at this node. The order of the children is the same as the event order in the transaction. Each element must be a valid LedgerString (as described in value.proto). Optional

exercise_result

Value   The result of exercising the choice. Required

InterfaceView

View of a create event matched by an interface filter.

Field Type Label Description

interface_id

Identifier   The interface implemented by the matched event. 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/v1/experimental_features.proto

CommandDeduplicationFeatures

Feature descriptors for command deduplication intended to be used for adapting Ledger API tests.

Field Type Label Description

deduplication_period_support

CommandDeduplicationPeriodSupport    

deduplication_type

CommandDeduplicationType    

max_deduplication_duration_enforced

bool   The ledger will reject any requests which specify a deduplication period which exceeds the specified max deduplication duration. This is also enforced for ledgers that convert deduplication periods specified as offsets to durations.

CommandDeduplicationPeriodSupport

Feature descriptor specifying how deduplication periods can be specified and how they are handled by the participant node.

Field Type Label Description

offset_support

CommandDeduplicationPeriodSupport.OffsetSupport    

duration_support

CommandDeduplicationPeriodSupport.DurationSupport    

ExperimentalCommitterEventLog

How the committer stores events.

Field Type Label Description

event_log_type

ExperimentalCommitterEventLog.CommitterEventLogType    

ExperimentalContractIds

See daml-lf/spec/contract-id.rst for more information on contract ID formats.

Field Type Label Description

v1

ExperimentalContractIds.ContractIdV1Support    

ExperimentalExplicitDisclosure

Enables the use of explicitly disclosed contracts for command submission

Field Type Label Description

supported

bool    

ExperimentalFeatures

See the feature message definitions for descriptions.

Field Type Label Description

self_service_error_codes

ExperimentalSelfServiceErrorCodes    

static_time

ExperimentalStaticTime    

command_deduplication

CommandDeduplicationFeatures    

optional_ledger_id

ExperimentalOptionalLedgerId    

contract_ids

ExperimentalContractIds    

committer_event_log

ExperimentalCommitterEventLog    

explicit_disclosure

ExperimentalExplicitDisclosure    

user_and_party_local_metadata_extensions

ExperimentalUserAndPartyLocalMetadataExtensions    

ExperimentalOptionalLedgerId

Ledger API does not require ledgerId to be set in the requests.

ExperimentalSelfServiceErrorCodes

GRPC self-service error codes are returned by the Ledger API.

ExperimentalStaticTime

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

Field Type Label Description

supported

bool    

ExperimentalUserAndPartyLocalMetadataExtensions

Whether the Ledger API supports: - is_deactivated user property, - metadata with annotations and resource version for users and parties, - update calls for users and parties.

Field Type Label Description

supported

bool    

CommandDeduplicationPeriodSupport.DurationSupport

How the participant node supports deduplication periods specified as durations.

Name Number Description

DURATION_NATIVE_SUPPORT

0  

DURATION_CONVERT_TO_OFFSET

1  

CommandDeduplicationPeriodSupport.OffsetSupport

How the participant node supports deduplication periods specified using offsets.

Name Number Description

OFFSET_NOT_SUPPORTED

0  

OFFSET_NATIVE_SUPPORT

1  

OFFSET_CONVERT_TO_DURATION

2  

CommandDeduplicationType

How the participant node reports duplicate command submissions.

Name Number Description

ASYNC_ONLY

0 Duplicate commands are exclusively reported asynchronously via completions.

ASYNC_AND_CONCURRENT_SYNC

1 Commands that are duplicates of concurrently submitted commands are reported synchronously via a gRPC error on the command submission, while all other duplicate commands are reported asynchronously via completions.

ExperimentalCommitterEventLog.CommitterEventLogType

Name Number Description

CENTRALIZED

0 Default. There is a single log.

DISTRIBUTED

1 There is more than one event log. Usually, when the committer itself is distributed. Or there are per-participant event logs. It may result in transaction IDs being different for the same transaction across participants, for example.

ExperimentalContractIds.ContractIdV1Support

Name Number Description

SUFFIXED

0 Contract IDs must be suffixed. Distributed ledger implementations must reject non-suffixed contract IDs.

NON_SUFFIXED

1 Contract IDs do not need to be suffixed. This can be useful for shorter contract IDs in centralized committer implementations. Suffixed contract IDs must also be supported.

com/daml/ledger/api/v1/ledger_configuration_service.proto

GetLedgerConfigurationRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

GetLedgerConfigurationResponse

Field Type Label Description

ledger_configuration

LedgerConfiguration   The latest ledger configuration.

LedgerConfiguration

LedgerConfiguration contains parameters of the ledger instance that may be useful to clients.

Field Type Label Description

max_deduplication_duration

google.protobuf.Duration   If a command submission specifies a deduplication period of length up to max_deduplication_duration, the submission SHOULD not be rejected with FAILED_PRECONDITION because the deduplication period starts too early. The deduplication period is measured on a local clock of the participant or Daml ledger, and therefore subject to clock skews and clock drifts. Command submissions with longer periods MAY get accepted though.

LedgerConfigurationService

LedgerConfigurationService allows clients to subscribe to changes of the ledger configuration.

Method name Request type Response type Description
GetLedgerConfiguration GetLedgerConfigurationRequest GetLedgerConfigurationResponse Returns the latest configuration as the first response, and publishes configuration updates in the same stream.

com/daml/ledger/api/v1/ledger_identity_service.proto

GetLedgerIdentityRequest

GetLedgerIdentityResponse

Field Type Label Description

ledger_id

string   The ID of the ledger exposed by the server. Must be a valid LedgerString (as described in value.proto). Optional

LedgerIdentityService

DEPRECATED: This service is now deprecated and ledger identity string is optional for all Ledger API requests.

Allows clients to verify that the server they are communicating with exposes the ledger they wish to operate on.

Method name Request type Response type Description
GetLedgerIdentity GetLedgerIdentityRequest GetLedgerIdentityResponse Clients may call this RPC to return the identifier of the ledger they are connected to.

com/daml/ledger/api/v1/ledger_offset.proto

LedgerOffset

Describes a specific point on the ledger.

The Ledger API endpoints that take offsets allow to specify portions of the ledger that are relevant for the client to read.

Offsets returned by the Ledger API can be used as-is (e.g. to keep track of processed transactions and provide a restart point to use in case of need).

The format of absolute offsets is opaque to the client: no client-side transformation of an offset is guaranteed to return a meaningful offset.

The server implementation ensures internally that offsets are lexicographically comparable.

Field Type Label Description
oneof value.absolute string   The format of this string is specific to the ledger and opaque to the client.
oneof value.boundary LedgerOffset.LedgerBoundary    

LedgerOffset.LedgerBoundary

Name Number Description

LEDGER_BEGIN

0 Refers to the first transaction.

LEDGER_END

1 Refers to the currently last transaction, which is a moving target.

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

GetPackageRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

package_id

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

GetPackageResponse

Field Type Label Description

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

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

package_id

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

GetPackageStatusResponse

Field Type Label Description

package_status

PackageStatus   The status of the package.

ListPackagesRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

ListPackagesResponse

Field Type Label Description

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

Name Number Description

SHA256

0  

PackageStatus

Name Number Description

UNKNOWN

0 The server is not aware of such a package.

REGISTERED

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

PackageService

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

Method name Request type Response type Description
ListPackages ListPackagesRequest ListPackagesResponse Returns the identifiers of all supported packages.
GetPackage GetPackageRequest GetPackageResponse Returns the contents of a single package.
GetPackageStatus GetPackageStatusRequest GetPackageStatusResponse Returns the status of a single package.

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

GetTimeRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as describe in value.proto). Optional

GetTimeResponse

Field Type Label Description

current_time

google.protobuf.Timestamp   The current time according to the ledger server.

SetTimeRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as describe in value.proto). Optional

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.

TimeService

Optional service, exposed for testing static time scenarios.

Method name Request type Response type Description
GetTime GetTimeRequest GetTimeResponse Returns a stream of time updates. Always returns at least one response, where the first one is the current time. Subsequent responses are emitted whenever the ledger server’s time is updated.
SetTime SetTimeRequest .google.protobuf.Empty Allows clients to change the ledger’s clock in an atomic get-and-set operation.

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

Transaction

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

Field Type Label Description

transaction_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. Must be a valid LedgerString (as described in value.proto). Required

events

Event repeated The collection of events. Only contains CreatedEvent or ArchivedEvent. Required

offset

string   The absolute offset. The format of this field is described in ledger_offset.proto. Required

TransactionTree

Complete view of an on-ledger transaction.

Field Type Label Description

transaction_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

string   The absolute offset. The format of this field is described in ledger_offset.proto. Required

events_by_id

TransactionTree.EventsByIdEntry repeated Changes to the ledger that were caused by this transaction. Nodes of the transaction tree. Each key be a valid LedgerString (as describe in value.proto). Required

root_event_ids

string repeated Roots of the transaction tree. Each element must be a valid LedgerString (as describe in value.proto). The elements are in the same order as the commands in the corresponding Commands object that triggered this transaction. Required

TransactionTree.EventsByIdEntry

Field Type Label Description

key

string    

value

TreeEvent    

TreeEvent

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.

Field Type Label Description
oneof kind.created CreatedEvent    
oneof kind.exercised ExercisedEvent    

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

Filters

The union of a set of contract filters, or a wildcard.

Field Type Label Description

inclusive

InclusiveFilters   If set, then contracts matching any of the InclusiveFilters match this filter. If not set, or if InclusiveFilters has empty template_ids and empty interface_filters: any contract matches this filter. Optional

InclusiveFilters

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

Field Type Label Description

template_ids

Identifier repeated A collection of templates for which the payload will be included in the create_arguments of a matching CreatedEvent. SHOULD NOT contain duplicates. All template_ids needs to be valid: corresponding template should be defined in one of the available packages at the time of the query. Optional

interface_filters

InterfaceFilter repeated Include an InterfaceView for every InterfaceFilter matching a contract. The InterfaceFilter``s MUST use unique ``interface_id``s. All ``interface_id needs to be valid: corresponding interface should be defined in one of the available packages at the time of the query. Optional

InterfaceFilter

This filter matches contracts that implement a specific interface.

Field Type Label Description

interface_id

Identifier   The interface that a matching contract must implement. Required

include_interface_view

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

include_create_arguments_blob

bool   Whether to include a create_arguments_blob in the returned CreateEvent. Use this to access the complete contract data in your API client for submitting it as a disclosed contract with future commands. Optional

TransactionFilter

A filter both for filtering create and archive events as well as for filtering transaction trees.

Field Type Label Description

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 stream being filtered: (1) For transaction tree streams only party filters with wildcards are allowed, and all subtrees whose root has one of the listed parties as an informee are returned. (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. Required

TransactionFilter.FiltersByPartyEntry

Field Type Label Description

key

string    

value

Filters    

com/daml/ledger/api/v1/transaction_service.proto

GetFlatTransactionResponse

Field Type Label Description

transaction

Transaction    

GetLedgerEndRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as describe in value.proto). Optional

GetLedgerEndResponse

Field Type Label Description

offset

LedgerOffset   The absolute offset of the current ledger end.

GetTransactionByEventIdRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

event_id

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

requesting_parties

string repeated 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). Required

GetTransactionByIdRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as describe in value.proto). Optional

transaction_id

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

requesting_parties

string repeated 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 be a valid PartyIdString (as describe in value.proto). Required

GetTransactionResponse

Field Type Label Description

transaction

TransactionTree    

GetTransactionTreesResponse

Field Type Label Description

transactions

TransactionTree repeated The list of transaction trees that matches the filter in GetTransactionsRequest for the GetTransactionTrees method.

GetTransactionsRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

begin

LedgerOffset   Beginning of the requested ledger section. This offset is exclusive: the response will only contain transactions whose offset is strictly greater than this. Required

end

LedgerOffset   End of the requested ledger section. This offset is inclusive: the response will only contain transactions whose offset is less than or equal to this. Optional, if not set, the stream will not terminate.

filter

TransactionFilter   Requesting parties with template filters. Template filters must be empty for GetTransactionTrees requests. Required

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

GetTransactionsResponse

Field Type Label Description

transactions

Transaction repeated The list of transactions that matches the filter in GetTransactionsRequest for the GetTransactions method.

TransactionService

Allows clients to read transactions from the ledger.

Method name Request type Response type Description
GetTransactions GetTransactionsRequest GetTransactionsResponse Read the ledger’s filtered transaction stream for a set of parties. Lists only creates and archives, but not other events. Omits all events on transient contracts, i.e., contracts that were both created and archived in the same transaction.
GetTransactionTrees GetTransactionsRequest GetTransactionTreesResponse Read the ledger’s complete transaction tree stream for a set of parties. The stream can be filtered only by parties, but not templates (template filter must be empty).
GetTransactionByEventId GetTransactionByEventIdRequest GetTransactionResponse Lookup a transaction tree by the ID of an event that appears within it. For looking up a transaction instead of a transaction tree, please see GetFlatTransactionByEventId
GetTransactionById GetTransactionByIdRequest GetTransactionResponse Lookup a transaction tree by its ID. For looking up a transaction instead of a transaction tree, please see GetFlatTransactionById
GetFlatTransactionByEventId GetTransactionByEventIdRequest GetFlatTransactionResponse Lookup a transaction by the ID of an event that appears within it.
GetFlatTransactionById GetTransactionByIdRequest GetFlatTransactionResponse Lookup a transaction by its ID.
GetLedgerEnd GetLedgerEndRequest GetLedgerEndResponse Get the current ledger end. Subscriptions started with the returned offset will serve transactions created after this RPC was called.

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

Enum

A value with finite set of alternative representations.

Field Type Label Description

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

Field Type Label Description

entries

GenMap.Entry repeated  

GenMap.Entry

Field Type Label Description

key

Value    

value

Value    

Identifier

Unique identifier of an entity.

Field Type Label Description

package_id

string   The identifier of the Daml package that contains the entity. Must be a valid PackageIdString. 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

A homogenous collection of values.

Field Type Label Description

elements

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

Map

Field Type Label Description

entries

Map.Entry repeated  

Map.Entry

Field Type Label Description

key

string    

value

Value    

Optional

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.

Field Type Label Description

value

Value   optional

Record

Contains nested values.

Field Type Label Description

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

A named nested value within a record.

Field Type Label Description

label

string   When reading a transaction stream, it’s omitted if verbose streaming is not enabled. When submitting a commmand, 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

Value

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 <= 256 that match the regexp [A-Za-z0-9:\-_ ]+. - LedgerStrings are strings with length <= 256 that match the regexp [A-Za-z0-9#:\-_/ ]+. - ApplicationIdStrings are strings with length <= 256 that match the regexp [A-Za-z0-9#:\-_/ @\|]+.

Field Type Label Description
oneof Sum.record Record    
oneof Sum.variant Variant    
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.list List   Represents a homogeneous list of values.
oneof Sum.int64 sint64    
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.text string   A string.
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.party string   An agent operating on the ledger. Must be a valid PartyIdString.
oneof Sum.bool bool   True or false.
oneof Sum.unit google.protobuf.Empty   This value is used for example for choices that don’t take any arguments.
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.optional Optional   The Optional type, None or Some
oneof Sum.map Map   The Map type
oneof Sum.enum Enum   The Enum type
oneof Sum.gen_map GenMap   The GenMap type

Variant

A value with alternative representations.

Field Type Label Description

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

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

FeaturesDescriptor

Field Type Label Description

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.

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.

GetLedgerApiVersionRequest

Field Type Label Description

ledger_id

string   Must correspond to the ledger ID reported by the Ledger Identification Service. Must be a valid LedgerString (as described in value.proto). Optional

GetLedgerApiVersionResponse

Field Type Label Description

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.

UserManagementFeature

Field Type Label Description

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.

VersionService

Allows clients to retrieve information about the ledger API version

Method name Request type Response type Description
GetLedgerApiVersion GetLedgerApiVersionRequest GetLedgerApiVersionResponse Read the Ledger API version

Scalar Value Types

.proto type Notes C++ type Java type Python type

double

  double double float

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. int32 int int

int64

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

uint32

Uses variable-length encoding. uint32 int int/long

uint64

Uses variable-length encoding. uint64 long int/long

sint32

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

sint64

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

fixed32

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

fixed64

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

sfixed32

Always four bytes. int32 int int

sfixed64

Always eight bytes. int64 long int/long

bool

  bool boolean boolean

string

A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode

bytes

May contain any arbitrary sequence of bytes. string ByteString str