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 ). Required |
|
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 | |
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. 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 |
trace_context |
TraceContext | Zipkin trace context. This field is a future extension point and is currently not supported. 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¶
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. In case of failure this method responds with: - 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. - ABORTED if the request is rejected or 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. - UNIMPLEMENTED if this method is not supported by the backing ledger. |
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¶
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. When the participant is run in mode requiring authentication, all the calls in this interface will respond with UNAUTHENTICATED, if the caller fails to provide a valid access token, and will respond with PERMISSION_DENIED, if the claims in the token are insufficient to perform a given operation. Subsequently, only specific errors of individual calls not related to authorization will be described.
Method name | Request type | Response type | Description |
---|---|---|---|
ListKnownPackages | ListKnownPackagesRequest | ListKnownPackagesResponse | Returns the details of all DAML-LF packages known to the backing participant. This request will always succeed. |
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 UNIMPLEMENTED, if DAR package uploading is not supported by the backing participant. - Respond with INVALID_ARGUMENT, if the DAR file is too big or malformed. The maximum supported size is implementation specific. |
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 hosted 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¶
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. When the participant is run in mode requiring authentication, all the calls in this interface will respond with UNAUTHENTICATED, if the caller fails to provide a valid access token, and will respond with PERMISSION_DENIED, if the claims in the token are insufficient to perform a given operation. Subsequently, only specific errors of individual calls not related to authorization will be described.
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. This method is expected to succeed provided the backing participant is healthy, otherwise it responds with INTERNAL grpc error. daml-on-sql: returns an identifier supplied on command line at launch time daml-on-kv-ledger: as above canton: returns globally unique identifier of the backing participant |
GetParties | GetPartiesRequest | GetPartiesResponse | Get the party details of the given parties. Only known parties will be returned in the list. This request will always succeed. |
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. This request will always succeed. |
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 UNIMPLEMENTED if synchronous party allocation is not supported by the backing participant. - Respond with INVALID_ARGUMENT if the provided hint and/or display name is invalid on the given ledger (see below). daml-on-sql: suggestion’s uniqueness is checked and call rejected if the identifier is already present 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 the surface protocol, the arguments take implicit values |
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. Required Must be a valid LedgerString (as described in value.proto ). |
|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. 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 ). Required |
|
application_id |
string | Only completions of commands submitted with the same application_id will be visible in the stream. Must be a valid LedgerString (as described in value.proto ). Required |
|
parties |
string | repeated | Non-empty list of parties whose data should be included. 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. 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 4 distinct manners:
INVALID_PARAMETER
gRPC error on malformed payloads and missing required fields.- Failure communicated in the gRPC error.
- Failure communicated in a Completion.
- A Checkpoint with
record_time
> commandmrt
arrives through the Completion Stream, and the command’s Completion was not visible before. In this case the command is lost.
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.
Interprocess tracing of command submissions may be achieved via Zipkin by filling out the trace_context
field.
The server will return a child context of the submitted one, (or a new one if the context was missing) on both the Completion and Transaction streams.
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 |
SubmitAndWaitForTransactionResponse¶
Field | Type | Label | Description |
---|---|---|---|
transaction |
Transaction | The flat transaction that resulted from the submitted command. Required |
SubmitAndWaitForTransactionTreeResponse¶
Field | Type | Label | Description |
---|---|---|---|
transaction |
TransactionTree | The transaction tree that resulted from the submitted command. Required |
SubmitAndWaitRequest¶
These commands are atomic, and will become transactions.
Field | Type | Label | Description |
---|---|---|---|
commands |
Commands | The commands to be submitted. Required | |
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
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.
Method name | Request type | Response type | Description |
---|---|---|---|
SubmitAndWait | SubmitAndWaitRequest | .google.protobuf.Empty | Submits a single composite command and waits for its result. Returns RESOURCE_EXHAUSTED if the number of in-flight commands reached the maximum (if a limit is configured). 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. Returns RESOURCE_EXHAUSTED if the number of in-flight commands reached the maximum (if a limit is configured). 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. Returns RESOURCE_EXHAUSTED if the number of in-flight commands reached the maximum (if a limit is configured). 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. Returns RESOURCE_EXHAUSTED if the number of in-flight commands reached the maximum (if a limit is configured). 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 | |
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
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 4 distinct manners:
INVALID_PARAMETER
gRPC error on malformed payloads and missing required fields.- Failure communicated in the gRPC error.
- Failure communicated in a Completion.
- A Checkpoint with
record_time
> commandmrt
arrives through the Completion Stream, and the command’s Completion was not visible before. In this case the command is lost.
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.
Interprocess tracing of command submissions may be achieved via Zipkin by filling out the trace_context
field.
The server will return a child context of the submitted one, (or a new one if the context was missing) on both the Completion and Transaction streams.
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 |
---|---|---|---|
create |
CreateCommand | ||
exercise |
ExerciseCommand | ||
exerciseByKey |
ExerciseByKeyCommand | ||
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 ). Required |
|
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 its part) that issued the command. This is used in tracing across different components and to let applications subscribe to their own submissions only. Must be a valid LedgerString (as described in value.proto ). Required |
|
command_id |
string | Uniquely identified the command. This identifier should be unique for each new command within an application domain, i.e., the triple (application_id, party, command_id) must be unique. It can be used for matching the requests with their respective completions. Must be a valid LedgerString (as described in value.proto ). Required |
|
party |
string | Party on whose behalf the command should be executed. It is up to the server to verify that the authorisation can be granted and that the connection has been authenticated for that party. Must be a valid PartyIdString (as described in value.proto ). Required |
|
commands |
Command | repeated | Individual elements of this atomic command. Must be non-empty. Required |
deduplication_time |
google.protobuf.Duration | The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error. Optional | |
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 |
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 |
|
trace_context |
TraceContext | The trace context submitted with the command. This field is a future extension point and is currently not supported. 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 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 descibed 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. 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 |
---|---|---|---|
created |
CreatedEvent | ||
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 | |
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. 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/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 ). Required |
|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. 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_time |
google.protobuf.Duration | The maximum value for the deduplication_time parameter of command submissions (as described in commands.proto ). This defines the maximum time window during which commands can be deduplicated. |
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¶
Field | Type | Label | Description |
---|---|---|---|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
GetLedgerIdentityResponse¶
Field | Type | Label | Description |
---|---|---|---|
ledger_id |
string | The ID of the ledger exposed by the server. Requests submitted with the wrong ledger ID will result in NOT_FOUND gRPC errors. Must be a valid LedgerString (as described in value.proto ). Required |
LedgerIdentityService¶
Allows clients to verify that the server they are communicating with exposes the ledger they wish to operate on. Note that every ledger has a unique ID.
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 |
---|---|---|---|
absolute |
string | The format of this string is specific to the ledger and opaque to the client. | |
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 ). Required |
|
package_id |
string | The ID of the requested package. Must be a valid PackageIdString (as described in value.proto ). Required |
|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
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 ). Required |
|
package_id |
string | The ID of the requested package. Must be a valid PackageIdString (as described in value.proto ). Required |
|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
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 ). Required |
|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. 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, or a NOT_FOUND error if the requested package is unknown. |
GetPackageStatus | GetPackageStatusRequest | GetPackageStatusResponse | Returns the status of a single package. |
com/daml/ledger/api/v1/testing/reset_service.proto¶
ResetRequest¶
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 ). Required |
ResetService¶
Service to reset the ledger state. The goal here is to be able to reset the state in a way that’s much faster compared to restarting the whole ledger application (be it a sandbox or the real ledger server).
Note that all state present in the ledger implementation will be reset, most importantly including the ledger ID. This means that clients will have to re-fetch the ledger ID from the identity service after hitting this endpoint.
The semantics are as follows:
- When the reset service returns the reset is initiated, but not completed;
- While the reset is performed, the ledger will not accept new requests. In fact we guarantee that ledger stops accepting new requests by the time the response to Reset is delivered;
- In-flight requests might be aborted, we make no guarantees on when or how quickly this happens;
- The ledger might be unavailable for a period of time before the reset is complete.
Given the above, the recommended mode of operation for clients of the reset endpoint is to call it, then call the ledger identity endpoint in a retry loop that will tolerate a brief window when the ledger is down, and resume operation as soon as the new ledger ID is delivered.
Note that this service will be available on the sandbox and might be available in some other testing environments, but will never be available in production.
Method name | Request type | Response type | Description |
---|---|---|---|
Reset | ResetRequest | .google.protobuf.Empty | Resets the ledger state. Note that loaded DARs won’t be removed – this only rolls back the ledger to genesis. |
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 ). Required |
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 ). Required |
|
current_time |
google.protobuf.Timestamp | MUST precisely match the current time as it’s known to the ledger server. On mismatch, an INVALID_PARAMETER gRPC error will be returned. |
|
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/trace_context.proto¶
TraceContext¶
Data structure to propagate Zipkin trace information. See https://github.com/openzipkin/b3-propagation Trace identifiers are 64 or 128-bit, but all span identifiers within a trace are 64-bit. All identifiers are opaque.
Field | Type | Label | Description |
---|---|---|---|
trace_id_high |
uint64 | If present, this is the high 64 bits of the 128-bit identifier. Otherwise the trace ID is 64 bits long. | |
trace_id |
uint64 | The TraceId is 64 or 128-bit in length and indicates the overall ID of the trace. Every span in a trace shares this ID. | |
span_id |
uint64 | The SpanId is 64-bit in length and indicates the position of the current operation in the trace tree. The value should not be interpreted: it may or may not be derived from the value of the TraceId. | |
parent_span_id |
google.protobuf.UInt64Value | The ParentSpanId is 64-bit in length and indicates the position of the parent operation in the trace tree. When the span is the root of the trace tree, the ParentSpanId is absent. | |
sampled |
bool | When the sampled decision is accept, report this span to the tracing system. When it is reject, do not. When B3 attributes are sent without a sampled decision, the receiver should make one. Once the sampling decision is made, the same value should be consistently sent downstream. |
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 |
|
trace_context |
TraceContext | Zipkin trace context. This field is a future extension point and is currently not supported. Optional |
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 triggerd this transaction. Required |
trace_context |
TraceContext | Zipkin trace context. This field is a future extension point and is currently not supported. Optional |
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 |
---|---|---|---|
created |
CreatedEvent | ||
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 data will be returned.
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 |
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 ). Required |
|
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. 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 ). Required |
|
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 |
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
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 ). Required |
|
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 |
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. Optional |
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 ). Required |
|
begin |
LedgerOffset | Beginning of the requested ledger section. Required | |
end |
LedgerOffset | End of the requested ledger section. Optional, if not set, the stream will not terminate. | |
filter |
TransactionFilter | Requesting parties with template filters. 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 | |
trace_context |
TraceContext | Server side tracing will be registered as a child of the submitted context. This field is a future extension point and is currently not supported. 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. |
GetTransactionTrees | GetTransactionsRequest | GetTransactionTreesResponse | Read the ledger’s complete transaction tree stream for a set of parties. |
GetTransactionByEventId | GetTransactionByEventIdRequest | GetTransactionResponse | Lookup a transaction tree by the ID of an event that appears within it. Returns NOT_FOUND if no such transaction exists. For looking up a transaction instead of a transaction tree, please see GetFlatTransactionByEventId |
GetTransactionById | GetTransactionByIdRequest | GetTransactionResponse | Lookup a transaction tree by its ID. Returns NOT_FOUND if no such transaction exists. 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. Returns NOT_FOUND if no such transaction exists. |
GetFlatTransactionById | GetTransactionByIdRequest | GetFlatTransactionResponse | Lookup a transaction by its ID. Returns NOT_FOUND if no such transaction exists. |
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 |
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 |
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 four classes of strings as identifiers. Those classes are
defined as follow:
- NameStrings are strings that match the regexp [A-Za-z\$_][A-Za-z0-9\$_]*
.
- PackageIdStrings are strings that match the regexp [A-Za-z0-9\-_ ]+
.
- PartyIdStrings are strings that match the regexp [A-Za-z0-9:\-_ ]+
.
- LedgerStrings are strings that match the regexp [A-Za-z0-9#:\-_/ ]+
.
Field | Type | Label | Description |
---|---|---|---|
record |
Record | ||
variant |
Variant | ||
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. | |
list |
List | Represents a homogeneous list of values. | |
int64 |
sint64 | ||
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. | |
text |
string | A string. | |
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 | |
party |
string | An agent operating on the ledger. Must be a valid PartyIdString. | |
bool |
bool | True or false. | |
unit |
google.protobuf.Empty | This value is used for example for choices that don’t take any arguments. | |
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 | |
optional |
Optional | The Optional type, None or Some | |
map |
Map | The Map type | |
enum |
Enum | The Enum type | |
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 |
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 |