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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (filters by party cannot be empty)

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation
SetTimeModel	SetTimeModelRequest	SetTimeModelResponse	Set the ledger time model. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if arguments are invalid, or the provided configuration generation does not match the current active configuration generation. The caller is expected to retry by again fetching current time model using ‘GetTimeModel’, applying changes and resubmitting. - DEADLINE_EXCEEDED: if the request times out. Note that a timed out request may have still been committed to the ledger. Application should re-query the current time model before retrying. - FAILED_PRECONDITION: if the request is rejected. - UNIMPLEMENTED: if this method is not supported by the backing ledger.

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

ApplicationMeteringReport

Field	Type	Label	Description
application_id	string		The application Id
event_count	int64		The event count for the application; i.e., the number of fetch, lookup-by-key, create, and exercise events in transactions issued by this application.

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.
participant_report	ParticipantMeteringReport		The computed report.
report_generation_time	google.protobuf.Timestamp		The time at which the report was computed.

ParticipantMeteringReport

Field	Type	Label	Description
participant_id	string		The reporting participant
is_final	bool		If the report is final it has been generated based on aggregated data so will never change in the future.
application_reports	ApplicationMeteringReport	repeated	Per application reports.

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/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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation
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 Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - UNIMPLEMENTED: if DAR package uploading is not supported by the backing participant - INVALID_ARGUMENT: if the DAR file is too big or malformed. The maximum supported size is implementation specific.

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 one of the following errors: - INVALID_ARGUMENT: if the payload, particularly the offset is malformed or missing - UNIMPLEMENTED: if the participant is based on a ledger that has not implemented pruning - INTERNAL: if the participant has encountered a failure and has potentially applied pruning partially. Such cases warrant verifying the participant health before retrying the prune with the same (or a larger, valid) offset. Successful retries after such errors ensure that different components reach a consistent pruning state. - FAILED_PRECONDITION: if the participant is not yet able to prune at the specified offset.

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

AllocatePartyRequest

Field	Type	Label	Description
party_id_hint	string		A hint to the backing 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. Optional

AllocatePartyResponse

Field	Type	Label	Description
party_details	PartyDetails

GetParticipantIdRequest

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

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

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. Caution, it might not be unique. Optional
is_local	bool		true if party is hosted by the backing participant. Required

PartyManagementService

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

Inspect the party management state of a ledger participant and modify the parts that are modifiable. We use ‘backing participant’ to refer to this specific participant in the methods of this API.

Method name	Request type	Response type	Description
GetParticipantId	GetParticipantIdRequest	GetParticipantIdResponse	Return the identifier of the backing 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 backing participant Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation
GetParties	GetPartiesRequest	GetPartiesResponse	Get the party details of the given parties. Only known parties will be returned in the list. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation
ListKnownParties	ListKnownPartiesRequest	ListKnownPartiesResponse	List the parties known by the backing participant. The list returned contains parties whose ledger access is facilitated by backing participant and the ones maintained elsewhere. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation
AllocateParty	AllocatePartyRequest	AllocatePartyResponse	Adds a new party to the set managed by the backing participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - UNIMPLEMENTED: if synchronous party allocation is not supported by the backing participant - DEADLINE_EXCEEDED: if the request times out - INVALID_ARGUMENT: if the provided hint and/or display name is invalid on the given ledger (see below). 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

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

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

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

RevokeUserRightsResponse

Field	Type	Label	Description
newly_revoked_rights	Right	repeated	The rights that were actually revoked by the request.

Right

A right granted to a user.

Field	Type	Label	Description
oneof kind.participant_admin	Right.ParticipantAdmin		The user can administrate 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.

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.

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

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.

Method name	Request type	Response type	Description
CreateUser	CreateUserRequest	CreateUserResponse	Create a new user. Errors: - ALREADY_EXISTS: if the user already exists - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields
GetUser	GetUserRequest	GetUserResponse	Get the user data of a specific user or the authenticated user. Errors: - NOT_FOUND: if the user doesn’t exist - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields
DeleteUser	DeleteUserRequest	DeleteUserResponse	Delete an existing user and all its rights. Errors: - NOT_FOUND: if the user doesn’t exist - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields
ListUsers	ListUsersRequest	ListUsersResponse	List all existing users. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields
GrantUserRights	GrantUserRightsRequest	GrantUserRightsResponse	Grant rights to a user. Errors: - NOT_FOUND: if the user doesn’t exist - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields
RevokeUserRights	RevokeUserRightsRequest	RevokeUserRightsResponse	Revoke rights from a user. Errors: - NOT_FOUND: if the user doesn’t exist - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields
ListUserRights	ListUserRightsRequest	ListUserRightsResponse	List the set of all rights granted to a user. Errors: - NOT_FOUND: if the user doesn’t exist - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - INVALID_ARGUMENT: if the payload is malformed or is missing required fields

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id - FAILED_PRECONDITION: if the ledger has been pruned after the subscription start offset - INVALID_ARGUMENT: if the payload is malformed or is missing required fields - OUT_OF_RANGE: if the absolute offset is after the end of the ledger
CompletionEnd	CompletionEndRequest	CompletionEndResponse	Returns the offset after the latest completion. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) due to for example contention on resources - ALREADY_EXISTS if a resource is duplicated (e.g. contract key) - INVALID_ARGUMENT: if the payload is malformed or is missing required fields - ABORTED: if the number of in-flight commands reached the maximum (if a limit is configured) - FAILED_PRECONDITION: on consistency errors (e.g. the contract key has changed since the submission) or if an interpretation error occurred - UNAVAILABLE: if the participant is not yet ready to submit commands or if the service has been shut down. - DEADLINE_EXCEEDED: if the request failed to receive its completion within the predefined timeout.
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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) due to for example contention on resources - ALREADY_EXISTS if a resource is duplicated (e.g. contract key) - INVALID_ARGUMENT: if the payload is malformed or is missing required fields - ABORTED: if the number of in-flight commands reached the maximum (if a limit is configured) - FAILED_PRECONDITION: on consistency errors (e.g. the contract key has changed since the submission) or if an interpretation error occurred - UNAVAILABLE: if the participant is not yet ready to submit commands or if the service has been shut down. - DEADLINE_EXCEEDED: if the request failed to receive its completion within the predefined timeout.
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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) due to for example contention on resources - ALREADY_EXISTS if a resource is duplicated (e.g. contract key) - INVALID_ARGUMENT: if the payload is malformed or is missing required fields - ABORTED: if the number of in-flight commands reached the maximum (if a limit is configured) - FAILED_PRECONDITION: on consistency errors (e.g. the contract key has changed since the submission) or if an interpretation error occurred - UNAVAILABLE: if the participant is not yet ready to submit commands or if the service has been shut down. - DEADLINE_EXCEEDED: if the request failed to receive its completion within the predefined timeout.
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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) due to for example contention on resources - ALREADY_EXISTS if a resource is duplicated (e.g. contract key) - INVALID_ARGUMENT: if the payload is malformed or is missing required fields - ABORTED: if the number of in-flight commands reached the maximum (if a limit is configured) - FAILED_PRECONDITION: on consistency errors (e.g. the contract key has changed since the submission) or if an interpretation error occurred - UNAVAILABLE: if the participant is not yet ready to submit commands or if the service has been shut down. - DEADLINE_EXCEEDED: if the request failed to receive its completion within the predefined timeout.

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) due to for example contention on resources - ALREADY_EXISTS if a resource is duplicated (e.g. contract key) - INVALID_ARGUMENT: if the payload is malformed or is missing required fields - ABORTED: if the number of in-flight commands reached the maximum (if a limit is configured) - FAILED_PRECONDITION: on consistency errors (e.g. the contract key has changed since the submission) or if an interpretation error occurred - UNAVAILABLE: if the participant is not yet ready to submit commands or if the service has been shut down.

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

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

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. For example, malformed or double spend transactions will result in a INVALID_ARGUMENT status. Transactions with invalid time time windows (which may be valid at a later date) will result in an ABORTED error. 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/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 ArchivedEvent``s, 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, if defined. Optional
create_arguments	Record		The arguments that have been used to create the contract. Required
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

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’s been exercised on the target contract. Must be a valid NameString (as described in value.proto). Required
choice_argument	Value		The argument the choice was made with. Required
acting_parties	string	repeated	The parties that made 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

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

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

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

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation

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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id
GetPackage	GetPackageRequest	GetPackageResponse	Returns the contents of a single package. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the requested package is unknown
GetPackageStatus	GetPackageStatusRequest	GetPackageStatusResponse	Returns the status of a single package. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the requested package is unknown

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. Errors: - INVALID_ARGUMENT: if current_time is invalid (it MUST precisely match the current time as it’s known to the ledger server)

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

Transaction

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

Field	Type	Label	Description
inclusive	InclusiveFilters		If not set, no filters will be applied. Optional

InclusiveFilters

If no internal fields are set, no filters will be applied.

Field	Type	Label	Description
template_ids	Identifier	repeated	A collection of templates. SHOULD NOT contain duplicates. Required

TransactionFilter

Used for filtering Transaction and Active Contract Set streams. Determines which on-ledger events will be served to the client.

Field	Type	Label	Description
filters_by_party	TransactionFilter.FiltersByPartyEntry	repeated	Keys of the map determine which parties’ on-ledger transactions are being queried. Values of the map determine which events are disclosed in the stream per party. At the minimum, a party needs to set an empty Filters message to receive any events. Each key must be a valid PartyIdString (as described in value.proto). 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. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (e.g. if before is not before end) - FAILED_PRECONDITION: if the ledger has been pruned after the subscription start offset - OUT_OF_RANGE: if the begin parameter value is not before the end of the ledger
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). Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (e.g. if before is not before end) - FAILED_PRECONDITION: if the ledger has been pruned after the subscription start offset - OUT_OF_RANGE: if the begin parameter value is not before the end of the ledger
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 Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or no such transaction exists - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (e.g. if requesting parties are invalid or empty)
GetTransactionById	GetTransactionByIdRequest	GetTransactionResponse	Lookup a transaction tree by its ID. For looking up a transaction instead of a transaction tree, please see GetFlatTransactionById Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or no such transaction exists - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (e.g. if requesting parties are invalid or empty)
GetFlatTransactionByEventId	GetTransactionByEventIdRequest	GetFlatTransactionResponse	Lookup a transaction by the ID of an event that appears within it. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or no such transaction exists - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (e.g. if requesting parties are invalid or empty)
GetFlatTransactionById	GetTransactionByIdRequest	GetFlatTransactionResponse	Lookup a transaction by its ID. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id or no such transaction exists - INVALID_ARGUMENT: if the payload is malformed or is missing required fields (e.g. if requesting parties are invalid or empty)
GetLedgerEnd	GetLedgerEndRequest	GetLedgerEndResponse	Get the current ledger end. Subscriptions started with the returned offset will serve transactions created after this RPC was called. Errors: - UNAUTHENTICATED: if the request does not include a valid access token - PERMISSION_DENIED: if the claims in the token are insufficient to perform a given operation - NOT_FOUND: if the request does not include a valid ledger id

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