diff --git a/community/daml-lf/ledger-api-value-proto/src/main/protobuf/com/daml/ledger/api/v2/value.proto b/community/daml-lf/ledger-api-value-proto/src/main/protobuf/com/daml/ledger/api/v2/value.proto index ae592ccf02..1a098a786a 100644 --- a/community/daml-lf/ledger-api-value-proto/src/main/protobuf/com/daml/ledger/api/v2/value.proto +++ b/community/daml-lf/ledger-api-value-proto/src/main/protobuf/com/daml/ledger/api/v2/value.proto @@ -10,6 +10,7 @@ package com.daml.ledger.api.v2; import "google/protobuf/empty.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "ValueOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/command_inspection_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/command_inspection_service.proto index d7af813a51..bdd0610bba 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/command_inspection_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/command_inspection_service.proto @@ -10,6 +10,7 @@ import "com/daml/ledger/api/v2/completion.proto"; import "com/daml/ledger/api/v2/value.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "CommandInspectionServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/identity_provider_config_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/identity_provider_config_service.proto index 2f1c9f4566..cf5a7bba71 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/identity_provider_config_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/identity_provider_config_service.proto @@ -5,8 +5,10 @@ syntax = "proto3"; package com.daml.ledger.api.v2.admin; +import "google/api/annotations.proto"; import "google/protobuf/field_mask.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "IdentityProviderConfigServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; @@ -37,20 +39,42 @@ option java_package = "com.daml.ledger.api.v2.admin"; service IdentityProviderConfigService { // Create a new identity provider configuration. // The request will fail if the maximum allowed number of separate configurations is reached. - rpc CreateIdentityProviderConfig(CreateIdentityProviderConfigRequest) returns (CreateIdentityProviderConfigResponse); + rpc CreateIdentityProviderConfig(CreateIdentityProviderConfigRequest) returns (CreateIdentityProviderConfigResponse) { + option (google.api.http) = { + post: "/v2/idps" + body: "*" + }; + } // Get the identity provider configuration data by id. - rpc GetIdentityProviderConfig(GetIdentityProviderConfigRequest) returns (GetIdentityProviderConfigResponse); + rpc GetIdentityProviderConfig(GetIdentityProviderConfigRequest) returns (GetIdentityProviderConfigResponse) { + option (google.api.http) = { + get: "/v2/idps/{identity_provider_id}" + }; + } // Update selected modifiable attribute of an identity provider config resource described // by the ``IdentityProviderConfig`` message. - rpc UpdateIdentityProviderConfig(UpdateIdentityProviderConfigRequest) returns (UpdateIdentityProviderConfigResponse); + rpc UpdateIdentityProviderConfig(UpdateIdentityProviderConfigRequest) returns (UpdateIdentityProviderConfigResponse) { + option (google.api.http) = { + patch: "/v2/idps/{identity_provider_config.identity_provider_id}" + body: "*" + }; + } // List all existing identity provider configurations. - rpc ListIdentityProviderConfigs(ListIdentityProviderConfigsRequest) returns (ListIdentityProviderConfigsResponse); + rpc ListIdentityProviderConfigs(ListIdentityProviderConfigsRequest) returns (ListIdentityProviderConfigsResponse) { + option (google.api.http) = { + get: "/v2/idps" + }; + } // Delete an existing identity provider configuration. - rpc DeleteIdentityProviderConfig(DeleteIdentityProviderConfigRequest) returns (DeleteIdentityProviderConfigResponse); + rpc DeleteIdentityProviderConfig(DeleteIdentityProviderConfigRequest) returns (DeleteIdentityProviderConfigResponse) { + option (google.api.http) = { + delete: "/v2/idps/{identity_provider_id}" + }; + } } message IdentityProviderConfig { diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/object_meta.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/object_meta.proto index 7cf96b7373..d34775c171 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/object_meta.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/object_meta.proto @@ -5,6 +5,7 @@ syntax = "proto3"; package com.daml.ledger.api.v2.admin; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "ObjectMetaOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/package_management_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/package_management_service.proto index 4656c328a2..300f8d725d 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/package_management_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/package_management_service.proto @@ -6,8 +6,10 @@ syntax = "proto3"; package com.daml.ledger.api.v2.admin; import "com/daml/ledger/api/v2/package_reference.proto"; +import "google/api/annotations.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "PackageManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; @@ -27,7 +29,12 @@ service PackageManagementService { // If vetting is enabled in the request, the DAR is checked for upgrade compatibility // with the set of the already vetted packages on the target vetting synchronizer // See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer. - rpc UploadDarFile(UploadDarFileRequest) returns (UploadDarFileResponse); + rpc UploadDarFile(UploadDarFileRequest) returns (UploadDarFileResponse) { + option (google.api.http) = { + post: "/v2/dars" + body: "*" + }; + } // Validates the DAR and checks the upgrade compatibility of the DAR's packages // with the set of the already vetted packages on the target vetting synchronizer. @@ -35,10 +42,20 @@ service PackageManagementService { // // The operation has no effect on the state of the participant or the Canton ledger: // the DAR payload and its packages are not persisted neither are the packages vetted. - rpc ValidateDarFile(ValidateDarFileRequest) returns (ValidateDarFileResponse); + rpc ValidateDarFile(ValidateDarFileRequest) returns (ValidateDarFileResponse) { + option (google.api.http) = { + post: "/v2/dars/validate" + body: "*" + }; + } // Update the vetted packages of this participant - rpc UpdateVettedPackages(UpdateVettedPackagesRequest) returns (UpdateVettedPackagesResponse); + rpc UpdateVettedPackages(UpdateVettedPackagesRequest) returns (UpdateVettedPackagesResponse) { + option (google.api.http) = { + post: "/v2/package-vetting/update" + body: "*" + }; + } } message ListKnownPackagesRequest {} diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/participant_pruning_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/participant_pruning_service.proto index dab9d5b45f..6c27a2e84d 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/participant_pruning_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/participant_pruning_service.proto @@ -5,6 +5,7 @@ syntax = "proto3"; package com.daml.ledger.api.v2.admin; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "ParticipantPruningServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/party_management_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/party_management_service.proto index 34e70f943a..5ec9c60dc9 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/party_management_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/party_management_service.proto @@ -7,8 +7,10 @@ package com.daml.ledger.api.v2.admin; import "com/daml/ledger/api/v2/admin/object_meta.proto"; import "com/daml/ledger/api/v2/crypto.proto"; +import "google/api/annotations.proto"; import "google/protobuf/field_mask.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "PartyManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; @@ -39,16 +41,28 @@ service PartyManagementService { // All horizontally scaled replicas should return the same id. // daml-on-kv-ledger: returns an identifier supplied on command line at launch time // canton: returns globally unique identifier of the participant - rpc GetParticipantId(GetParticipantIdRequest) returns (GetParticipantIdResponse); + rpc GetParticipantId(GetParticipantIdRequest) returns (GetParticipantIdResponse) { + option (google.api.http) = { + get: "/v2/parties/participant-id" + }; + } // Get the party details of the given parties. Only known parties will be // returned in the list. - rpc GetParties(GetPartiesRequest) returns (GetPartiesResponse); + rpc GetParties(GetPartiesRequest) returns (GetPartiesResponse) { + option (google.api.http) = { + get: "/v2/parties/{parties}" + }; + } // List the parties known by the participant. // The list returned contains parties whose ledger access is facilitated by // the participant and the ones maintained elsewhere. - rpc ListKnownParties(ListKnownPartiesRequest) returns (ListKnownPartiesResponse); + rpc ListKnownParties(ListKnownPartiesRequest) returns (ListKnownPartiesResponse) { + option (google.api.http) = { + get: "/v2/parties" + }; + } // Allocates a new party on a ledger and adds it to the set managed by the participant. // Caller specifies a party identifier suggestion, the actual identifier @@ -67,7 +81,12 @@ service PartyManagementService { // 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 - rpc AllocateParty(AllocatePartyRequest) returns (AllocatePartyResponse); + rpc AllocateParty(AllocatePartyRequest) returns (AllocatePartyResponse) { + option (google.api.http) = { + post: "/v2/parties" + body: "*" + }; + } // The external party must be hosted (at least) on this node with either confirmation or observation permissions // It can optionally be hosted on other nodes (then called a multi-hosted party). @@ -78,11 +97,21 @@ service PartyManagementService { // In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is // effectively allocated and ready to use, similarly to the AllocateParty behavior. // For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). - rpc AllocateExternalParty(AllocateExternalPartyRequest) returns (AllocateExternalPartyResponse); + rpc AllocateExternalParty(AllocateExternalPartyRequest) returns (AllocateExternalPartyResponse) { + option (google.api.http) = { + post: "/v2/parties/external/allocate" + body: "*" + }; + } // Update selected modifiable participant-local attributes of a party details resource. // Can update the participant's local information for local parties. - rpc UpdatePartyDetails(UpdatePartyDetailsRequest) returns (UpdatePartyDetailsResponse); + rpc UpdatePartyDetails(UpdatePartyDetailsRequest) returns (UpdatePartyDetailsResponse) { + option (google.api.http) = { + patch: "/v2/parties/{party_details.party}" + body: "*" + }; + } // Update the assignment of a party from one IDP to another. rpc UpdatePartyIdentityProviderId(UpdatePartyIdentityProviderIdRequest) returns (UpdatePartyIdentityProviderIdResponse); @@ -93,7 +122,12 @@ service PartyManagementService { // Note that this request will create a normal namespace using the same key for the // identity as for signing. More elaborate schemes such as multi-signature // or decentralized parties require you to construct the topology transactions yourself. - rpc GenerateExternalPartyTopology(GenerateExternalPartyTopologyRequest) returns (GenerateExternalPartyTopologyResponse); + rpc GenerateExternalPartyTopology(GenerateExternalPartyTopologyRequest) returns (GenerateExternalPartyTopologyResponse) { + option (google.api.http) = { + post: "/v2/parties/external/generate-topology" + body: "*" + }; + } } // Required authorization: ``HasRight(ParticipantAdmin)`` diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/user_management_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/user_management_service.proto index df207f2fbe..80e6bee53e 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/user_management_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/user_management_service.proto @@ -6,8 +6,10 @@ syntax = "proto3"; package com.daml.ledger.api.v2.admin; import "com/daml/ledger/api/v2/admin/object_meta.proto"; +import "google/api/annotations.proto"; import "google/protobuf/field_mask.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin"; option java_outer_classname = "UserManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.admin"; @@ -42,33 +44,74 @@ option java_package = "com.daml.ledger.api.v2.admin"; // In order to grant or revoke user rights use ``GrantRights' and ``RevokeRights`` RPCs. service UserManagementService { // Create a new user. - rpc CreateUser(CreateUserRequest) returns (CreateUserResponse); + rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) { + option (google.api.http) = { + post: "/v2/users" + body: "*" + }; + } // Get the user data of a specific user or the authenticated user. - rpc GetUser(GetUserRequest) returns (GetUserResponse); + rpc GetUser(GetUserRequest) returns (GetUserResponse) { + option (google.api.http) = { + get: "/v2/users/{user_id}" + }; + } // Update selected modifiable attribute of a user resource described by the ``User`` message. - rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse); + rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) { + option (google.api.http) = { + patch: "/v2/users/{user.id}" + body: "*" + }; + } // Delete an existing user and all its rights. - rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse); + rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse) { + option (google.api.http) = { + delete: "/v2/users/{user_id}" + }; + } // List all existing users. - rpc ListUsers(ListUsersRequest) returns (ListUsersResponse); + rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) { + option (google.api.http) = { + get: "/v2/users" + }; + } // Grant rights to a user. // Granting rights does not affect the resource version of the corresponding user. - rpc GrantUserRights(GrantUserRightsRequest) returns (GrantUserRightsResponse); + rpc GrantUserRights(GrantUserRightsRequest) returns (GrantUserRightsResponse) { + option (google.api.http) = { + post: "/v2/users/{user_id}/rights" + body: "*" + }; + } // Revoke rights from a user. // Revoking rights does not affect the resource version of the corresponding user. - rpc RevokeUserRights(RevokeUserRightsRequest) returns (RevokeUserRightsResponse); + rpc RevokeUserRights(RevokeUserRightsRequest) returns (RevokeUserRightsResponse) { + option (google.api.http) = { + patch: "/v2/users/{user_id}/rights" + body: "*" + }; + } // List the set of all rights granted to a user. - rpc ListUserRights(ListUserRightsRequest) returns (ListUserRightsResponse); + rpc ListUserRights(ListUserRightsRequest) returns (ListUserRightsResponse) { + option (google.api.http) = { + get: "/v2/users/{user_id}/rights" + }; + } // Update the assignment of a user from one IDP to another. - rpc UpdateUserIdentityProviderId(UpdateUserIdentityProviderIdRequest) returns (UpdateUserIdentityProviderIdResponse); + rpc UpdateUserIdentityProviderId(UpdateUserIdentityProviderIdRequest) returns (UpdateUserIdentityProviderIdResponse) { + option (google.api.http) = { + patch: "/v2/users/{user_id}/identity-provider-id" + body: "*" + }; + } } // Users and rights diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_completion_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_completion_service.proto index d81120378d..b5d2f52202 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_completion_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_completion_service.proto @@ -7,7 +7,9 @@ package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/completion.proto"; import "com/daml/ledger/api/v2/offset_checkpoint.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "CommandCompletionServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -29,7 +31,12 @@ option java_package = "com.daml.ledger.api.v2"; service CommandCompletionService { // Deprecated: please use ``GetCompletions`` instead. // Subscribe to command completion events. - rpc CompletionStream(CompletionStreamRequest) returns (stream CompletionStreamResponse); + rpc CompletionStream(CompletionStreamRequest) returns (stream CompletionStreamResponse) { + option (google.api.http) = { + post: "/v2/commands/completions" + body: "*" + }; + } // Subscribe to command completion events. // This streaming endpoint provides more flexibility in filtering than the predecessor ``CompletionStream``. diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto index 1f5cac5bf2..0f2fdca90c 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto @@ -10,7 +10,9 @@ import "com/daml/ledger/api/v2/reassignment.proto"; import "com/daml/ledger/api/v2/reassignment_commands.proto"; import "com/daml/ledger/api/v2/transaction.proto"; import "com/daml/ledger/api/v2/transaction_filter.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "CommandServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -23,15 +25,30 @@ option java_package = "com.daml.ledger.api.v2"; service CommandService { // Submits a single composite command and waits for its result. // Propagates the gRPC error of failed submissions including Daml interpretation errors. - rpc SubmitAndWait(SubmitAndWaitRequest) returns (SubmitAndWaitResponse); + rpc SubmitAndWait(SubmitAndWaitRequest) returns (SubmitAndWaitResponse) { + option (google.api.http) = { + post: "/v2/commands/submit-and-wait" + body: "commands" + }; + } // Submits a single composite command, waits for its result, and returns the transaction. // Propagates the gRPC error of failed submissions including Daml interpretation errors. - rpc SubmitAndWaitForTransaction(SubmitAndWaitForTransactionRequest) returns (SubmitAndWaitForTransactionResponse); + rpc SubmitAndWaitForTransaction(SubmitAndWaitForTransactionRequest) returns (SubmitAndWaitForTransactionResponse) { + option (google.api.http) = { + post: "/v2/commands/submit-and-wait-for-transaction" + body: "*" + }; + } // Submits a single composite reassignment command, waits for its result, and returns the reassignment. // Propagates the gRPC error of failed submission. - rpc SubmitAndWaitForReassignment(SubmitAndWaitForReassignmentRequest) returns (SubmitAndWaitForReassignmentResponse); + rpc SubmitAndWaitForReassignment(SubmitAndWaitForReassignmentRequest) returns (SubmitAndWaitForReassignmentResponse) { + option (google.api.http) = { + post: "/v2/commands/submit-and-wait-for-reassignment" + body: "*" + }; + } } // These commands are executed as a single atomic transaction. diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_submission_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_submission_service.proto index 16e2e335fb..53699d4f83 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_submission_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_submission_service.proto @@ -7,7 +7,9 @@ package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/commands.proto"; import "com/daml/ledger/api/v2/reassignment_commands.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "CommandSubmissionServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -28,10 +30,20 @@ option java_package = "com.daml.ledger.api.v2"; // Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions. service CommandSubmissionService { // Submit a single composite command. - rpc Submit(SubmitRequest) returns (SubmitResponse); + rpc Submit(SubmitRequest) returns (SubmitResponse) { + option (google.api.http) = { + post: "/v2/commands/async/submit" + body: "commands" + }; + } // Submit a single reassignment. - rpc SubmitReassignment(SubmitReassignmentRequest) returns (SubmitReassignmentResponse); + rpc SubmitReassignment(SubmitReassignmentRequest) returns (SubmitReassignmentResponse) { + option (google.api.http) = { + post: "/v2/commands/async/submit-reassignment" + body: "*" + }; + } } // 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. diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/commands.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/commands.proto index 8341f09ec3..767ac269f5 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/commands.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/commands.proto @@ -9,6 +9,7 @@ import "com/daml/ledger/api/v2/value.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "CommandsOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/completion.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/completion.proto index b9de1e9df3..c9be80e9ba 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/completion.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/completion.proto @@ -10,6 +10,7 @@ import "com/daml/ledger/api/v2/trace_context.proto"; import "google/protobuf/duration.proto"; import "google/rpc/status.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "CompletionOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/contract_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/contract_service.proto index 13608c625e..ca7e526192 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/contract_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/contract_service.proto @@ -6,7 +6,9 @@ syntax = "proto3"; package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/event.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "ContractServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -19,7 +21,12 @@ service ContractService { // or repair service. // If there is no contract exist with the contract ID, or there is no intersection with the querying_parties, // an CONTRACT_PAYLOAD_NOT_FOUND error will be raised. - rpc GetContract(GetContractRequest) returns (GetContractResponse); + rpc GetContract(GetContractRequest) returns (GetContractResponse) { + option (google.api.http) = { + post: "/v2/contracts/contract-by-id" + body: "*" + }; + } } message GetContractRequest { diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/crypto.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/crypto.proto index c75bfbc8b9..0ec81b7ebb 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/crypto.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/crypto.proto @@ -5,6 +5,7 @@ syntax = "proto3"; package com.daml.ledger.api.v2; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "CryptoOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event.proto index 87b7672de3..89a1ea6eec 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event.proto @@ -9,6 +9,7 @@ import "com/daml/ledger/api/v2/value.proto"; import "google/protobuf/timestamp.proto"; import "google/rpc/status.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "EventOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event_query_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event_query_service.proto index 1d45036bdc..84a6b272c8 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event_query_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/event_query_service.proto @@ -7,7 +7,9 @@ package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/event.proto"; import "com/daml/ledger/api/v2/transaction_filter.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "EventQueryServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -36,7 +38,12 @@ service EventQueryService { // No events will be returned for contracts that have been pruned because they // have already been archived before the latest pruning offset. // If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. - rpc GetEventsByContractId(GetEventsByContractIdRequest) returns (GetEventsByContractIdResponse); + rpc GetEventsByContractId(GetEventsByContractIdRequest) returns (GetEventsByContractIdResponse) { + option (google.api.http) = { + post: "/v2/events/events-by-contract-id" + body: "*" + }; + } } message GetEventsByContractIdResponse { diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/experimental_features.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/experimental_features.proto index fa9d3803d3..39d145e270 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/experimental_features.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/experimental_features.proto @@ -5,6 +5,7 @@ syntax = "proto3"; package com.daml.ledger.api.v2; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "ExperimentalFeaturesOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_common_data.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_common_data.proto index 43e0aafa51..638f48fe0d 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_common_data.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_common_data.proto @@ -7,6 +7,7 @@ package com.daml.ledger.api.v2.interactive; import "com/daml/ledger/api/v2/value.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/interactive;interactivev2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Interactive"; option java_outer_classname = "InteractiveSubmissionCommonDataOuterClass"; option java_package = "com.daml.ledger.api.v2.interactive"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_service.proto index f4134ebd7f..4c41fb8be0 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/interactive_submission_service.proto @@ -13,9 +13,11 @@ import "com/daml/ledger/api/v2/package_reference.proto"; import "com/daml/ledger/api/v2/transaction.proto"; import "com/daml/ledger/api/v2/transaction_filter.proto"; import "com/daml/ledger/api/v2/value.proto"; +import "google/api/annotations.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/interactive;interactivev2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Interactive"; option java_outer_classname = "InteractiveSubmissionServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.interactive"; @@ -30,15 +32,35 @@ option java_package = "com.daml.ledger.api.v2.interactive"; // This gives callers the ability to sign the daml transaction with their own signing keys service InteractiveSubmissionService { // Requires `readAs` scope for the submitting party when LAPI User authorization is enabled - rpc PrepareSubmission(PrepareSubmissionRequest) returns (PrepareSubmissionResponse); + rpc PrepareSubmission(PrepareSubmissionRequest) returns (PrepareSubmissionResponse) { + option (google.api.http) = { + post: "/v2/interactive-submission/prepare" + body: "*" + }; + } // Execute a prepared submission _asynchronously_ on the ledger. // Requires `actAs` or `executeAs` scope for the submitting party when LAPI User authorization is enabled // Requires a signature of the transaction from the submitting external party. - rpc ExecuteSubmission(ExecuteSubmissionRequest) returns (ExecuteSubmissionResponse); + rpc ExecuteSubmission(ExecuteSubmissionRequest) returns (ExecuteSubmissionResponse) { + option (google.api.http) = { + post: "/v2/interactive-submission/execute" + body: "*" + }; + } // Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction - rpc ExecuteSubmissionAndWait(ExecuteSubmissionAndWaitRequest) returns (ExecuteSubmissionAndWaitResponse); + rpc ExecuteSubmissionAndWait(ExecuteSubmissionAndWaitRequest) returns (ExecuteSubmissionAndWaitResponse) { + option (google.api.http) = { + post: "/v2/interactive-submission/executeAndWait" + body: "*" + }; + } // Similar to ExecuteSubmissionAndWait but additionally returns the transaction - rpc ExecuteSubmissionAndWaitForTransaction(ExecuteSubmissionAndWaitForTransactionRequest) returns (ExecuteSubmissionAndWaitForTransactionResponse); + rpc ExecuteSubmissionAndWaitForTransaction(ExecuteSubmissionAndWaitForTransactionRequest) returns (ExecuteSubmissionAndWaitForTransactionResponse) { + option (google.api.http) = { + post: "/v2/interactive-submission/executeAndWaitForTransaction" + body: "*" + }; + } // A preferred package is the highest-versioned package for a provided package-name // that is vetted by all the participants hosting the provided parties. @@ -52,7 +74,11 @@ service InteractiveSubmissionService { // Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. // // Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 - rpc GetPreferredPackageVersion(GetPreferredPackageVersionRequest) returns (GetPreferredPackageVersionResponse); + rpc GetPreferredPackageVersion(GetPreferredPackageVersionRequest) returns (GetPreferredPackageVersionResponse) { + option (google.api.http) = { + get: "/v2/interactive-submission/preferred-package-version" + }; + } // Compute the preferred packages for the vetting requirements in the request. // A preferred package is the highest-versioned package for a provided package-name @@ -70,7 +96,12 @@ service InteractiveSubmissionService { // Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. // // Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases - rpc GetPreferredPackages(GetPreferredPackagesRequest) returns (GetPreferredPackagesResponse); + rpc GetPreferredPackages(GetPreferredPackagesRequest) returns (GetPreferredPackagesResponse) { + option (google.api.http) = { + post: "/v2/interactive-submission/preferred-packages" + body: "*" + }; + } } // Hints to improve cost estimation precision of a prepared transaction diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/transaction/v1/interactive_submission_data.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/transaction/v1/interactive_submission_data.proto index 81e0ef887c..ac8ce9cb8f 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/transaction/v1/interactive_submission_data.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/interactive/transaction/v1/interactive_submission_data.proto @@ -8,6 +8,7 @@ package com.daml.ledger.api.v2.interactive.transaction.v1; import "com/daml/ledger/api/v2/interactive/interactive_submission_common_data.proto"; import "com/daml/ledger/api/v2/value.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/interactive/transaction/v1;transactionv1"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Interactive.Transaction.V1"; option java_outer_classname = "InteractiveSubmissionDataOuterClass"; option java_package = "com.daml.ledger.api.v2.interactive.transaction.v1"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/offset_checkpoint.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/offset_checkpoint.proto index 6bf4a76036..4b5d1cf469 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/offset_checkpoint.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/offset_checkpoint.proto @@ -7,6 +7,7 @@ package com.daml.ledger.api.v2; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "OffsetCheckpointOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_reference.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_reference.proto index 8576c820f0..0ab516e85b 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_reference.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_reference.proto @@ -8,6 +8,7 @@ package com.daml.ledger.api.v2; import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "PackageReferenceOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_service.proto index f015a8a90d..21d79b147f 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/package_service.proto @@ -6,7 +6,9 @@ syntax = "proto3"; package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/package_reference.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "PackageServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -59,17 +61,34 @@ enum HashFunction { // Allows clients to query the Daml-LF packages that are supported by the server. service PackageService { // Returns the identifiers of all supported packages. - rpc ListPackages(ListPackagesRequest) returns (ListPackagesResponse); + rpc ListPackages(ListPackagesRequest) returns (ListPackagesResponse) { + option (google.api.http) = { + get: "/v2/packages" + }; + } // Returns the contents of a single package. - rpc GetPackage(GetPackageRequest) returns (GetPackageResponse); + rpc GetPackage(GetPackageRequest) returns (GetPackageResponse) { + option (google.api.http) = { + get: "/v2/packages/{package_id}" + }; + } // Returns the status of a single package. - rpc GetPackageStatus(GetPackageStatusRequest) returns (GetPackageStatusResponse); + rpc GetPackageStatus(GetPackageStatusRequest) returns (GetPackageStatusResponse) { + option (google.api.http) = { + get: "/v2/packages/{package_id}/status" + }; + } // Lists which participant node vetted what packages on which synchronizer. // Can be called by any authenticated user. - rpc ListVettedPackages(ListVettedPackagesRequest) returns (ListVettedPackagesResponse); + rpc ListVettedPackages(ListVettedPackagesRequest) returns (ListVettedPackagesResponse) { + option (google.api.http) = { + post: "/v2/package-vetting/list" + body: "*" + }; + } } message ListPackagesRequest {} diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment.proto index 6ab821809e..38c0eb7587 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment.proto @@ -10,6 +10,7 @@ import "com/daml/ledger/api/v2/trace_context.proto"; import "com/daml/ledger/api/v2/value.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "ReassignmentOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment_commands.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment_commands.proto index eb01f7ae7a..a8fb7e1642 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment_commands.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/reassignment_commands.proto @@ -5,6 +5,7 @@ syntax = "proto3"; package com.daml.ledger.api.v2; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "ReassignmentCommandOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/state_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/state_service.proto index 842e1cedd7..2c8c74902c 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/state_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/state_service.proto @@ -8,7 +8,9 @@ package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/event.proto"; import "com/daml/ledger/api/v2/reassignment.proto"; import "com/daml/ledger/api/v2/transaction_filter.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "StateServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -20,24 +22,46 @@ service StateService { // the client SHOULD begin streaming updates from the update service, // starting at the GetActiveContractsRequest.active_at_offset specified in this request. // Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. - rpc GetActiveContracts(GetActiveContractsRequest) returns (stream GetActiveContractsResponse); + rpc GetActiveContracts(GetActiveContractsRequest) returns (stream GetActiveContractsResponse) { + option (google.api.http) = { + post: "/v2/state/active-contracts" + body: "*" + }; + } // Returns a page of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. // Once all pages are fetched by repeated calls to ``GetActiveContractsPage``, // the client SHOULD begin retrieving updates from the update service, // starting at the ``GetActiveContractsPageResponse``.``active_at_offset`` specified in this request. // Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. - rpc GetActiveContractsPage(GetActiveContractsPageRequest) returns (GetActiveContractsPageResponse); + rpc GetActiveContractsPage(GetActiveContractsPageRequest) returns (GetActiveContractsPageResponse) { + option (google.api.http) = { + post: "/v2/state/active-contracts-page" + body: "*" + }; + } // Get the list of connected synchronizers at the time of the query. - rpc GetConnectedSynchronizers(GetConnectedSynchronizersRequest) returns (GetConnectedSynchronizersResponse); + rpc GetConnectedSynchronizers(GetConnectedSynchronizersRequest) returns (GetConnectedSynchronizersResponse) { + option (google.api.http) = { + get: "/v2/state/connected-synchronizers" + }; + } // Get the current ledger end. // Subscriptions started with the returned offset will serve events after this RPC was called. - rpc GetLedgerEnd(GetLedgerEndRequest) returns (GetLedgerEndResponse); + rpc GetLedgerEnd(GetLedgerEndRequest) returns (GetLedgerEndResponse) { + option (google.api.http) = { + get: "/v2/state/ledger-end" + }; + } // Get the latest successfully pruned ledger offsets - rpc GetLatestPrunedOffsets(GetLatestPrunedOffsetsRequest) returns (GetLatestPrunedOffsetsResponse); + rpc GetLatestPrunedOffsets(GetLatestPrunedOffsetsRequest) returns (GetLatestPrunedOffsetsResponse) { + option (google.api.http) = { + get: "/v2/state/latest-pruned-offsets" + }; + } } // If the given offset is different than the ledger end, and there are (un)assignments in-flight at the given offset, diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/testing/time_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/testing/time_service.proto index dea131cb33..cc8317ee88 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/testing/time_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/testing/time_service.proto @@ -9,6 +9,7 @@ import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/testing;testingv2"; option java_outer_classname = "TimeServiceOuterClass"; option java_package = "com.daml.ledger.api.v2.testing"; option csharp_namespace = "Com.Daml.Ledger.Api.V2.Testing"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/topology_transaction.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/topology_transaction.proto index 71bb3b873b..9049e08854 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/topology_transaction.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/topology_transaction.proto @@ -9,6 +9,7 @@ import "com/daml/ledger/api/v2/state_service.proto"; import "com/daml/ledger/api/v2/trace_context.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "TopologyTransactionOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/trace_context.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/trace_context.proto index a1b6a8466a..c1b03d1e47 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/trace_context.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/trace_context.proto @@ -5,6 +5,7 @@ syntax = "proto3"; package com.daml.ledger.api.v2; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "TraceContextOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction.proto index 9b3c62de8f..68b0183a01 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction.proto @@ -9,6 +9,7 @@ import "com/daml/ledger/api/v2/event.proto"; import "com/daml/ledger/api/v2/trace_context.proto"; import "google/protobuf/timestamp.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "TransactionOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction_filter.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction_filter.proto index cb794a826b..db0e8752d0 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction_filter.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/transaction_filter.proto @@ -7,6 +7,7 @@ package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/value.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "TransactionFilterOuterClass"; option java_package = "com.daml.ledger.api.v2"; diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/update_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/update_service.proto index 734f8b7552..069439e170 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/update_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/update_service.proto @@ -10,7 +10,9 @@ import "com/daml/ledger/api/v2/reassignment.proto"; import "com/daml/ledger/api/v2/topology_transaction.proto"; import "com/daml/ledger/api/v2/transaction.proto"; import "com/daml/ledger/api/v2/transaction_filter.proto"; +import "google/api/annotations.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "UpdateServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -34,15 +36,30 @@ service UpdateService { // // - ACS delta: a requesting party must be a stakeholder of an event for it to be included. // - ledger effects: a requesting party must be a witness of an event for it to be included. - rpc GetUpdates(GetUpdatesRequest) returns (stream GetUpdatesResponse); + rpc GetUpdates(GetUpdatesRequest) returns (stream GetUpdatesResponse) { + option (google.api.http) = { + post: "/v2/updates" + body: "*" + }; + } // Lookup an update by its offset. // If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. - rpc GetUpdateByOffset(GetUpdateByOffsetRequest) returns (GetUpdateResponse); + rpc GetUpdateByOffset(GetUpdateByOffsetRequest) returns (GetUpdateResponse) { + option (google.api.http) = { + post: "/v2/updates/update-by-offset" + body: "*" + }; + } // Lookup an update by its ID. // If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. - rpc GetUpdateById(GetUpdateByIdRequest) returns (GetUpdateResponse); + rpc GetUpdateById(GetUpdateByIdRequest) returns (GetUpdateResponse) { + option (google.api.http) = { + post: "/v2/updates/update-by-id" + body: "*" + }; + } // Read a page of ledger's filtered updates. It returns the event types in accordance with // the specified contents and filters. @@ -50,7 +67,12 @@ service UpdateService { // // - ACS delta: an event is included only if the requesting party is a stakeholder. // - ledger effects: an event is included if the requesting party is a witness. - rpc GetUpdatesPage(GetUpdatesPageRequest) returns (GetUpdatesPageResponse); + rpc GetUpdatesPage(GetUpdatesPageRequest) returns (GetUpdatesPageResponse) { + option (google.api.http) = { + post: "/v2/updates/get-updates-page" + body: "*" + }; + } } message GetUpdatesRequest { diff --git a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/version_service.proto b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/version_service.proto index 3d73627206..d35329e8fe 100644 --- a/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/version_service.proto +++ b/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/version_service.proto @@ -6,8 +6,10 @@ syntax = "proto3"; package com.daml.ledger.api.v2; import "com/daml/ledger/api/v2/experimental_features.proto"; +import "google/api/annotations.proto"; import "google/protobuf/duration.proto"; +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; option csharp_namespace = "Com.Daml.Ledger.Api.V2"; option java_outer_classname = "VersionServiceOuterClass"; option java_package = "com.daml.ledger.api.v2"; @@ -15,7 +17,11 @@ option java_package = "com.daml.ledger.api.v2"; // Allows clients to retrieve information about the ledger API version service VersionService { // Read the Ledger API version - rpc GetLedgerApiVersion(GetLedgerApiVersionRequest) returns (GetLedgerApiVersionResponse); + rpc GetLedgerApiVersion(GetLedgerApiVersionRequest) returns (GetLedgerApiVersionResponse) { + option (google.api.http) = { + get: "/v2/version" + }; + } } message GetLedgerApiVersionRequest {} diff --git a/experiment-evidence/README.md b/experiment-evidence/README.md new file mode 100644 index 0000000000..e4d6189090 --- /dev/null +++ b/experiment-evidence/README.md @@ -0,0 +1,16 @@ +# Experiment evidence + +Burden-of-evidence artefacts for the PR `experiment: google.api.http annotations on CommandService`. + +**This directory is internal to the Peaceful Studio fork.** Delete it before submitting any upstream PR to `digital-asset/canton` — these files are review aids, not part of the contribution. + +## Contents + +| Subdirectory | Purpose | +|---|---| +| [`go-package-harmlessness/`](go-package-harmlessness/) | Empirical proof that adding `option go_package = "..."` to the v2 protos does not affect any existing C# / Java / Scala codegen consumer. | +| [`openapi-generation/`](openapi-generation/) | The actual OpenAPI document generated from the annotated `command_service.proto`, plus the `buf.gen.yaml` used to produce it. The 1,372-line JSON is the "after" side of the SwaggerHub comparison linked from the PR description. | + +## How to verify everything from scratch + +The PR description (top of #1) has the full reproducible flow: install buf, drop the three google.api / google.rpc protos into `community/lib/google-common-protos-scala/target/protobuf_external/`, run `buf build` and `buf generate`. Every artefact in this directory is regeneratable from that flow. diff --git a/experiment-evidence/go-package-harmlessness/README.md b/experiment-evidence/go-package-harmlessness/README.md new file mode 100644 index 0000000000..d23c0926de --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/README.md @@ -0,0 +1,89 @@ +# Proof that `option go_package` is harmless for existing Canton consumers + +## Why we needed `go_package` in the first place + +Every off-the-shelf OpenAPI generator in the protobuf ecosystem is written in Go: `protoc-gen-openapiv2` (grpc-ecosystem/grpc-gateway), `protoc-gen-openapi` (google/gnostic), the buf-published variants of both. They walk the `FileDescriptorSet` for the target service and, for every `.proto` in the transitive closure, look up its declared Go import path so the generator can emit per-file artefacts. + +When the option is missing the plugin fails fast: + +``` +unable to determine Go import path for "com/daml/ledger/api/v2/value.proto" + +Please specify either: + • a "go_package" option in the .proto source file, or + • a "M" argument on the command line. +``` + +This is enforced even when no Go code is being emitted — it is a hard precondition for *running* the plugin. Canton's protos currently declare `csharp_namespace`, `java_package`, `java_outer_classname` but not `go_package`, because Canton has no Go target. So every Go-based OpenAPI tool refuses to run against the proto set until that gap is filled. + +The fix is a one-line `option go_package = "..."` per proto file, sitting alongside the existing language-target options. Three things to prove: + +1. The added option is the **only** semantic change to the compiled `FileDescriptorSet`. +2. Canton's actual codegen pipeline **never reads** `go_package`, so the option cannot affect generated Scala / Java / C# output. +3. The option is **inert by design** in protobuf — each language has its own `FileOptions` field; consumers read only their own. + +The artefacts below establish each claim with byte-level evidence. + +## Artefacts + +| File | What it proves | +|---|---| +| `version_service.proto.before` | Verbatim copy of the proto **as it exists upstream** in `digital-asset/canton@v3.5.1-rc3`. | +| `version_service.proto.after` | Verbatim copy of the proto **after our change**. | +| `version_service.proto.diff` | Unified diff of the two source files. One added line: `+option go_package = "...";`. | +| `version_service.before.descriptor.txt` | Full textproto-decoded `FileDescriptorProto` produced by `buf build` on the upstream proto. | +| `version_service.after.descriptor.txt` | Same, on the patched proto. | +| `version_service.before.descriptor.nosourceinfo.txt` | Same as above with `source_code_info` stripped. `source_code_info` only carries source-line spans for IDE tooling; it inevitably shifts when any line is added or removed and is not semantically meaningful. | +| `version_service.after.descriptor.nosourceinfo.txt` | Same. | +| `version_service.descriptor.semantic.diff` | Unified diff of the two `.nosourceinfo` descriptors. **One added line: `+ go_package: "..."` inside the `options { }` block, alongside `java_package`, `java_outer_classname`, `csharp_namespace`. Nothing else changes — no message field, no service method, no enum, no import.** | +| `canton-build-targets.txt` | `grep` of `project/BuildCommon.scala` for every `PB.targets` declaration. Every entry routes to `scalapb.gen` or `PB.gens.java`. No `gen_go`, no `protoc-gen-go`, no Go plugin anywhere. Canton's build pipeline literally cannot read the `go_package` option, because no Go plugin is invoked. | + +## Why this is sound — the protobuf-language guarantee + +`google/protobuf/descriptor.proto` defines `FileOptions` as a flat message with one field per language target: + +```proto +message FileOptions { + optional string java_package = 1; + optional string java_outer_classname = 8; + ... + optional string go_package = 11; + ... + optional string csharp_namespace = 37; + optional string swift_prefix = 39; + optional string php_class_prefix = 40; + ... +} +``` + +Each consuming plugin reads only the field assigned to its language. `protoc-gen-java` reads `java_package` and ignores the rest. `protoc-gen-go` reads `go_package` and ignores the rest. ScalaPB reads its own dedicated `scalapb.options` extension and ignores all of the language-target fields. Adding a sibling field to `options {}` has no effect on a plugin that does not read that field — this is the whole point of how proto FileOptions are structured. + +The semantic diff above demonstrates this empirically: the **only** change to the compiled descriptor is one new sibling field inside `options {}`. Every other byte of the descriptor — message definitions, service methods, RPC signatures, imports, dependencies — is identical. + +## Reproduce + +```bash +# from canton repo root, on this branch: +git checkout HEAD~1 -- community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/version_service.proto +( cd community/ledger-api-proto/src/main/protobuf && \ + buf build --path com/daml/ledger/api/v2/version_service.proto -o /tmp/version_service.before.binpb ) +git checkout HEAD -- community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/version_service.proto +( cd community/ledger-api-proto/src/main/protobuf && \ + buf build --path com/daml/ledger/api/v2/version_service.proto -o /tmp/version_service.after.binpb ) + +python3 - <<'EOF' +from google.protobuf import descriptor_pb2 +for state in ('before', 'after'): + fds = descriptor_pb2.FileDescriptorSet() + with open(f'/tmp/version_service.{state}.binpb', 'rb') as f: + fds.ParseFromString(f.read()) + for fproto in fds.file: + if fproto.name.endswith('version_service.proto'): + fproto.ClearField('source_code_info') + open(f'/tmp/version_service.{state}.txt', 'w').write(str(fproto)) +EOF + +diff -u /tmp/version_service.before.txt /tmp/version_service.after.txt +``` + +The diff is the same one-line addition shown in `version_service.descriptor.semantic.diff`. diff --git a/experiment-evidence/go-package-harmlessness/canton-build-targets.txt b/experiment-evidence/go-package-harmlessness/canton-build-targets.txt new file mode 100644 index 0000000000..92adc9cfe5 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/canton-build-targets.txt @@ -0,0 +1,25 @@ +922: Test / PB.targets := Seq( +923: scalapb.gen() -> (Test / sourceManaged).value / "protobuf" +1005: Compile / PB.targets := Seq( +1006: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +1119: Compile / PB.targets := Seq( +1120: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +1122: Test / PB.targets := Seq( +1123: scalapb.gen(flatPackage = true) -> (Test / sourceManaged).value / "protobuf" +1160: Compile / PB.targets := Seq( +1161: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +1205: Compile / PB.targets := Seq( +1206: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +1262: Compile / PB.targets := Seq( +1263: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +1589: Compile / PB.targets := Seq( +1590: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +2002: Compile / PB.targets := Seq( +2003: scalapb.gen(flatPackage = false) -> (Compile / sourceManaged).value / "protobuf" +2042: Test / PB.targets := Seq( +2044: PB.gens.java -> (Test / sourceManaged).value / "protobuf", +2046: scalapb.gen( +2916: Compile / PB.targets := Seq( +2917: scalapb.gen(flatPackage = true) -> (Compile / sourceManaged).value / "protobuf" +3141: Compile / PB.targets := Seq( +3143: scalapb.gen( diff --git a/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.nosourceinfo.txt b/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.nosourceinfo.txt new file mode 100644 index 0000000000..a5acf178b0 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.nosourceinfo.txt @@ -0,0 +1,138 @@ +name: "com/daml/ledger/api/v2/version_service.proto" +package: "com.daml.ledger.api.v2" +dependency: "com/daml/ledger/api/v2/experimental_features.proto" +dependency: "google/protobuf/duration.proto" +message_type { + name: "GetLedgerApiVersionRequest" +} +message_type { + name: "GetLedgerApiVersionResponse" + field { + name: "version" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_STRING + json_name: "version" + } + field { + name: "features" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.FeaturesDescriptor" + json_name: "features" + } +} +message_type { + name: "FeaturesDescriptor" + field { + name: "experimental" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.ExperimentalFeatures" + json_name: "experimental" + } + field { + name: "user_management" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.UserManagementFeature" + json_name: "userManagement" + } + field { + name: "party_management" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PartyManagementFeature" + json_name: "partyManagement" + } + field { + name: "offset_checkpoint" + number: 4 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.OffsetCheckpointFeature" + json_name: "offsetCheckpoint" + } + field { + name: "package_feature" + number: 5 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PackageFeature" + json_name: "packageFeature" + } +} +message_type { + name: "UserManagementFeature" + field { + name: "supported" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_BOOL + json_name: "supported" + } + field { + name: "max_rights_per_user" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxRightsPerUser" + } + field { + name: "max_users_page_size" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxUsersPageSize" + } +} +message_type { + name: "PartyManagementFeature" + field { + name: "max_parties_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxPartiesPageSize" + } +} +message_type { + name: "PackageFeature" + field { + name: "max_vetted_packages_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxVettedPackagesPageSize" + } +} +message_type { + name: "OffsetCheckpointFeature" + field { + name: "max_offset_checkpoint_emission_delay" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".google.protobuf.Duration" + json_name: "maxOffsetCheckpointEmissionDelay" + } +} +service { + name: "VersionService" + method { + name: "GetLedgerApiVersion" + input_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionRequest" + output_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionResponse" + } +} +options { + java_package: "com.daml.ledger.api.v2" + java_outer_classname: "VersionServiceOuterClass" + go_package: "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2" + csharp_namespace: "Com.Daml.Ledger.Api.V2" +} +syntax: "proto3" diff --git a/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.txt b/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.txt new file mode 100644 index 0000000000..7c493474e4 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.txt @@ -0,0 +1,913 @@ +name: "com/daml/ledger/api/v2/version_service.proto" +package: "com.daml.ledger.api.v2" +dependency: "com/daml/ledger/api/v2/experimental_features.proto" +dependency: "google/protobuf/duration.proto" +message_type { + name: "GetLedgerApiVersionRequest" +} +message_type { + name: "GetLedgerApiVersionResponse" + field { + name: "version" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_STRING + json_name: "version" + } + field { + name: "features" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.FeaturesDescriptor" + json_name: "features" + } +} +message_type { + name: "FeaturesDescriptor" + field { + name: "experimental" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.ExperimentalFeatures" + json_name: "experimental" + } + field { + name: "user_management" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.UserManagementFeature" + json_name: "userManagement" + } + field { + name: "party_management" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PartyManagementFeature" + json_name: "partyManagement" + } + field { + name: "offset_checkpoint" + number: 4 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.OffsetCheckpointFeature" + json_name: "offsetCheckpoint" + } + field { + name: "package_feature" + number: 5 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PackageFeature" + json_name: "packageFeature" + } +} +message_type { + name: "UserManagementFeature" + field { + name: "supported" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_BOOL + json_name: "supported" + } + field { + name: "max_rights_per_user" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxRightsPerUser" + } + field { + name: "max_users_page_size" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxUsersPageSize" + } +} +message_type { + name: "PartyManagementFeature" + field { + name: "max_parties_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxPartiesPageSize" + } +} +message_type { + name: "PackageFeature" + field { + name: "max_vetted_packages_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxVettedPackagesPageSize" + } +} +message_type { + name: "OffsetCheckpointFeature" + field { + name: "max_offset_checkpoint_emission_delay" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".google.protobuf.Duration" + json_name: "maxOffsetCheckpointEmissionDelay" + } +} +service { + name: "VersionService" + method { + name: "GetLedgerApiVersion" + input_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionRequest" + output_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionResponse" + } +} +options { + java_package: "com.daml.ledger.api.v2" + java_outer_classname: "VersionServiceOuterClass" + go_package: "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2" + csharp_namespace: "Com.Daml.Ledger.Api.V2" +} +source_code_info { + location { + span: 3 + span: 0 + span: 120 + span: 1 + } + location { + path: 12 + span: 3 + span: 0 + span: 18 + leading_detached_comments: " Copyright (c) 2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.\n SPDX-License-Identifier: Apache-2.0\n" + } + location { + path: 2 + span: 5 + span: 0 + span: 31 + } + location { + path: 3 + path: 0 + span: 7 + span: 0 + span: 60 + } + location { + path: 3 + path: 1 + span: 8 + span: 0 + span: 40 + } + location { + path: 8 + span: 10 + span: 0 + span: 83 + } + location { + path: 8 + path: 11 + span: 10 + span: 0 + span: 83 + } + location { + path: 8 + span: 11 + span: 0 + span: 51 + } + location { + path: 8 + path: 37 + span: 11 + span: 0 + span: 51 + } + location { + path: 8 + span: 12 + span: 0 + span: 57 + } + location { + path: 8 + path: 8 + span: 12 + span: 0 + span: 57 + } + location { + path: 8 + span: 13 + span: 0 + span: 47 + } + location { + path: 8 + path: 1 + span: 13 + span: 0 + span: 47 + } + location { + path: 6 + path: 0 + span: 16 + span: 0 + span: 19 + span: 1 + leading_comments: " Allows clients to retrieve information about the ledger API version\n" + } + location { + path: 6 + path: 0 + path: 1 + span: 16 + span: 8 + span: 22 + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + span: 18 + span: 2 + span: 92 + leading_comments: " Read the Ledger API version\n" + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + path: 1 + span: 18 + span: 6 + span: 25 + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + path: 2 + span: 18 + span: 26 + span: 52 + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + path: 3 + span: 18 + span: 63 + span: 90 + } + location { + path: 4 + path: 0 + span: 21 + span: 0 + span: 37 + } + location { + path: 4 + path: 0 + path: 1 + span: 21 + span: 8 + span: 34 + } + location { + path: 4 + path: 1 + span: 23 + span: 0 + span: 41 + span: 1 + } + location { + path: 4 + path: 1 + path: 1 + span: 23 + span: 8 + span: 35 + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + path: 5 + span: 27 + span: 2 + span: 8 + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + span: 27 + span: 2 + span: 21 + leading_comments: " The version of the ledger API.\n\n Required\n" + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + path: 1 + span: 27 + span: 9 + span: 16 + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + path: 3 + span: 27 + span: 19 + span: 20 + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + path: 6 + span: 40 + span: 2 + span: 20 + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + span: 40 + span: 2 + span: 34 + leading_comments: " The features supported by this Ledger API endpoint.\n\n Daml applications CAN use the feature descriptor on top of\n version constraints on the Ledger API version to determine\n whether a given Ledger API endpoint supports the features\n required to run the application.\n\n See the feature descriptions themselves for the relation between\n Ledger API versions and feature presence.\n\n Required\n" + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + path: 1 + span: 40 + span: 21 + span: 29 + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + path: 3 + span: 40 + span: 32 + span: 33 + } + location { + path: 4 + path: 2 + span: 43 + span: 0 + span: 77 + span: 1 + } + location { + path: 4 + path: 2 + path: 1 + span: 43 + span: 8 + span: 26 + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + path: 6 + span: 50 + span: 2 + span: 22 + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + span: 50 + span: 2 + span: 40 + leading_comments: " Features under development or features that are used\n for ledger implementation testing purposes only.\n\n Daml applications SHOULD not depend on these in production.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + path: 1 + span: 50 + span: 23 + span: 35 + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + path: 3 + span: 50 + span: 38 + span: 39 + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + path: 6 + span: 57 + span: 2 + span: 23 + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + span: 57 + span: 2 + span: 44 + leading_comments: " If set, then the Ledger API server supports user management.\n It is recommended that clients query this field to gracefully adjust their behavior for\n ledgers that do not support user management.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + path: 1 + span: 57 + span: 24 + span: 39 + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + path: 3 + span: 57 + span: 42 + span: 43 + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + path: 6 + span: 64 + span: 2 + span: 24 + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + span: 64 + span: 2 + span: 46 + leading_comments: " If set, then the Ledger API server supports party management configurability.\n It is recommended that clients query this field to gracefully adjust their behavior to\n maximum party page size.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + path: 1 + span: 64 + span: 25 + span: 41 + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + path: 3 + span: 64 + span: 44 + span: 45 + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + path: 6 + span: 69 + span: 2 + span: 25 + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + span: 69 + span: 2 + span: 48 + leading_comments: " It contains the timeouts related to the periodic offset checkpoint emission\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + path: 1 + span: 69 + span: 26 + span: 43 + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + path: 3 + span: 69 + span: 46 + span: 47 + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + path: 6 + span: 76 + span: 2 + span: 16 + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + span: 76 + span: 2 + span: 37 + leading_comments: " If set, then the Ledger API server supports package listing\n configurability. It is recommended that clients query this field to\n gracefully adjust their behavior to maximum package listing page size.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + path: 1 + span: 76 + span: 17 + span: 32 + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + path: 3 + span: 76 + span: 35 + span: 36 + } + location { + path: 4 + path: 3 + span: 79 + span: 0 + span: 98 + span: 1 + } + location { + path: 4 + path: 3 + path: 1 + span: 79 + span: 8 + span: 29 + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + path: 5 + span: 83 + span: 2 + span: 6 + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + span: 83 + span: 2 + span: 21 + leading_comments: " Whether the Ledger API server provides the user management service.\n\n Required\n" + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + path: 1 + span: 83 + span: 7 + span: 16 + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + path: 3 + span: 83 + span: 19 + span: 20 + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + path: 5 + span: 90 + span: 2 + span: 7 + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + span: 90 + span: 2 + span: 32 + leading_comments: " The maximum number of rights that can be assigned to a single user.\n Servers MUST support at least 100 rights per user.\n A value of 0 means that the server enforces no rights per user limit.\n\n Required\n" + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + path: 1 + span: 90 + span: 8 + span: 27 + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + path: 3 + span: 90 + span: 30 + span: 31 + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + path: 5 + span: 97 + span: 2 + span: 7 + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + span: 97 + span: 2 + span: 32 + leading_comments: " The maximum number of users the server can return in a single response (page).\n Servers MUST support at least a 100 users per page.\n A value of 0 means that the server enforces no page size limit.\n\n Required\n" + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + path: 1 + span: 97 + span: 8 + span: 27 + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + path: 3 + span: 97 + span: 30 + span: 31 + } + location { + path: 4 + path: 4 + span: 100 + span: 0 + span: 105 + span: 1 + } + location { + path: 4 + path: 4 + path: 1 + span: 100 + span: 8 + span: 30 + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + path: 5 + span: 104 + span: 2 + span: 7 + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + span: 104 + span: 2 + span: 34 + leading_comments: " The maximum number of parties the server can return in a single response (page).\n\n Required\n" + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + path: 1 + span: 104 + span: 8 + span: 29 + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + path: 3 + span: 104 + span: 32 + span: 33 + } + location { + path: 4 + path: 5 + span: 107 + span: 0 + span: 113 + span: 1 + } + location { + path: 4 + path: 5 + path: 1 + span: 107 + span: 8 + span: 22 + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + path: 5 + span: 112 + span: 2 + span: 7 + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + span: 112 + span: 2 + span: 42 + leading_comments: " The maximum number of vetted packages the server can return in a single\n response (page) when listing them.\n\n Required\n" + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + path: 1 + span: 112 + span: 8 + span: 37 + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + path: 3 + span: 112 + span: 40 + span: 41 + } + location { + path: 4 + path: 6 + span: 115 + span: 0 + span: 120 + span: 1 + } + location { + path: 4 + path: 6 + path: 1 + span: 115 + span: 8 + span: 31 + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + path: 6 + span: 119 + span: 2 + span: 26 + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + span: 119 + span: 2 + span: 68 + leading_comments: " The maximum delay to emmit a new OffsetCheckpoint if it exists\n\n Required\n" + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + path: 1 + span: 119 + span: 27 + span: 63 + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + path: 3 + span: 119 + span: 66 + span: 67 + } +} +syntax: "proto3" diff --git a/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.nosourceinfo.txt b/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.nosourceinfo.txt new file mode 100644 index 0000000000..43f05971d0 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.nosourceinfo.txt @@ -0,0 +1,137 @@ +name: "com/daml/ledger/api/v2/version_service.proto" +package: "com.daml.ledger.api.v2" +dependency: "com/daml/ledger/api/v2/experimental_features.proto" +dependency: "google/protobuf/duration.proto" +message_type { + name: "GetLedgerApiVersionRequest" +} +message_type { + name: "GetLedgerApiVersionResponse" + field { + name: "version" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_STRING + json_name: "version" + } + field { + name: "features" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.FeaturesDescriptor" + json_name: "features" + } +} +message_type { + name: "FeaturesDescriptor" + field { + name: "experimental" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.ExperimentalFeatures" + json_name: "experimental" + } + field { + name: "user_management" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.UserManagementFeature" + json_name: "userManagement" + } + field { + name: "party_management" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PartyManagementFeature" + json_name: "partyManagement" + } + field { + name: "offset_checkpoint" + number: 4 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.OffsetCheckpointFeature" + json_name: "offsetCheckpoint" + } + field { + name: "package_feature" + number: 5 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PackageFeature" + json_name: "packageFeature" + } +} +message_type { + name: "UserManagementFeature" + field { + name: "supported" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_BOOL + json_name: "supported" + } + field { + name: "max_rights_per_user" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxRightsPerUser" + } + field { + name: "max_users_page_size" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxUsersPageSize" + } +} +message_type { + name: "PartyManagementFeature" + field { + name: "max_parties_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxPartiesPageSize" + } +} +message_type { + name: "PackageFeature" + field { + name: "max_vetted_packages_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxVettedPackagesPageSize" + } +} +message_type { + name: "OffsetCheckpointFeature" + field { + name: "max_offset_checkpoint_emission_delay" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".google.protobuf.Duration" + json_name: "maxOffsetCheckpointEmissionDelay" + } +} +service { + name: "VersionService" + method { + name: "GetLedgerApiVersion" + input_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionRequest" + output_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionResponse" + } +} +options { + java_package: "com.daml.ledger.api.v2" + java_outer_classname: "VersionServiceOuterClass" + csharp_namespace: "Com.Daml.Ledger.Api.V2" +} +syntax: "proto3" diff --git a/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.txt b/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.txt new file mode 100644 index 0000000000..5962f85f3e --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.txt @@ -0,0 +1,899 @@ +name: "com/daml/ledger/api/v2/version_service.proto" +package: "com.daml.ledger.api.v2" +dependency: "com/daml/ledger/api/v2/experimental_features.proto" +dependency: "google/protobuf/duration.proto" +message_type { + name: "GetLedgerApiVersionRequest" +} +message_type { + name: "GetLedgerApiVersionResponse" + field { + name: "version" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_STRING + json_name: "version" + } + field { + name: "features" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.FeaturesDescriptor" + json_name: "features" + } +} +message_type { + name: "FeaturesDescriptor" + field { + name: "experimental" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.ExperimentalFeatures" + json_name: "experimental" + } + field { + name: "user_management" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.UserManagementFeature" + json_name: "userManagement" + } + field { + name: "party_management" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PartyManagementFeature" + json_name: "partyManagement" + } + field { + name: "offset_checkpoint" + number: 4 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.OffsetCheckpointFeature" + json_name: "offsetCheckpoint" + } + field { + name: "package_feature" + number: 5 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".com.daml.ledger.api.v2.PackageFeature" + json_name: "packageFeature" + } +} +message_type { + name: "UserManagementFeature" + field { + name: "supported" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_BOOL + json_name: "supported" + } + field { + name: "max_rights_per_user" + number: 2 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxRightsPerUser" + } + field { + name: "max_users_page_size" + number: 3 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxUsersPageSize" + } +} +message_type { + name: "PartyManagementFeature" + field { + name: "max_parties_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxPartiesPageSize" + } +} +message_type { + name: "PackageFeature" + field { + name: "max_vetted_packages_page_size" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_INT32 + json_name: "maxVettedPackagesPageSize" + } +} +message_type { + name: "OffsetCheckpointFeature" + field { + name: "max_offset_checkpoint_emission_delay" + number: 1 + label: LABEL_OPTIONAL + type: TYPE_MESSAGE + type_name: ".google.protobuf.Duration" + json_name: "maxOffsetCheckpointEmissionDelay" + } +} +service { + name: "VersionService" + method { + name: "GetLedgerApiVersion" + input_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionRequest" + output_type: ".com.daml.ledger.api.v2.GetLedgerApiVersionResponse" + } +} +options { + java_package: "com.daml.ledger.api.v2" + java_outer_classname: "VersionServiceOuterClass" + csharp_namespace: "Com.Daml.Ledger.Api.V2" +} +source_code_info { + location { + span: 3 + span: 0 + span: 119 + span: 1 + } + location { + path: 12 + span: 3 + span: 0 + span: 18 + leading_detached_comments: " Copyright (c) 2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.\n SPDX-License-Identifier: Apache-2.0\n" + } + location { + path: 2 + span: 5 + span: 0 + span: 31 + } + location { + path: 3 + path: 0 + span: 7 + span: 0 + span: 60 + } + location { + path: 3 + path: 1 + span: 8 + span: 0 + span: 40 + } + location { + path: 8 + span: 10 + span: 0 + span: 51 + } + location { + path: 8 + path: 37 + span: 10 + span: 0 + span: 51 + } + location { + path: 8 + span: 11 + span: 0 + span: 57 + } + location { + path: 8 + path: 8 + span: 11 + span: 0 + span: 57 + } + location { + path: 8 + span: 12 + span: 0 + span: 47 + } + location { + path: 8 + path: 1 + span: 12 + span: 0 + span: 47 + } + location { + path: 6 + path: 0 + span: 15 + span: 0 + span: 18 + span: 1 + leading_comments: " Allows clients to retrieve information about the ledger API version\n" + } + location { + path: 6 + path: 0 + path: 1 + span: 15 + span: 8 + span: 22 + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + span: 17 + span: 2 + span: 92 + leading_comments: " Read the Ledger API version\n" + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + path: 1 + span: 17 + span: 6 + span: 25 + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + path: 2 + span: 17 + span: 26 + span: 52 + } + location { + path: 6 + path: 0 + path: 2 + path: 0 + path: 3 + span: 17 + span: 63 + span: 90 + } + location { + path: 4 + path: 0 + span: 20 + span: 0 + span: 37 + } + location { + path: 4 + path: 0 + path: 1 + span: 20 + span: 8 + span: 34 + } + location { + path: 4 + path: 1 + span: 22 + span: 0 + span: 40 + span: 1 + } + location { + path: 4 + path: 1 + path: 1 + span: 22 + span: 8 + span: 35 + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + path: 5 + span: 26 + span: 2 + span: 8 + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + span: 26 + span: 2 + span: 21 + leading_comments: " The version of the ledger API.\n\n Required\n" + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + path: 1 + span: 26 + span: 9 + span: 16 + } + location { + path: 4 + path: 1 + path: 2 + path: 0 + path: 3 + span: 26 + span: 19 + span: 20 + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + path: 6 + span: 39 + span: 2 + span: 20 + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + span: 39 + span: 2 + span: 34 + leading_comments: " The features supported by this Ledger API endpoint.\n\n Daml applications CAN use the feature descriptor on top of\n version constraints on the Ledger API version to determine\n whether a given Ledger API endpoint supports the features\n required to run the application.\n\n See the feature descriptions themselves for the relation between\n Ledger API versions and feature presence.\n\n Required\n" + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + path: 1 + span: 39 + span: 21 + span: 29 + } + location { + path: 4 + path: 1 + path: 2 + path: 1 + path: 3 + span: 39 + span: 32 + span: 33 + } + location { + path: 4 + path: 2 + span: 42 + span: 0 + span: 76 + span: 1 + } + location { + path: 4 + path: 2 + path: 1 + span: 42 + span: 8 + span: 26 + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + path: 6 + span: 49 + span: 2 + span: 22 + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + span: 49 + span: 2 + span: 40 + leading_comments: " Features under development or features that are used\n for ledger implementation testing purposes only.\n\n Daml applications SHOULD not depend on these in production.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + path: 1 + span: 49 + span: 23 + span: 35 + } + location { + path: 4 + path: 2 + path: 2 + path: 0 + path: 3 + span: 49 + span: 38 + span: 39 + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + path: 6 + span: 56 + span: 2 + span: 23 + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + span: 56 + span: 2 + span: 44 + leading_comments: " If set, then the Ledger API server supports user management.\n It is recommended that clients query this field to gracefully adjust their behavior for\n ledgers that do not support user management.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + path: 1 + span: 56 + span: 24 + span: 39 + } + location { + path: 4 + path: 2 + path: 2 + path: 1 + path: 3 + span: 56 + span: 42 + span: 43 + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + path: 6 + span: 63 + span: 2 + span: 24 + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + span: 63 + span: 2 + span: 46 + leading_comments: " If set, then the Ledger API server supports party management configurability.\n It is recommended that clients query this field to gracefully adjust their behavior to\n maximum party page size.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + path: 1 + span: 63 + span: 25 + span: 41 + } + location { + path: 4 + path: 2 + path: 2 + path: 2 + path: 3 + span: 63 + span: 44 + span: 45 + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + path: 6 + span: 68 + span: 2 + span: 25 + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + span: 68 + span: 2 + span: 48 + leading_comments: " It contains the timeouts related to the periodic offset checkpoint emission\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + path: 1 + span: 68 + span: 26 + span: 43 + } + location { + path: 4 + path: 2 + path: 2 + path: 3 + path: 3 + span: 68 + span: 46 + span: 47 + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + path: 6 + span: 75 + span: 2 + span: 16 + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + span: 75 + span: 2 + span: 37 + leading_comments: " If set, then the Ledger API server supports package listing\n configurability. It is recommended that clients query this field to\n gracefully adjust their behavior to maximum package listing page size.\n\n Required\n" + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + path: 1 + span: 75 + span: 17 + span: 32 + } + location { + path: 4 + path: 2 + path: 2 + path: 4 + path: 3 + span: 75 + span: 35 + span: 36 + } + location { + path: 4 + path: 3 + span: 78 + span: 0 + span: 97 + span: 1 + } + location { + path: 4 + path: 3 + path: 1 + span: 78 + span: 8 + span: 29 + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + path: 5 + span: 82 + span: 2 + span: 6 + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + span: 82 + span: 2 + span: 21 + leading_comments: " Whether the Ledger API server provides the user management service.\n\n Required\n" + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + path: 1 + span: 82 + span: 7 + span: 16 + } + location { + path: 4 + path: 3 + path: 2 + path: 0 + path: 3 + span: 82 + span: 19 + span: 20 + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + path: 5 + span: 89 + span: 2 + span: 7 + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + span: 89 + span: 2 + span: 32 + leading_comments: " The maximum number of rights that can be assigned to a single user.\n Servers MUST support at least 100 rights per user.\n A value of 0 means that the server enforces no rights per user limit.\n\n Required\n" + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + path: 1 + span: 89 + span: 8 + span: 27 + } + location { + path: 4 + path: 3 + path: 2 + path: 1 + path: 3 + span: 89 + span: 30 + span: 31 + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + path: 5 + span: 96 + span: 2 + span: 7 + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + span: 96 + span: 2 + span: 32 + leading_comments: " The maximum number of users the server can return in a single response (page).\n Servers MUST support at least a 100 users per page.\n A value of 0 means that the server enforces no page size limit.\n\n Required\n" + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + path: 1 + span: 96 + span: 8 + span: 27 + } + location { + path: 4 + path: 3 + path: 2 + path: 2 + path: 3 + span: 96 + span: 30 + span: 31 + } + location { + path: 4 + path: 4 + span: 99 + span: 0 + span: 104 + span: 1 + } + location { + path: 4 + path: 4 + path: 1 + span: 99 + span: 8 + span: 30 + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + path: 5 + span: 103 + span: 2 + span: 7 + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + span: 103 + span: 2 + span: 34 + leading_comments: " The maximum number of parties the server can return in a single response (page).\n\n Required\n" + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + path: 1 + span: 103 + span: 8 + span: 29 + } + location { + path: 4 + path: 4 + path: 2 + path: 0 + path: 3 + span: 103 + span: 32 + span: 33 + } + location { + path: 4 + path: 5 + span: 106 + span: 0 + span: 112 + span: 1 + } + location { + path: 4 + path: 5 + path: 1 + span: 106 + span: 8 + span: 22 + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + path: 5 + span: 111 + span: 2 + span: 7 + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + span: 111 + span: 2 + span: 42 + leading_comments: " The maximum number of vetted packages the server can return in a single\n response (page) when listing them.\n\n Required\n" + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + path: 1 + span: 111 + span: 8 + span: 37 + } + location { + path: 4 + path: 5 + path: 2 + path: 0 + path: 3 + span: 111 + span: 40 + span: 41 + } + location { + path: 4 + path: 6 + span: 114 + span: 0 + span: 119 + span: 1 + } + location { + path: 4 + path: 6 + path: 1 + span: 114 + span: 8 + span: 31 + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + path: 6 + span: 118 + span: 2 + span: 26 + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + span: 118 + span: 2 + span: 68 + leading_comments: " The maximum delay to emmit a new OffsetCheckpoint if it exists\n\n Required\n" + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + path: 1 + span: 118 + span: 27 + span: 63 + } + location { + path: 4 + path: 6 + path: 2 + path: 0 + path: 3 + span: 118 + span: 66 + span: 67 + } +} +syntax: "proto3" diff --git a/experiment-evidence/go-package-harmlessness/version_service.descriptor.semantic.diff b/experiment-evidence/go-package-harmlessness/version_service.descriptor.semantic.diff new file mode 100644 index 0000000000..46b897eb25 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.descriptor.semantic.diff @@ -0,0 +1,10 @@ +--- /Users/matthieu/Code/peaceful/canton/experiment-evidence/go-package-harmlessness/version_service.before.descriptor.nosourceinfo.txt 2026-05-11 16:16:34 ++++ /Users/matthieu/Code/peaceful/canton/experiment-evidence/go-package-harmlessness/version_service.after.descriptor.nosourceinfo.txt 2026-05-11 16:16:34 +@@ -132,6 +132,7 @@ + options { + java_package: "com.daml.ledger.api.v2" + java_outer_classname: "VersionServiceOuterClass" ++ go_package: "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2" + csharp_namespace: "Com.Daml.Ledger.Api.V2" + } + syntax: "proto3" diff --git a/experiment-evidence/go-package-harmlessness/version_service.proto.after b/experiment-evidence/go-package-harmlessness/version_service.proto.after new file mode 100644 index 0000000000..6fa09556f9 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.proto.after @@ -0,0 +1,121 @@ +// Copyright (c) 2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +syntax = "proto3"; + +package com.daml.ledger.api.v2; + +import "com/daml/ledger/api/v2/experimental_features.proto"; +import "google/protobuf/duration.proto"; + +option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; +option csharp_namespace = "Com.Daml.Ledger.Api.V2"; +option java_outer_classname = "VersionServiceOuterClass"; +option java_package = "com.daml.ledger.api.v2"; + +// Allows clients to retrieve information about the ledger API version +service VersionService { + // Read the Ledger API version + rpc GetLedgerApiVersion(GetLedgerApiVersionRequest) returns (GetLedgerApiVersionResponse); +} + +message GetLedgerApiVersionRequest {} + +message GetLedgerApiVersionResponse { + // The version of the ledger API. + // + // Required + string version = 1; + + // 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. + // + // Required + FeaturesDescriptor features = 2; +} + +message FeaturesDescriptor { + // Features under development or features that are used + // for ledger implementation testing purposes only. + // + // Daml applications SHOULD not depend on these in production. + // + // Required + ExperimentalFeatures experimental = 1; + + // 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. + // + // Required + UserManagementFeature user_management = 2; + + // If set, then the Ledger API server supports party management configurability. + // It is recommended that clients query this field to gracefully adjust their behavior to + // maximum party page size. + // + // Required + PartyManagementFeature party_management = 3; + + // It contains the timeouts related to the periodic offset checkpoint emission + // + // Required + OffsetCheckpointFeature offset_checkpoint = 4; + + // If set, then the Ledger API server supports package listing + // configurability. It is recommended that clients query this field to + // gracefully adjust their behavior to maximum package listing page size. + // + // Required + PackageFeature package_feature = 5; +} + +message UserManagementFeature { + // Whether the Ledger API server provides the user management service. + // + // Required + bool supported = 1; + + // 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. + // + // Required + int32 max_rights_per_user = 2; + + // 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. + // + // Required + int32 max_users_page_size = 3; +} + +message PartyManagementFeature { + // The maximum number of parties the server can return in a single response (page). + // + // Required + int32 max_parties_page_size = 1; +} + +message PackageFeature { + // The maximum number of vetted packages the server can return in a single + // response (page) when listing them. + // + // Required + int32 max_vetted_packages_page_size = 1; +} + +message OffsetCheckpointFeature { + // The maximum delay to emmit a new OffsetCheckpoint if it exists + // + // Required + google.protobuf.Duration max_offset_checkpoint_emission_delay = 1; +} diff --git a/experiment-evidence/go-package-harmlessness/version_service.proto.before b/experiment-evidence/go-package-harmlessness/version_service.proto.before new file mode 100644 index 0000000000..3d73627206 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.proto.before @@ -0,0 +1,120 @@ +// Copyright (c) 2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +syntax = "proto3"; + +package com.daml.ledger.api.v2; + +import "com/daml/ledger/api/v2/experimental_features.proto"; +import "google/protobuf/duration.proto"; + +option csharp_namespace = "Com.Daml.Ledger.Api.V2"; +option java_outer_classname = "VersionServiceOuterClass"; +option java_package = "com.daml.ledger.api.v2"; + +// Allows clients to retrieve information about the ledger API version +service VersionService { + // Read the Ledger API version + rpc GetLedgerApiVersion(GetLedgerApiVersionRequest) returns (GetLedgerApiVersionResponse); +} + +message GetLedgerApiVersionRequest {} + +message GetLedgerApiVersionResponse { + // The version of the ledger API. + // + // Required + string version = 1; + + // 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. + // + // Required + FeaturesDescriptor features = 2; +} + +message FeaturesDescriptor { + // Features under development or features that are used + // for ledger implementation testing purposes only. + // + // Daml applications SHOULD not depend on these in production. + // + // Required + ExperimentalFeatures experimental = 1; + + // 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. + // + // Required + UserManagementFeature user_management = 2; + + // If set, then the Ledger API server supports party management configurability. + // It is recommended that clients query this field to gracefully adjust their behavior to + // maximum party page size. + // + // Required + PartyManagementFeature party_management = 3; + + // It contains the timeouts related to the periodic offset checkpoint emission + // + // Required + OffsetCheckpointFeature offset_checkpoint = 4; + + // If set, then the Ledger API server supports package listing + // configurability. It is recommended that clients query this field to + // gracefully adjust their behavior to maximum package listing page size. + // + // Required + PackageFeature package_feature = 5; +} + +message UserManagementFeature { + // Whether the Ledger API server provides the user management service. + // + // Required + bool supported = 1; + + // 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. + // + // Required + int32 max_rights_per_user = 2; + + // 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. + // + // Required + int32 max_users_page_size = 3; +} + +message PartyManagementFeature { + // The maximum number of parties the server can return in a single response (page). + // + // Required + int32 max_parties_page_size = 1; +} + +message PackageFeature { + // The maximum number of vetted packages the server can return in a single + // response (page) when listing them. + // + // Required + int32 max_vetted_packages_page_size = 1; +} + +message OffsetCheckpointFeature { + // The maximum delay to emmit a new OffsetCheckpoint if it exists + // + // Required + google.protobuf.Duration max_offset_checkpoint_emission_delay = 1; +} diff --git a/experiment-evidence/go-package-harmlessness/version_service.proto.diff b/experiment-evidence/go-package-harmlessness/version_service.proto.diff new file mode 100644 index 0000000000..b24476d6a7 --- /dev/null +++ b/experiment-evidence/go-package-harmlessness/version_service.proto.diff @@ -0,0 +1,10 @@ +--- experiment-evidence/go-package-harmlessness/version_service.proto.before 2026-05-11 16:16:51 ++++ experiment-evidence/go-package-harmlessness/version_service.proto.after 2026-05-11 16:16:51 +@@ -8,6 +8,7 @@ + import "com/daml/ledger/api/v2/experimental_features.proto"; + import "google/protobuf/duration.proto"; + ++option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2"; + option csharp_namespace = "Com.Daml.Ledger.Api.V2"; + option java_outer_classname = "VersionServiceOuterClass"; + option java_package = "com.daml.ledger.api.v2"; diff --git a/experiment-evidence/openapi-generation/README.md b/experiment-evidence/openapi-generation/README.md new file mode 100644 index 0000000000..4786e635fe --- /dev/null +++ b/experiment-evidence/openapi-generation/README.md @@ -0,0 +1,46 @@ +# Generated OpenAPI artefacts + +## Contents + +| File | Source | +|---|---| +| `buf.gen.yaml` | The exact `buf generate` config used to produce the OpenAPI. | +| `command_service.swagger.json` | The 1,372-line OpenAPI 2.0 document generated from the annotated `command_service.proto` (plus its transitive proto closure). This is the "after" side of the SwaggerHub comparison linked at the top of PR #1. | + +## Reproduce + +```bash +# from canton repo root, on this branch: + +# 1. Make sure google common protos are unpacked where buf.work.yaml expects them +mkdir -p community/lib/google-common-protos-scala/target/protobuf_external/google/api \ + community/lib/google-common-protos-scala/target/protobuf_external/google/rpc +curl -sS -o community/lib/google-common-protos-scala/target/protobuf_external/google/api/annotations.proto \ + https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto +curl -sS -o community/lib/google-common-protos-scala/target/protobuf_external/google/api/http.proto \ + https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto +curl -sS -o community/lib/google-common-protos-scala/target/protobuf_external/google/rpc/status.proto \ + https://raw.githubusercontent.com/googleapis/googleapis/master/google/rpc/status.proto + +# 2. Run buf generate with the bundled config +cd experiment-evidence/openapi-generation +buf generate \ + --path ../../community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto \ + ../../community/ledger-api-proto/src/main/protobuf + +# 3. Output appears at gen/openapi/com/daml/ledger/api/v2/command_service.swagger.json +diff gen/openapi/com/daml/ledger/api/v2/command_service.swagger.json command_service.swagger.json +# (empty — byte-identical) +``` + +## What's in the output + +Three operations, fully typed end-to-end: + +``` +POST /v2/commands/submit-and-wait +POST /v2/commands/submit-and-wait-for-transaction +POST /v2/commands/submit-and-wait-for-reassignment +``` + +Schema definitions are qualified by proto package (`com.daml.ledger.api.v2.Commands`, `com.daml.ledger.api.v2.Record`, …). No `Empty1`–`Empty10`, no single-key `oneOf` envelopes, no inline duplicated enums, no untyped DAML payload fields. See PR #1's defect-by-defect table for the side-by-side with the current tapir-emitted spec. diff --git a/experiment-evidence/openapi-generation/buf.gen.yaml b/experiment-evidence/openapi-generation/buf.gen.yaml new file mode 100644 index 0000000000..280be62814 --- /dev/null +++ b/experiment-evidence/openapi-generation/buf.gen.yaml @@ -0,0 +1,8 @@ +version: v2 +plugins: + - remote: buf.build/grpc-ecosystem/openapiv2:v2.28.0 + out: gen/openapi + opt: + - allow_delete_body=true + - json_names_for_fields=true + - openapi_naming_strategy=fqn diff --git a/experiment-evidence/openapi-generation/command_service.swagger.json b/experiment-evidence/openapi-generation/command_service.swagger.json new file mode 100644 index 0000000000..001ae3c37f --- /dev/null +++ b/experiment-evidence/openapi-generation/command_service.swagger.json @@ -0,0 +1,1372 @@ +{ + "swagger": "2.0", + "info": { + "title": "com/daml/ledger/api/v2/command_service.proto", + "version": "version not set" + }, + "tags": [ + { + "name": "CommandService" + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/v2/commands/submit-and-wait": { + "post": { + "summary": "Submits a single composite command and waits for its result.\nPropagates the gRPC error of failed submissions including Daml interpretation errors.", + "operationId": "CommandService_SubmitAndWait", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/com.daml.ledger.api.v2.SubmitAndWaitResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/google.rpc.Status" + } + } + }, + "parameters": [ + { + "name": "commands", + "description": "The commands to be submitted.\n\nRequired", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Commands" + } + } + ], + "tags": [ + "CommandService" + ] + } + }, + "/v2/commands/submit-and-wait-for-reassignment": { + "post": { + "summary": "Submits a single composite reassignment command, waits for its result, and returns the reassignment.\nPropagates the gRPC error of failed submission.", + "operationId": "CommandService_SubmitAndWaitForReassignment", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForReassignmentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/google.rpc.Status" + } + } + }, + "parameters": [ + { + "name": "body", + "description": "This reassignment is executed as a single atomic update.", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForReassignmentRequest" + } + } + ], + "tags": [ + "CommandService" + ] + } + }, + "/v2/commands/submit-and-wait-for-transaction": { + "post": { + "summary": "Submits a single composite command, waits for its result, and returns the transaction.\nPropagates the gRPC error of failed submissions including Daml interpretation errors.", + "operationId": "CommandService_SubmitAndWaitForTransaction", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForTransactionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/google.rpc.Status" + } + } + }, + "parameters": [ + { + "name": "body", + "description": "These commands are executed as a single atomic transaction.", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForTransactionRequest" + } + } + ], + "tags": [ + "CommandService" + ] + } + } + }, + "definitions": { + "com.daml.ledger.api.v2.ArchivedEvent": { + "type": "object", + "properties": { + "offset": { + "type": "string", + "format": "int64", + "description": "Required", + "title": "The offset of origin.\nOffsets are managed by the participant nodes.\nTransactions can thus NOT be assumed to have the same offsets on different participant nodes.\nIt is a valid absolute offset (positive integer)" + }, + "nodeId": { + "type": "integer", + "format": "int32", + "description": "Required", + "title": "The position of this event in the originating transaction or reassignment.\nNode IDs are not necessarily equal across participants,\nas these may see different projections/parts of transactions.\nMust be valid node ID (non-negative integer)" + }, + "contractId": { + "type": "string", + "description": "The ID of the archived contract.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "Identifies the template that defines the choice that archived the contract.\nThis template's package-id may differ from the target contract's package-id\nif the target contract has been upgraded or downgraded.\n\nThe identifier uses the package-id reference format.\n\nRequired" + }, + "witnessParties": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The parties that are notified of this event. For an ``ArchivedEvent``,\nthese are the intersection of the stakeholders of the contract in\nquestion and the parties specified in the ``TransactionFilter``. The\nstakeholders are the union of the signatories and the observers of\nthe contract.\nEach one of its elements must be a valid PartyIdString (as described\nin ``value.proto``).\n\nRequired: must be non-empty" + }, + "packageName": { + "type": "string", + "description": "The package name of the contract.\n\nRequired" + }, + "implementedInterfaces": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier" + }, + "description": "The interfaces implemented by the target template that have been\nmatched from the interface filter query.\nPopulated only in case interface filters with include_interface_view set.\n\nIf defined, the identifier uses the package-id reference format.\n\nOptional: can be empty" + } + }, + "description": "Records that a contract has been archived, and choices may no longer be exercised on it." + }, + "com.daml.ledger.api.v2.AssignCommand": { + "type": "object", + "properties": { + "reassignmentId": { + "type": "string", + "description": "The ID from the unassigned event to be completed by this assignment.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "source": { + "type": "string", + "description": "Required", + "title": "The ID of the source synchronizer\nMust be a valid synchronizer id" + }, + "target": { + "type": "string", + "description": "Required", + "title": "The ID of the target synchronizer\nMust be a valid synchronizer id" + } + }, + "title": "Assign a contract" + }, + "com.daml.ledger.api.v2.AssignedEvent": { + "type": "object", + "properties": { + "source": { + "type": "string", + "description": "The ID of the source synchronizer.\nMust be a valid synchronizer id.\n\nRequired" + }, + "target": { + "type": "string", + "description": "The ID of the target synchronizer.\nMust be a valid synchronizer id.\n\nRequired" + }, + "reassignmentId": { + "type": "string", + "description": "The ID from the unassigned event.\nFor correlation capabilities.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "submitter": { + "type": "string", + "description": "Party on whose behalf the assign command was executed.\nEmpty if the assignment happened offline via the repair service.\nMust be a valid PartyIdString (as described in ``value.proto``).\n\nOptional" + }, + "reassignmentCounter": { + "type": "string", + "format": "uint64", + "description": "Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases\nwith each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter\nequals zero.\n\nRequired" + }, + "createdEvent": { + "$ref": "#/definitions/com.daml.ledger.api.v2.CreatedEvent", + "description": "The offset of this event refers to the offset of the assignment,\nwhile the node_id is the index of within the batch.\n\nRequired" + } + }, + "description": "Records that a contract has been assigned, and it can be used on the target synchronizer." + }, + "com.daml.ledger.api.v2.Command": { + "type": "object", + "properties": { + "create": { + "$ref": "#/definitions/com.daml.ledger.api.v2.CreateCommand" + }, + "exercise": { + "$ref": "#/definitions/com.daml.ledger.api.v2.ExerciseCommand" + }, + "exerciseByKey": { + "$ref": "#/definitions/com.daml.ledger.api.v2.ExerciseByKeyCommand" + }, + "createAndExercise": { + "$ref": "#/definitions/com.daml.ledger.api.v2.CreateAndExerciseCommand" + } + }, + "description": "A command can either create a new contract or exercise a choice on an existing contract." + }, + "com.daml.ledger.api.v2.Commands": { + "type": "object", + "properties": { + "workflowId": { + "type": "string", + "description": "Identifier of the on-ledger workflow that this command is a part of.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nOptional" + }, + "userId": { + "type": "string", + "description": "Uniquely identifies the participant user that issued the command.\nMust be a valid UserIdString (as described in ``value.proto``).\nRequired unless authentication is used with a user token.\nIn that case, the token's user-id will be used for the request's user_id.\n\nOptional" + }, + "commandId": { + "type": "string", + "description": "Uniquely identifies the command.\nThe triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change,\nwhere act_as is interpreted as a set of party names.\nThe change ID can be used for matching the intended ledger changes with all their completions.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "commands": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.Command" + }, + "description": "Individual elements of this atomic command. Must be non-empty.\n\nRequired: must be non-empty" + }, + "deduplicationDuration": { + "type": "string", + "description": "Specifies the length of the deduplication period.\nIt is interpreted relative to the local clock at some point during the submission's processing.\nMust be non-negative. Must not exceed the maximum deduplication time." + }, + "deduplicationOffset": { + "type": "string", + "format": "int64", + "description": "Specifies the start of the deduplication period by a completion stream offset (exclusive).\nMust be a valid absolute offset (positive integer) or participant begin (zero)." + }, + "minLedgerTimeAbs": { + "type": "string", + "format": "date-time", + "description": "Lower bound for the ledger time assigned to the resulting transaction.\nNote: The ledger time of a transaction is assigned as part of command interpretation.\nUse this property if you expect that command interpretation will take a considerate amount of time, such that by\nthe time the resulting transaction is sequenced, its assigned ledger time is not valid anymore.\nMust not be set at the same time as min_ledger_time_rel.\n\nOptional" + }, + "minLedgerTimeRel": { + "type": "string", + "description": "Same as min_ledger_time_abs, but specified as a duration, starting from the time the command is received by the server.\nMust not be set at the same time as min_ledger_time_abs.\n\nOptional" + }, + "actAs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Set of parties on whose behalf the command should be executed.\nIf ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request\nto act on behalf of each of the given parties.\nEach element must be a valid PartyIdString (as described in ``value.proto``).\n\nRequired: must be non-empty" + }, + "readAs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Set of parties on whose behalf (in addition to all parties listed in ``act_as``) contracts can be retrieved.\nThis affects Daml operations such as ``fetch``, ``fetchByKey``, ``lookupByKey``, ``exercise``, and ``exerciseByKey``.\nNote: A participant node of a Daml network can host multiple parties. Each contract present on the participant\nnode is only visible to a subset of these parties. A command can only use contracts that are visible to at least\none of the parties in ``act_as`` or ``read_as``. This visibility check is independent from the Daml authorization\nrules for fetch operations.\nIf ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request\nto read contract data on behalf of each of the given parties.\n\nOptional: can be empty" + }, + "submissionId": { + "type": "string", + "description": "A unique identifier to distinguish completions for different submissions with the same change ID.\nTypically a random UUID. Applications are expected to use a different UUID for each retry of a submission\nwith the same change ID.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nIf omitted, the participant or the committer may set a value of their choice.\n\nOptional" + }, + "disclosedContracts": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.DisclosedContract" + }, + "description": "Additional contracts used to resolve contract \u0026 contract key lookups.\n\nOptional: can be empty" + }, + "synchronizerId": { + "type": "string", + "description": "Optional", + "title": "Must be a valid synchronizer id" + }, + "packageIdSelectionPreference": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Optional: can be empty", + "title": "The package-id selection preference of the client for resolving\npackage names and interface instances in command submission and interpretation" + }, + "prefetchContractKeys": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.PrefetchContractKey" + }, + "description": "Fetches the contract keys into the caches to speed up the command processing.\nShould only contain contract keys that are expected to be resolved during interpretation of the commands.\nKeys of disclosed contracts do not need prefetching.\n\nOptional: can be empty" + }, + "tapsMaxPasses": { + "type": "integer", + "format": "int64", + "description": "The maximum number of passes for the Topology-Aware Package Selection (TAPS).\nHigher values can increase the chance of successful package selection for routing of interpreted transactions.\nIf unset, this defaults to the value defined in the participant configuration.\nThe provided value must not exceed the limit specified in the participant configuration.\n\nOptional" + } + }, + "description": "A composite command that groups multiple commands together." + }, + "com.daml.ledger.api.v2.CreateAndExerciseCommand": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template of the contract the client wants to create.\nBoth package-name and package-id reference identifier formats for the template-id are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\n\nRequired" + }, + "createArguments": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Record", + "description": "The arguments required for creating a contract from this template.\n\nRequired" + }, + "choice": { + "type": "string", + "description": "The name of the choice the client wants to exercise.\nMust be a valid NameString (as described in ``value.proto``).\n\nRequired" + }, + "choiceArgument": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The argument for this choice.\n\nRequired" + } + }, + "description": "Create a contract and exercise a choice on it in the same transaction." + }, + "com.daml.ledger.api.v2.CreateCommand": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template of contract the client wants to create.\nBoth package-name and package-id reference identifier formats for the template-id are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\n\nRequired" + }, + "createArguments": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Record", + "description": "The arguments required for creating a contract from this template.\n\nRequired" + } + }, + "description": "Create a new contract instance based on a template." + }, + "com.daml.ledger.api.v2.CreatedEvent": { + "type": "object", + "properties": { + "offset": { + "type": "string", + "format": "int64", + "description": "Required", + "title": "The offset of origin, which has contextual meaning, please see description at messages that include a CreatedEvent.\nOffsets are managed by the participant nodes.\nTransactions can thus NOT be assumed to have the same offsets on different participant nodes.\nIt is a valid absolute offset (positive integer)" + }, + "nodeId": { + "type": "integer", + "format": "int32", + "description": "Required", + "title": "The position of this event in the originating transaction or reassignment.\nThe origin has contextual meaning, please see description at messages that include a CreatedEvent.\nNode IDs are not necessarily equal across participants,\nas these may see different projections/parts of transactions.\nMust be valid node ID (non-negative integer)" + }, + "contractId": { + "type": "string", + "description": "The ID of the created contract.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template of the created contract.\nThe identifier uses the package-id reference format.\n\nRequired" + }, + "contractKey": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The key of the created contract.\nThis will be set if and only if ``template_id`` defines a contract key.\n\nOptional" + }, + "contractKeyHash": { + "type": "string", + "format": "byte", + "description": "The hash of contract_key.\nThis will be set if and only if ``template_id`` defines a contract key.\n\nOptional: can be empty" + }, + "createArguments": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Record", + "description": "The arguments that have been used to create the contract.\n\nRequired" + }, + "createdEventBlob": { + "type": "string", + "format": "byte", + "description": "Opaque representation of contract create event payload intended for forwarding\nto an API server as a contract disclosed as part of a command\nsubmission.\n\nOptional: can be empty" + }, + "interfaceViews": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.InterfaceView" + }, + "description": "- its party in the ``witness_parties`` of this event,\n- and which is implemented by the template of this event,\n- and which has ``include_interface_view`` set.\n\nOptional: can be empty", + "title": "Interface views specified in the transaction filter.\nIncludes an ``InterfaceView`` for each interface for which there is a ``InterfaceFilter`` with" + }, + "witnessParties": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The parties that are notified of this event. When a ``CreatedEvent``\nis returned as part of a transaction tree or ledger-effects transaction, this will include all\nthe parties specified in the ``TransactionFilter`` that are witnesses of the event\n(the stakeholders of the contract and all informees of all the ancestors\nof this create action that this participant knows about).\nIf served as part of a ACS delta transaction those will\nbe limited to all parties specified in the ``TransactionFilter`` that\nare stakeholders of the contract (i.e. either signatories or observers).\nIf the ``CreatedEvent`` is returned as part of an AssignedEvent,\nActiveContract or IncompleteUnassigned (so the event is related to\nan assignment or unassignment): this will include all parties of the\n``TransactionFilter`` that are stakeholders of the contract.\n\nThe behavior of reading create events visible to parties not hosted\non the participant node serving the Ledger API is undefined. Concretely,\nthere is neither a guarantee that the participant node will serve all their\ncreate events on the ACS stream, nor is there a guarantee that matching archive\nevents are delivered for such create events.\n\nFor most clients this is not a problem, as they only read events for parties\nthat are hosted on the participant node. If you need to read events\nfor parties that may not be hosted at all times on the participant node,\nsubscribe to the ``TopologyEvent``s for that party by setting a corresponding\n``UpdateFormat``. Using these events, query the ACS as-of an offset where the\nparty is hosted on the participant node, and ignore create events at offsets\nwhere the party is not hosted on the participant node.\n\nRequired: must be non-empty" + }, + "signatories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The signatories for this contract as specified by the template.\n\nRequired: must be non-empty" + }, + "observers": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The observers for this contract as specified explicitly by the template or implicitly as choice controllers.\nThis field never contains parties that are signatories.\n\nOptional: can be empty" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Ledger effective time of the transaction that created the contract.\n\nRequired" + }, + "packageName": { + "type": "string", + "description": "The package name of the created contract.\n\nRequired" + }, + "acsDelta": { + "type": "boolean", + "description": "Whether this event would be part of respective ACS_DELTA shaped stream,\nand should therefore considered when tracking contract activeness on the client-side.\n\nRequired" + }, + "representativePackageId": { + "type": "string", + "description": "A package-id present in the participant package store that typechecks the contract's argument.\nThis may differ from the package-id of the template used to create the contract.\nFor contracts created before Canton 3.4, this field matches the contract's creation package-id.\n\nNOTE: Experimental, server internal concept, not for client consumption. Subject to change without notice.\n\nRequired" + } + }, + "description": "Records that a contract has been created, and choices may now be exercised on it." + }, + "com.daml.ledger.api.v2.CumulativeFilter": { + "type": "object", + "properties": { + "wildcardFilter": { + "$ref": "#/definitions/com.daml.ledger.api.v2.WildcardFilter", + "description": "Optional", + "title": "A wildcard filter that matches all templates" + }, + "interfaceFilter": { + "$ref": "#/definitions/com.daml.ledger.api.v2.InterfaceFilter", + "description": "Include an ``InterfaceView`` for every ``InterfaceFilter`` matching a contract.\nThe ``InterfaceFilter`` instances MUST each use a unique ``interface_id``.\n\nOptional" + }, + "templateFilter": { + "$ref": "#/definitions/com.daml.ledger.api.v2.TemplateFilter", + "description": "A template for which the data will be included in the\n``create_arguments`` of a matching ``CreatedEvent``.\nIf a contract is simultaneously selected by a template filter and one or more interface filters,\nthe corresponding ``include_created_event_blob`` are consolidated using an OR operation.\n\nOptional" + } + }, + "description": "A filter that matches all contracts that are either an instance of one of\nthe ``template_filters`` or that match one of the ``interface_filters``." + }, + "com.daml.ledger.api.v2.DisclosedContract": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template id of the contract.\nThe identifier uses the package-id reference format.\n\nIf provided, used to validate the template id of the contract serialized in the created_event_blob.\n\nOptional" + }, + "contractId": { + "type": "string", + "description": "If provided, used to validate the contract id of the contract serialized in the created_event_blob.\n\nOptional", + "title": "The contract id" + }, + "createdEventBlob": { + "type": "string", + "format": "byte", + "description": "Opaque byte string containing the complete payload required by the Daml engine\nto reconstruct a contract not known to the receiving participant.\n\nRequired: must be non-empty" + }, + "synchronizerId": { + "type": "string", + "description": "Optional", + "title": "The ID of the synchronizer where the contract is currently assigned" + } + }, + "description": "An additional contract that is used to resolve\ncontract \u0026 contract key lookups." + }, + "com.daml.ledger.api.v2.Enum": { + "type": "object", + "properties": { + "enumId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "Omitted from the transaction stream when verbose streaming is not enabled.\nOptional when submitting commands." + }, + "constructor": { + "type": "string", + "title": "Determines which of the Variant's alternatives is encoded in this message.\nMust be a valid NameString.\nRequired" + } + }, + "description": "A value with finite set of alternative representations." + }, + "com.daml.ledger.api.v2.Event": { + "type": "object", + "properties": { + "created": { + "$ref": "#/definitions/com.daml.ledger.api.v2.CreatedEvent", + "description": "The event as it appeared in the context of its original daml transaction on this participant node.\nIn particular, the offset, node_id pair of the daml transaction are preserved." + }, + "archived": { + "$ref": "#/definitions/com.daml.ledger.api.v2.ArchivedEvent" + }, + "exercised": { + "$ref": "#/definitions/com.daml.ledger.api.v2.ExercisedEvent" + } + }, + "description": "- ACS delta: events can be CreatedEvent or ArchivedEvent\n- ledger effects: events can be CreatedEvent or ExercisedEvent\n\nIn the update service the events are restricted to the events\nvisible for the parties specified in the transaction filter. Each\nevent message type below contains a ``witness_parties`` field which\nindicates the subset of the requested parties that can see the event\nin question.", + "title": "Events in transactions can have two primary shapes:" + }, + "com.daml.ledger.api.v2.EventFormat": { + "type": "object", + "properties": { + "filtersByParty": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Filters" + }, + "description": "1. For **ledger-effects** create and exercise events are returned, for which the witnesses include at least one of\n the listed parties and match the per-party filter.\n2. For **transaction and active-contract-set streams** create and archive events are returned for all contracts whose\n stakeholders include at least one of the listed parties and match the per-party filter.\n\nOptional: can be empty", + "title": "Each key must be a valid PartyIdString (as described in ``value.proto``).\nThe interpretation of the filter depends on the transaction-shape being filtered:" + }, + "filtersForAnyParty": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Filters", + "description": "Wildcard filters that apply to all the parties existing on the participant. The interpretation of the filters is the same\nwith the per-party filter as described above.\n\nOptional" + }, + "verbose": { + "type": "boolean", + "description": "If enabled, values served over the API will contain more information than strictly necessary to interpret the data.\nIn particular, setting the verbose flag to true triggers the ledger to include labels for record fields.\n\nOptional" + } + }, + "description": "A format for events which defines both which events should be included\nand what data should be computed and included for them.\n\nNote that some of the filtering behavior depends on the `TransactionShape`,\nwhich is expected to be specified alongside usages of `EventFormat`." + }, + "com.daml.ledger.api.v2.ExerciseByKeyCommand": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template of contract the client wants to exercise.\nBoth package-name and package-id reference identifier formats for the template-id are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\n\nRequired" + }, + "contractKey": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The key of the contract the client wants to exercise upon.\n\nRequired" + }, + "choice": { + "type": "string", + "description": "Required", + "title": "The name of the choice the client wants to exercise.\nMust be a valid NameString (as described in ``value.proto``)" + }, + "choiceArgument": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The argument for this choice.\n\nRequired" + } + }, + "description": "Exercise a choice on an existing contract specified by its key." + }, + "com.daml.ledger.api.v2.ExerciseCommand": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template or interface of the contract the client wants to exercise.\nBoth package-name and package-id reference identifier formats for the template-id are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\nTo exercise a choice on an interface, specify the interface identifier in the template_id field.\n\nRequired" + }, + "contractId": { + "type": "string", + "description": "The ID of the contract the client wants to exercise upon.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "choice": { + "type": "string", + "description": "Required", + "title": "The name of the choice the client wants to exercise.\nMust be a valid NameString (as described in ``value.proto``)" + }, + "choiceArgument": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The argument for this choice.\n\nRequired" + } + }, + "description": "Exercise a choice on an existing contract." + }, + "com.daml.ledger.api.v2.ExercisedEvent": { + "type": "object", + "properties": { + "offset": { + "type": "string", + "format": "int64", + "description": "Required", + "title": "The offset of origin.\nOffsets are managed by the participant nodes.\nTransactions can thus NOT be assumed to have the same offsets on different participant nodes.\nIt is a valid absolute offset (positive integer)" + }, + "nodeId": { + "type": "integer", + "format": "int32", + "description": "Required", + "title": "The position of this event in the originating transaction or reassignment.\nNode IDs are not necessarily equal across participants,\nas these may see different projections/parts of transactions.\nMust be valid node ID (non-negative integer)" + }, + "contractId": { + "type": "string", + "description": "The ID of the target contract.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "Identifies the template that defines the executed choice.\nThis template's package-id may differ from the target contract's package-id\nif the target contract has been upgraded or downgraded.\n\nThe identifier uses the package-id reference format.\n\nRequired" + }, + "interfaceId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The interface where the choice is defined, if inherited.\nIf defined, the identifier uses the package-id reference format.\n\nOptional" + }, + "choice": { + "type": "string", + "description": "The choice that was exercised on the target contract.\nMust be a valid NameString (as described in ``value.proto``).\n\nRequired" + }, + "choiceArgument": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The argument of the exercised choice.\n\nRequired" + }, + "actingParties": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The parties that exercised the choice.\nEach element must be a valid PartyIdString (as described in ``value.proto``).\n\nRequired: must be non-empty" + }, + "consuming": { + "type": "boolean", + "description": "If true, the target contract may no longer be exercised.\n\nRequired" + }, + "witnessParties": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The parties that are notified of this event. The witnesses of an exercise\nnode will depend on whether the exercise was consuming or not.\nIf consuming, the witnesses are the union of the stakeholders,\nthe actors and all informees of all the ancestors of this event this\nparticipant knows about.\nIf not consuming, the witnesses are the union of the signatories,\nthe actors and all informees of all the ancestors of this event this\nparticipant knows about.\nIn both cases the witnesses are limited to the querying parties, or not\nlimited in case anyParty filters are used.\nNote that the actors might not necessarily be observers\nand thus stakeholders. This is the case when the controllers of a\nchoice are specified using \"flexible controllers\", using the\n``choice ... controller`` syntax, and said controllers are not\nexplicitly marked as observers.\nEach element must be a valid PartyIdString (as described in ``value.proto``).\n\nRequired: must be non-empty" + }, + "lastDescendantNodeId": { + "type": "integer", + "format": "int32", + "description": "Specifies the upper boundary of the node ids of the events in the same transaction that appeared as a result of\nthis ``ExercisedEvent``. This allows unambiguous identification of all the members of the subtree rooted at this\nnode. A full subtree can be constructed when all descendant nodes are present in the stream. If nodes are heavily\nfiltered, it is only possible to determine if a node is in a consequent subtree or not.\n\nRequired" + }, + "exerciseResult": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The result of exercising the choice.\n\nOptional" + }, + "packageName": { + "type": "string", + "description": "The package name of the contract.\n\nRequired" + }, + "implementedInterfaces": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier" + }, + "description": "If the event is consuming, the interfaces implemented by the target template that have been\nmatched from the interface filter query.\nPopulated only in case interface filters with include_interface_view set.\n\nThe identifier uses the package-id reference format.\n\nOptional: can be empty" + }, + "acsDelta": { + "type": "boolean", + "description": "Whether this event would be part of respective ACS_DELTA shaped stream,\nand should therefore considered when tracking contract activeness on the client-side.\n\nRequired" + } + }, + "description": "Records that a choice has been exercised on a target contract." + }, + "com.daml.ledger.api.v2.Filters": { + "type": "object", + "properties": { + "cumulative": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.CumulativeFilter" + }, + "description": "Every filter in the cumulative list expands the scope of the resulting stream. Each interface,\ntemplate or wildcard filter means additional events that will match the query.\nThe impact of include_interface_view and include_created_event_blob fields in the filters will\nalso be accumulated.\nA template or an interface SHOULD NOT appear twice in the accumulative field.\nA wildcard filter SHOULD NOT be defined more than once in the accumulative field.\nIf no ``CumulativeFilter`` defined, the default of a single ``WildcardFilter`` with\ninclude_created_event_blob unset is used.\n\nOptional: can be empty" + } + }, + "description": "The union of a set of template filters, interface filters, or a wildcard." + }, + "com.daml.ledger.api.v2.GenMap": { + "type": "object", + "properties": { + "entries": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.GenMap.Entry" + } + } + } + }, + "com.daml.ledger.api.v2.GenMap.Entry": { + "type": "object", + "properties": { + "key": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value" + }, + "value": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value" + } + } + }, + "com.daml.ledger.api.v2.Identifier": { + "type": "object", + "properties": { + "packageId": { + "type": "string", + "description": "Generally, the identifier of the Daml package that contains the entity.\nWhen encoding a package-id, it must be a valid PackageIdString.\n\nThe field is overloaded to also be able to contain the package-name of the Daml package.\nThis is supported if the entity referenced is either an interface or template.\nWhen representing the Daml package-name, the encoding is of form `#\u003cpackage-name\u003e`\nwhere `#` (not a valid package-id character)\nis used as a discriminator for signalling a package-name encoding.\n\nRequired" + }, + "moduleName": { + "type": "string", + "title": "The dot-separated module name of the identifier.\nRequired" + }, + "entityName": { + "type": "string", + "title": "The dot-separated name of the entity (e.g. record, template, ...) within the module.\nRequired" + } + }, + "description": "- if a Daml package-id is encoded in the package_id field, it is referred to as using a \"package-id reference format\"\n - if a Daml package-name is encoded in the package_id field, it is referred to as using a \"package-name reference format\"", + "title": "Unique identifier of an entity.\nThroughout this API, the following terminology is being used:" + }, + "com.daml.ledger.api.v2.InterfaceFilter": { + "type": "object", + "properties": { + "interfaceId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The interface that a matching contract must implement.\nThe ``interface_id`` needs to be valid: corresponding interface should be defined in\none of the available packages at the time of the query.\nBoth package-name and package-id reference formats for the identifier are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\n\nRequired" + }, + "includeInterfaceView": { + "type": "boolean", + "description": "Whether to include the interface view on the contract in the returned ``CreatedEvent``.\nUse this to access contract data in a uniform manner in your API client.\n\nOptional" + }, + "includeCreatedEventBlob": { + "type": "boolean", + "description": "Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``.\nUse this to access the contract create event payload in your API client\nfor submitting it as a disclosed contract with future commands.\n\nOptional" + } + }, + "description": "This filter matches contracts that implement a specific interface." + }, + "com.daml.ledger.api.v2.InterfaceView": { + "type": "object", + "properties": { + "interfaceId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The interface implemented by the matched event.\nThe identifier uses the package-id reference format.\n\nRequired" + }, + "viewStatus": { + "$ref": "#/definitions/google.rpc.Status", + "description": "Whether the view was successfully computed, and if not,\nthe reason for the error. The error is reported using the same rules\nfor error codes and messages as the errors returned for API requests.\n\nRequired" + }, + "viewValue": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Record", + "description": "The value of the interface's view method on this event.\nSet if it was requested in the ``InterfaceFilter`` and it could be\nsuccessfully computed.\n\nOptional" + }, + "implementationPackageId": { + "type": "string", + "description": "The package defining the interface implementation used to compute the view.\nCan be different from the package that was used to create the contract itself,\nas the contract arguments can be upgraded or downgraded using smart-contract upgrading\nas part of computing the interface view.\nPopulated if the view computation is successful, otherwise empty.\n\nOptional" + } + }, + "description": "View of a create event matched by an interface filter." + }, + "com.daml.ledger.api.v2.List": { + "type": "object", + "properties": { + "elements": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.Value" + }, + "title": "The elements must all be of the same concrete value type.\nOptional" + } + }, + "description": "A homogenous collection of values." + }, + "com.daml.ledger.api.v2.Optional": { + "type": "object", + "properties": { + "value": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "title": "optional" + } + }, + "description": "Corresponds to Java's Optional type, Scala's Option, and Haskell's Maybe.\nThe reason why we need to wrap this in an additional ``message`` is that we\nneed to be able to encode the ``None`` case in the ``Value`` oneof." + }, + "com.daml.ledger.api.v2.PrefetchContractKey": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template of contract the client wants to prefetch.\nBoth package-name and package-id reference identifier formats for the template-id are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\n\nRequired" + }, + "contractKey": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "description": "The key of the contract the client wants to prefetch.\n\nRequired" + } + }, + "title": "Preload contracts" + }, + "com.daml.ledger.api.v2.Reassignment": { + "type": "object", + "properties": { + "updateId": { + "type": "string", + "description": "Assigned by the server. Useful for correlating logs.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "commandId": { + "type": "string", + "description": "The ID of the command which resulted in this reassignment. Missing for everyone except the submitting party on the submitting participant.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nOptional" + }, + "workflowId": { + "type": "string", + "description": "The workflow ID used in reassignment command submission. Only set if the ``workflow_id`` for the command was set.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nOptional" + }, + "offset": { + "type": "string", + "format": "int64", + "description": "The participant's offset. The details of this field are described in ``community/ledger-api/README.md``.\nMust be a valid absolute offset (positive integer).\n\nRequired" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.ReassignmentEvent" + }, + "description": "The collection of reassignment events.\n\nRequired: must be non-empty" + }, + "traceContext": { + "$ref": "#/definitions/com.daml.ledger.api.v2.TraceContext", + "description": "The trace context transported in this message corresponds to the trace context supplied\nby the client application in a HTTP2 header of the original command submission.\nWe typically use a header to transfer this type of information. Here we use message\nbody, because it is used in gRPC streams which do not support per message headers.\nThis field will be populated with the trace context contained in the original submission.\nIf that was not provided, a unique ledger-api-server generated trace context will be used\ninstead.\n\nOptional", + "title": "Ledger API trace context" + }, + "recordTime": { + "type": "string", + "format": "date-time", + "description": "The time at which the reassignment was recorded. The record time refers to the source/target\nsynchronizer for an unassign/assign event respectively.\n\nRequired" + }, + "synchronizerId": { + "type": "string", + "description": "A valid synchronizer id.\nIdentifies the synchronizer that synchronized this Reassignment.\n\nRequired" + }, + "paidTrafficCost": { + "type": "string", + "format": "int64", + "description": "The traffic cost that this participant node paid for the corresponding (un)assignment request.\n\nNot set for transactions that were\n- initiated by another participant\n- initiated offline via the repair service\n- processed before the participant started serving traffic cost on the Ledger API\n- returned as part of a query filtering for a non submitting party\n\nOptional" + } + }, + "description": "Complete view of an on-ledger reassignment." + }, + "com.daml.ledger.api.v2.ReassignmentCommand": { + "type": "object", + "properties": { + "unassignCommand": { + "$ref": "#/definitions/com.daml.ledger.api.v2.UnassignCommand" + }, + "assignCommand": { + "$ref": "#/definitions/com.daml.ledger.api.v2.AssignCommand" + } + } + }, + "com.daml.ledger.api.v2.ReassignmentCommands": { + "type": "object", + "properties": { + "workflowId": { + "type": "string", + "description": "Identifier of the on-ledger workflow that this command is a part of.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nOptional" + }, + "userId": { + "type": "string", + "description": "Uniquely identifies the participant user that issued the command.\nMust be a valid UserIdString (as described in ``value.proto``).\nRequired unless authentication is used with a user token.\nIn that case, the token's user-id will be used for the request's user_id.\n\nOptional" + }, + "commandId": { + "type": "string", + "description": "Uniquely identifies the command.\nThe triple (user_id, submitter, command_id) constitutes the change ID for the intended ledger change.\nThe change ID can be used for matching the intended ledger changes with all their completions.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "submitter": { + "type": "string", + "description": "Party on whose behalf the command should be executed.\nIf ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request\nto act on behalf of the given party.\nMust be a valid PartyIdString (as described in ``value.proto``).\n\nRequired" + }, + "submissionId": { + "type": "string", + "description": "A unique identifier to distinguish completions for different submissions with the same change ID.\nTypically a random UUID. Applications are expected to use a different UUID for each retry of a submission\nwith the same change ID.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nIf omitted, the participant or the committer may set a value of their choice.\n\nOptional" + }, + "commands": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.ReassignmentCommand" + }, + "description": "Individual elements of this reassignment. Must be non-empty.\n\nRequired: must be non-empty" + } + } + }, + "com.daml.ledger.api.v2.ReassignmentEvent": { + "type": "object", + "properties": { + "unassigned": { + "$ref": "#/definitions/com.daml.ledger.api.v2.UnassignedEvent" + }, + "assigned": { + "$ref": "#/definitions/com.daml.ledger.api.v2.AssignedEvent" + } + } + }, + "com.daml.ledger.api.v2.Record": { + "type": "object", + "properties": { + "recordId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "Omitted from the transaction stream when verbose streaming is not enabled.\nOptional when submitting commands." + }, + "fields": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.RecordField" + }, + "title": "The nested values of the record.\nRequired" + } + }, + "description": "Contains nested values." + }, + "com.daml.ledger.api.v2.RecordField": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "- 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.\n- 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.\n\nMust be a valid NameString", + "title": "When reading a transaction stream, it's omitted if verbose streaming is not enabled.\nWhen submitting a command, it's optional:" + }, + "value": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "title": "A nested value of a record.\nRequired" + } + }, + "description": "A named nested value within a record." + }, + "com.daml.ledger.api.v2.SubmitAndWaitForReassignmentRequest": { + "type": "object", + "properties": { + "reassignmentCommands": { + "$ref": "#/definitions/com.daml.ledger.api.v2.ReassignmentCommands", + "description": "The reassignment commands to be submitted.\n\nRequired" + }, + "eventFormat": { + "$ref": "#/definitions/com.daml.ledger.api.v2.EventFormat", + "description": "If no event_format provided, the result will contain no events.\nThe events in the result, will take shape TRANSACTION_SHAPE_ACS_DELTA.\n\nOptional" + } + }, + "description": "This reassignment is executed as a single atomic update." + }, + "com.daml.ledger.api.v2.SubmitAndWaitForReassignmentResponse": { + "type": "object", + "properties": { + "reassignment": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Reassignment", + "description": "The reassignment that resulted from the submitted reassignment command.\nThe reassignment might contain no events (request conditions result in filtering out all of them).\n\nRequired" + } + } + }, + "com.daml.ledger.api.v2.SubmitAndWaitForTransactionRequest": { + "type": "object", + "properties": { + "commands": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Commands", + "description": "The commands to be submitted.\n\nRequired" + }, + "transactionFormat": { + "$ref": "#/definitions/com.daml.ledger.api.v2.TransactionFormat", + "description": "If no ``transaction_format`` is provided, a default will be used where ``transaction_shape`` is set to\nTRANSACTION_SHAPE_ACS_DELTA, ``event_format`` is defined with ``filters_by_party`` containing wildcard-template\nfilter for all original ``act_as`` and ``read_as`` parties and the ``verbose`` flag is set.\n\nOptional" + } + }, + "description": "These commands are executed as a single atomic transaction." + }, + "com.daml.ledger.api.v2.SubmitAndWaitForTransactionResponse": { + "type": "object", + "properties": { + "transaction": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Transaction", + "description": "The transaction that resulted from the submitted command.\nThe transaction might contain no events (request conditions result in filtering out all of them).\n\nRequired" + } + } + }, + "com.daml.ledger.api.v2.SubmitAndWaitResponse": { + "type": "object", + "properties": { + "updateId": { + "type": "string", + "description": "The id of the transaction that resulted from the submitted command.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "completionOffset": { + "type": "string", + "format": "int64", + "description": "The details of the offset field are described in ``community/ledger-api/README.md``.\n\nRequired" + } + } + }, + "com.daml.ledger.api.v2.TemplateFilter": { + "type": "object", + "properties": { + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "A template for which the payload should be included in the response.\nThe ``template_id`` needs to be valid: corresponding template should be defined in\none of the available packages at the time of the query.\nBoth package-name and package-id reference formats for the identifier are supported.\nNote: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4.\n\nRequired" + }, + "includeCreatedEventBlob": { + "type": "boolean", + "description": "Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``.\nUse this to access the contract event payload in your API client\nfor submitting it as a disclosed contract with future commands.\n\nOptional" + } + }, + "description": "This filter matches contracts of a specific template." + }, + "com.daml.ledger.api.v2.TextMap": { + "type": "object", + "properties": { + "entries": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.TextMap.Entry" + } + } + } + }, + "com.daml.ledger.api.v2.TextMap.Entry": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "value": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value" + } + } + }, + "com.daml.ledger.api.v2.TraceContext": { + "type": "object", + "properties": { + "traceparent": { + "type": "string", + "description": "Optional", + "title": "https://www.w3.org/TR/trace-context/" + }, + "tracestate": { + "type": "string", + "title": "Optional" + } + } + }, + "com.daml.ledger.api.v2.Transaction": { + "type": "object", + "properties": { + "updateId": { + "type": "string", + "description": "Assigned by the server. Useful for correlating logs.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "commandId": { + "type": "string", + "description": "The ID of the command which resulted in this transaction. Missing for everyone except the submitting party.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nOptional" + }, + "workflowId": { + "type": "string", + "description": "The workflow ID used in command submission.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nOptional" + }, + "effectiveAt": { + "type": "string", + "format": "date-time", + "description": "Ledger effective time.\n\nRequired" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/com.daml.ledger.api.v2.Event" + }, + "description": "- ``CreatedEvent`` or ``ArchivedEvent`` in case of ACS_DELTA transaction shape\n- ``CreatedEvent`` or ``ExercisedEvent`` in case of LEDGER_EFFECTS transaction shape\n\nRequired: must be non-empty", + "title": "The collection of events.\nContains:" + }, + "offset": { + "type": "string", + "format": "int64", + "description": "The absolute offset. The details of this field are described in ``community/ledger-api/README.md``.\nIt is a valid absolute offset (positive integer).\n\nRequired" + }, + "synchronizerId": { + "type": "string", + "description": "A valid synchronizer id.\nIdentifies the synchronizer that synchronized the transaction.\n\nRequired" + }, + "traceContext": { + "$ref": "#/definitions/com.daml.ledger.api.v2.TraceContext", + "description": "The trace context transported in this message corresponds to the trace context supplied\nby the client application in a HTTP2 header of the original command submission.\nWe typically use a header to transfer this type of information. Here we use message\nbody, because it is used in gRPC streams which do not support per message headers.\nThis field will be populated with the trace context contained in the original submission.\nIf that was not provided, a unique ledger-api-server generated trace context will be used\ninstead.\n\nOptional", + "title": "Ledger API trace context" + }, + "recordTime": { + "type": "string", + "format": "date-time", + "description": "The time at which the transaction was recorded. The record time refers to the synchronizer\nwhich synchronized the transaction.\n\nRequired" + }, + "externalTransactionHash": { + "type": "string", + "format": "byte", + "description": "For transaction externally signed, contains the external transaction hash\nsigned by the external party. Can be used to correlate an external submission with a committed transaction.\n\nOptional: can be empty" + }, + "paidTrafficCost": { + "type": "string", + "format": "int64", + "description": "The traffic cost that this participant node paid for the confirmation\nrequest for this transaction.\n\nNot set for transactions that were\n- initiated by another participant\n- initiated offline via the repair service\n- processed before the participant started serving traffic cost on the Ledger API\n- returned as part of a query filtering for a non submitting party\n\nOptional" + } + }, + "description": "Filtered view of an on-ledger transaction's create and archive events." + }, + "com.daml.ledger.api.v2.TransactionFormat": { + "type": "object", + "properties": { + "eventFormat": { + "$ref": "#/definitions/com.daml.ledger.api.v2.EventFormat", + "title": "Required" + }, + "transactionShape": { + "$ref": "#/definitions/com.daml.ledger.api.v2.TransactionShape", + "description": "What transaction shape to use for interpreting the filters of the event format.\n\nRequired" + } + }, + "description": "A format that specifies what events to include in Daml transactions\nand what data to compute and include for them." + }, + "com.daml.ledger.api.v2.TransactionShape": { + "type": "string", + "enum": [ + "TRANSACTION_SHAPE_UNSPECIFIED", + "TRANSACTION_SHAPE_ACS_DELTA", + "TRANSACTION_SHAPE_LEDGER_EFFECTS" + ], + "default": "TRANSACTION_SHAPE_UNSPECIFIED", + "description": "Event shape for Transactions.\nShapes are exclusive and only one of them can be defined in queries.\n\n - TRANSACTION_SHAPE_UNSPECIFIED: Following official proto3 convention, not intended for actual use.\n - TRANSACTION_SHAPE_ACS_DELTA: Transaction shape that is sufficient to maintain an accurate ACS view.\nThe field witness_parties in events are populated as stakeholders, transaction filter will apply accordingly.\nThis translates to create and archive events.\n - TRANSACTION_SHAPE_LEDGER_EFFECTS: Transaction shape that allows maintaining an ACS and also conveys detailed information about\nall exercises.\nThe field witness_parties in events are populated as cumulative informees, transaction filter will apply accordingly.\nThis translates to create, consuming exercise and non-consuming exercise." + }, + "com.daml.ledger.api.v2.UnassignCommand": { + "type": "object", + "properties": { + "contractId": { + "type": "string", + "description": "The ID of the contract the client wants to unassign.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "source": { + "type": "string", + "description": "Required", + "title": "The ID of the source synchronizer\nMust be a valid synchronizer id" + }, + "target": { + "type": "string", + "description": "Required", + "title": "The ID of the target synchronizer\nMust be a valid synchronizer id" + } + }, + "title": "Unassign a contract" + }, + "com.daml.ledger.api.v2.UnassignedEvent": { + "type": "object", + "properties": { + "reassignmentId": { + "type": "string", + "description": "The ID of the unassignment. This needs to be used as an input for a assign ReassignmentCommand.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "contractId": { + "type": "string", + "description": "The ID of the reassigned contract.\nMust be a valid LedgerString (as described in ``value.proto``).\n\nRequired" + }, + "templateId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "The template of the reassigned contract.\nThe identifier uses the package-id reference format.\n\nRequired" + }, + "source": { + "type": "string", + "description": "Required", + "title": "The ID of the source synchronizer\nMust be a valid synchronizer id" + }, + "target": { + "type": "string", + "description": "Required", + "title": "The ID of the target synchronizer\nMust be a valid synchronizer id" + }, + "submitter": { + "type": "string", + "description": "Party on whose behalf the unassign command was executed.\nEmpty if the unassignment happened offline via the repair service.\nMust be a valid PartyIdString (as described in ``value.proto``).\n\nOptional" + }, + "reassignmentCounter": { + "type": "string", + "format": "uint64", + "description": "Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases\nwith each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter\nequals zero.\n\nRequired" + }, + "assignmentExclusivity": { + "type": "string", + "format": "date-time", + "description": "Assignment exclusivity\nBefore this time (measured on the target synchronizer), only the submitter of the unassignment can initiate the assignment\nDefined for reassigning participants.\n\nOptional" + }, + "witnessParties": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The parties that are notified of this event.\n\nRequired: must be non-empty" + }, + "packageName": { + "type": "string", + "description": "The package name of the contract.\n\nRequired" + }, + "offset": { + "type": "string", + "format": "int64", + "description": "Required", + "title": "The offset of origin.\nOffsets are managed by the participant nodes.\nReassignments can thus NOT be assumed to have the same offsets on different participant nodes.\nMust be a valid absolute offset (positive integer)" + }, + "nodeId": { + "type": "integer", + "format": "int32", + "description": "Required", + "title": "The position of this event in the originating reassignment.\nNode IDs are not necessarily equal across participants,\nas these may see different projections/parts of reassignments.\nMust be valid node ID (non-negative integer)" + } + }, + "title": "Records that a contract has been unassigned, and it becomes unusable on the source synchronizer" + }, + "com.daml.ledger.api.v2.Value": { + "type": "object", + "properties": { + "unit": { + "type": "object", + "properties": {}, + "description": "This value is used for example for choices that don't take any arguments." + }, + "bool": { + "type": "boolean", + "description": "True or false." + }, + "int64": { + "type": "string", + "format": "int64" + }, + "date": { + "type": "integer", + "format": "int32", + "title": "Days since the unix epoch. Can go backwards. Limited from\n0001-01-01 to 9999-12-31, also to be compatible with\nhttps://www.ietf.org/rfc/rfc3339.txt" + }, + "timestamp": { + "type": "string", + "format": "int64", + "title": "Microseconds since the UNIX epoch. Can go backwards. Fixed\nsince the vast majority of values will be greater than\n2^28, since currently the number of microseconds since the\nepoch is greater than that. Range: 0001-01-01T00:00:00Z to\n9999-12-31T23:59:59.999999Z, so that we can convert to/from\nhttps://www.ietf.org/rfc/rfc3339.txt" + }, + "numeric": { + "type": "string", + "description": ".. code-block:: none\n\n [+-]?\\d{1,38}(.\\d{0,37})?\n\nand should be representable by a Numeric without loss of precision.", + "title": "A Numeric, that is a decimal value with precision 38 (at most 38 significant digits) and a\nscale between 0 and 37 (significant digits on the right of the decimal point).\nThe field has to match the regex" + }, + "party": { + "type": "string", + "description": "An agent operating on the ledger.\nMust be a valid PartyIdString." + }, + "text": { + "type": "string", + "description": "A string." + }, + "contractId": { + "type": "string", + "description": "Identifier of an on-ledger contract. Commands which reference an unknown or already archived contract ID will fail.\nMust be a valid LedgerString." + }, + "optional": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Optional", + "title": "The Optional type, None or Some" + }, + "list": { + "$ref": "#/definitions/com.daml.ledger.api.v2.List", + "description": "Represents a homogeneous list of values." + }, + "textMap": { + "$ref": "#/definitions/com.daml.ledger.api.v2.TextMap", + "title": "The TextMap type" + }, + "genMap": { + "$ref": "#/definitions/com.daml.ledger.api.v2.GenMap", + "title": "The GenMap type" + }, + "record": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Record" + }, + "variant": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Variant" + }, + "enum": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Enum", + "title": "The Enum type" + } + }, + "description": "Encodes values that the ledger accepts as command arguments and emits as contract arguments.\n\nThe values encoding use different classes of non-empty strings as identifiers. Those classes are\ndefined as follows:\n\n- NameStrings are strings with length \u003c= 1000 that match the regexp ``[A-Za-z\\$_][A-Za-z0-9\\$_]*``.\n- PackageIdStrings are strings with length \u003c= 64 that match the regexp ``[A-Za-z0-9\\-_ ]+``.\n- PartyIdStrings are strings with length \u003c= 255 that match the regexp ``[A-Za-z0-9:\\-_ ]+``.\n- ParticipantIdStrings are strings with length \u003c= 255 that match the regexp ``[A-Za-z0-9:\\-_ ]+``.\n- LedgerStrings are strings with length \u003c= 255 that match the regexp ``[A-Za-z0-9#:\\-_/ ]+``.\n- UserIdStrings are strings with length \u003c= 128 that match the regexp ``[a-zA-Z0-9@^$.!`\\-#+'~_|:]+``." + }, + "com.daml.ledger.api.v2.Variant": { + "type": "object", + "properties": { + "variantId": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Identifier", + "description": "Omitted from the transaction stream when verbose streaming is not enabled.\nOptional when submitting commands." + }, + "constructor": { + "type": "string", + "title": "Determines which of the Variant's alternatives is encoded in this message.\nMust be a valid NameString.\nRequired" + }, + "value": { + "$ref": "#/definitions/com.daml.ledger.api.v2.Value", + "title": "The value encoded within the Variant.\nRequired" + } + }, + "description": "A value with alternative representations." + }, + "com.daml.ledger.api.v2.WildcardFilter": { + "type": "object", + "properties": { + "includeCreatedEventBlob": { + "type": "boolean", + "description": "Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``.\nUse this to access the contract create event payload in your API client\nfor submitting it as a disclosed contract with future commands.\n\nOptional" + } + }, + "description": "This filter matches all templates." + }, + "google.protobuf.Any": { + "type": "object", + "properties": { + "@type": { + "type": "string", + "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics." + } + }, + "additionalProperties": {}, + "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(\u0026foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := \u0026pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := \u0026pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": \u003cstring\u003e,\n \"lastName\": \u003cstring\u003e\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" + }, + "google.rpc.Status": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "description": "The status code, which should be an enum value of\n[google.rpc.Code][google.rpc.Code]." + }, + "message": { + "type": "string", + "description": "A developer-facing error message, which should be in English. Any\nuser-facing error message should be localized and sent in the\n[google.rpc.Status.details][google.rpc.Status.details] field, or localized\nby the client." + }, + "details": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/google.protobuf.Any" + }, + "description": "A list of messages that carry the error details. There is a common set of\nmessage types for APIs to use." + } + }, + "description": "The `Status` type defines a logical error model that is suitable for\ndifferent programming environments, including REST APIs and RPC APIs. It is\nused by [gRPC](https://github.com/grpc). Each `Status` message contains\nthree pieces of data: error code, error message, and error details.\n\nYou can find out more about this error model and how to work with it in the\n[API Design Guide](https://cloud.google.com/apis/design/errors)." + } + } +} diff --git a/http-annotations-evidence/README.md b/http-annotations-evidence/README.md new file mode 100644 index 0000000000..ea9e2da7f8 --- /dev/null +++ b/http-annotations-evidence/README.md @@ -0,0 +1,76 @@ +# HTTP annotations evidence + +Burden-of-evidence artefacts for the PR that adds `google.api.http` +annotations across **every** HTTP-exposed RPC of the JSON Ledger API +(extending the single-service `command_service.proto` experiment to +full coverage). + +**Internal to the Peaceful Studio fork.** Delete this directory before +submitting any upstream PR to `digital-asset/canton` — these files are +review aids, not part of the contribution. + +## Contents + +| Path | Purpose | +|---|---| +| [`openapi-3.0/openapi.yaml`](openapi-3.0/openapi.yaml) | OpenAPI **3.0.3** YAML generated from the annotated protos via `buf.build/community/google-gnostic-openapi:v0.7.0`. Directly comparable to the existing `community/ledger/ledger-json-api/src/test/resources/json-api-docs/openapi.yaml` (also 3.0.3). | +| [`openapi-3.0/buf.gen.yaml`](openapi-3.0/buf.gen.yaml) | The exact `buf generate` config. | +| [`swagger-2.0/canton-ledger-api.swagger.yaml`](swagger-2.0/canton-ledger-api.swagger.yaml) | Swagger **2.0** YAML generated via `buf.build/grpc-ecosystem/openapiv2:v2.28.0` — same plugin as the upstream CommandService experiment, this time merged across every annotated service. | +| [`swagger-2.0/buf.gen.yaml`](swagger-2.0/buf.gen.yaml) | The exact `buf generate` config. | +| [`coverage-comparison/`](coverage-comparison/) | Sorted path inventories and the diff between the JSON API spec and the proto-derived spec after path-parameter name normalization. | +| [`reproduce.sh`](reproduce.sh) | One-shot script regenerating every artefact in this directory. | + +## Coverage summary + +| Metric | JSON API yaml | Proto-derived yaml | +|---|---|---| +| Distinct paths | 51 | 45 | +| Schemas | 199 (n/a in jsonapi yaml — uses inline) | 199 named, package-qualified | +| `Empty1`..`Empty10` numbered duplicate schemas | present | **0** | +| `additionalProperties: true` untyped maps | 0 | 1 (legitimate `google.protobuf.Any`) | + +After normalizing path-parameter names (`{user_id}` ↔ `{user-id}`, +`{identity_provider_id}` ↔ `{idp-id}`, `{parties}` ↔ `{party}`, etc.): + +- **9 paths only in the JSON API yaml** — all deliberately skipped on the + proto side, listed in [`coverage-comparison/jsonapi-only.txt`](coverage-comparison/jsonapi-only.txt): + - `/v2/authenticated-user` — custom JSON-only endpoint, no gRPC backing. + - 8 deprecated legacy aliases targeted for 3.5.0 removal + (`/v2/commands/submit-and-wait-for-transaction-tree`, + `/v2/package-vetting`, `/v2/updates/flats`, `/v2/updates/trees`, + `/v2/updates/transaction-by-id`, `/v2/updates/transaction-by-offset`, + `/v2/updates/transaction-tree-by-id/{update-id}`, + `/v2/updates/transaction-tree-by-offset/{offset}`). +- **0 paths only in the proto-derived yaml** — every annotated RPC has a + matching JSON API route. + +## Known route deviations from tapir + +A single intentional change: `StateService.GetActiveContractsPage` is +annotated as **POST** (not GET, like tapir does today). +`grpc-ecosystem/openapiv2` rejects GET-with-body +(`must not set request body when http method is GET`), and the request +carries a required `EventFormat` message that does not flatten cleanly +to query parameters. POST is the canonical mapping for a non-trivial +body. See the `experiment: switch GetActiveContractsPage to POST` commit +for context. + +## How to reproduce + +```bash +# from the repo root, on this branch: +bash http-annotations-evidence/reproduce.sh +``` + +The script: + +1. fetches `google/api/annotations.proto`, `google/api/http.proto`, and + `google/rpc/status.proto` into the workspace location that + `buf.work.yaml` already references + (`community/lib/google-common-protos-scala/target/protobuf_external/`); +2. runs `buf generate` twice (once per format) targeting every annotated + v2 service proto; +3. regenerates `coverage-comparison/*.txt` from both yamls. + +Re-running the script over a clean checkout of this branch must produce +byte-identical files to those committed here. diff --git a/http-annotations-evidence/coverage-comparison/jsonapi-only.txt b/http-annotations-evidence/coverage-comparison/jsonapi-only.txt new file mode 100644 index 0000000000..31d4a735b4 --- /dev/null +++ b/http-annotations-evidence/coverage-comparison/jsonapi-only.txt @@ -0,0 +1,9 @@ + /v2/authenticated-user + /v2/commands/submit-and-wait-for-transaction-tree + /v2/package-vetting + /v2/updates/flats + /v2/updates/transaction-by-id + /v2/updates/transaction-by-offset + /v2/updates/transaction-tree-by-id/{update-id} + /v2/updates/transaction-tree-by-offset/{offset} + /v2/updates/trees diff --git a/http-annotations-evidence/coverage-comparison/paths-jsonapi.txt b/http-annotations-evidence/coverage-comparison/paths-jsonapi.txt new file mode 100644 index 0000000000..b0cfa31455 --- /dev/null +++ b/http-annotations-evidence/coverage-comparison/paths-jsonapi.txt @@ -0,0 +1,51 @@ + /v2/authenticated-user + /v2/commands/async/submit + /v2/commands/async/submit-reassignment + /v2/commands/completions + /v2/commands/submit-and-wait + /v2/commands/submit-and-wait-for-reassignment + /v2/commands/submit-and-wait-for-transaction + /v2/commands/submit-and-wait-for-transaction-tree + /v2/contracts/contract-by-id + /v2/dars + /v2/dars/validate + /v2/events/events-by-contract-id + /v2/idps + /v2/idps/{idp-id} + /v2/interactive-submission/execute + /v2/interactive-submission/executeAndWait + /v2/interactive-submission/executeAndWaitForTransaction + /v2/interactive-submission/preferred-package-version + /v2/interactive-submission/preferred-packages + /v2/interactive-submission/prepare + /v2/package-vetting + /v2/package-vetting/list + /v2/package-vetting/update + /v2/packages + /v2/packages/{package-id} + /v2/packages/{package-id}/status + /v2/parties + /v2/parties/{party} + /v2/parties/external/allocate + /v2/parties/external/generate-topology + /v2/parties/participant-id + /v2/state/active-contracts + /v2/state/active-contracts-page + /v2/state/connected-synchronizers + /v2/state/latest-pruned-offsets + /v2/state/ledger-end + /v2/updates + /v2/updates/flats + /v2/updates/get-updates-page + /v2/updates/transaction-by-id + /v2/updates/transaction-by-offset + /v2/updates/transaction-tree-by-id/{update-id} + /v2/updates/transaction-tree-by-offset/{offset} + /v2/updates/trees + /v2/updates/update-by-id + /v2/updates/update-by-offset + /v2/users + /v2/users/{user-id} + /v2/users/{user-id}/identity-provider-id + /v2/users/{user-id}/rights + /v2/version diff --git a/http-annotations-evidence/coverage-comparison/paths-proto-normalized.txt b/http-annotations-evidence/coverage-comparison/paths-proto-normalized.txt new file mode 100644 index 0000000000..863669a224 --- /dev/null +++ b/http-annotations-evidence/coverage-comparison/paths-proto-normalized.txt @@ -0,0 +1,42 @@ + /v2/commands/async/submit + /v2/commands/async/submit-reassignment + /v2/commands/completions + /v2/commands/submit-and-wait + /v2/commands/submit-and-wait-for-reassignment + /v2/commands/submit-and-wait-for-transaction + /v2/contracts/contract-by-id + /v2/dars + /v2/dars/validate + /v2/events/events-by-contract-id + /v2/idps + /v2/idps/{idp-id} + /v2/interactive-submission/execute + /v2/interactive-submission/executeAndWait + /v2/interactive-submission/executeAndWaitForTransaction + /v2/interactive-submission/preferred-package-version + /v2/interactive-submission/preferred-packages + /v2/interactive-submission/prepare + /v2/package-vetting/list + /v2/package-vetting/update + /v2/packages + /v2/packages/{package-id} + /v2/packages/{package-id}/status + /v2/parties + /v2/parties/{party} + /v2/parties/external/allocate + /v2/parties/external/generate-topology + /v2/parties/participant-id + /v2/state/active-contracts + /v2/state/active-contracts-page + /v2/state/connected-synchronizers + /v2/state/latest-pruned-offsets + /v2/state/ledger-end + /v2/updates + /v2/updates/get-updates-page + /v2/updates/update-by-id + /v2/updates/update-by-offset + /v2/users + /v2/users/{user-id} + /v2/users/{user-id}/identity-provider-id + /v2/users/{user-id}/rights + /v2/version diff --git a/http-annotations-evidence/coverage-comparison/paths-proto.txt b/http-annotations-evidence/coverage-comparison/paths-proto.txt new file mode 100644 index 0000000000..3e3d619a09 --- /dev/null +++ b/http-annotations-evidence/coverage-comparison/paths-proto.txt @@ -0,0 +1,45 @@ +/v2/commands/async/submit +/v2/commands/async/submit-reassignment +/v2/commands/completions +/v2/commands/submit-and-wait +/v2/commands/submit-and-wait-for-reassignment +/v2/commands/submit-and-wait-for-transaction +/v2/contracts/contract-by-id +/v2/dars +/v2/dars/validate +/v2/events/events-by-contract-id +/v2/idps +/v2/idps/{identity_provider_config.identity_provider_id} +/v2/idps/{identity_provider_id} +/v2/interactive-submission/execute +/v2/interactive-submission/executeAndWait +/v2/interactive-submission/executeAndWaitForTransaction +/v2/interactive-submission/preferred-package-version +/v2/interactive-submission/preferred-packages +/v2/interactive-submission/prepare +/v2/package-vetting/list +/v2/package-vetting/update +/v2/packages +/v2/packages/{package_id} +/v2/packages/{package_id}/status +/v2/parties +/v2/parties/{parties} +/v2/parties/{party_details.party} +/v2/parties/external/allocate +/v2/parties/external/generate-topology +/v2/parties/participant-id +/v2/state/active-contracts +/v2/state/active-contracts-page +/v2/state/connected-synchronizers +/v2/state/latest-pruned-offsets +/v2/state/ledger-end +/v2/updates +/v2/updates/get-updates-page +/v2/updates/update-by-id +/v2/updates/update-by-offset +/v2/users +/v2/users/{user_id} +/v2/users/{user_id}/identity-provider-id +/v2/users/{user_id}/rights +/v2/users/{user.id} +/v2/version diff --git a/http-annotations-evidence/coverage-comparison/proto-only.txt b/http-annotations-evidence/coverage-comparison/proto-only.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/http-annotations-evidence/openapi-3.0/buf.gen.yaml b/http-annotations-evidence/openapi-3.0/buf.gen.yaml new file mode 100644 index 0000000000..0877764c2f --- /dev/null +++ b/http-annotations-evidence/openapi-3.0/buf.gen.yaml @@ -0,0 +1,8 @@ +version: v2 +plugins: + - remote: buf.build/community/google-gnostic-openapi:v0.7.0 + out: gen + opt: + - title=Canton Ledger API (proto-derived) + - version=v2 + - naming=proto diff --git a/http-annotations-evidence/openapi-3.0/openapi.yaml b/http-annotations-evidence/openapi-3.0/openapi.yaml new file mode 100644 index 0000000000..475447b46f --- /dev/null +++ b/http-annotations-evidence/openapi-3.0/openapi.yaml @@ -0,0 +1,7164 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Canton Ledger API (proto-derived) + version: v2 +paths: + /v2/commands/async/submit: + post: + tags: + - CommandSubmissionService + description: Submit a single composite command. + operationId: CommandSubmissionService_Submit + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Commands' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/commands/async/submit-reassignment: + post: + tags: + - CommandSubmissionService + description: Submit a single reassignment. + operationId: CommandSubmissionService_SubmitReassignment + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitReassignmentRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitReassignmentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/commands/completions: + post: + tags: + - CommandCompletionService + description: Subscribe to command completion events. + operationId: CommandCompletionService_CompletionStream + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CompletionStreamRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CompletionStreamResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/commands/submit-and-wait: + post: + tags: + - CommandService + description: |- + Submits a single composite command and waits for its result. + Propagates the gRPC error of failed submissions including Daml interpretation errors. + operationId: CommandService_SubmitAndWait + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Commands' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitAndWaitResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/commands/submit-and-wait-for-reassignment: + post: + tags: + - CommandService + description: |- + Submits a single composite reassignment command, waits for its result, and returns the reassignment. + Propagates the gRPC error of failed submission. + operationId: CommandService_SubmitAndWaitForReassignment + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitAndWaitForReassignmentRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitAndWaitForReassignmentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/commands/submit-and-wait-for-transaction: + post: + tags: + - CommandService + description: |- + Submits a single composite command, waits for its result, and returns the transaction. + Propagates the gRPC error of failed submissions including Daml interpretation errors. + operationId: CommandService_SubmitAndWaitForTransaction + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitAndWaitForTransactionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitAndWaitForTransactionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/contracts/contract-by-id: + post: + tags: + - ContractService + description: |- + Looking up contract data by contract ID. + This endpoint is experimental / alpha, therefore no backwards compatibility is guaranteed. + This endpoint must not be used to look up contracts which entered the participant via party replication + or repair service. + If there is no contract exist with the contract ID, or there is no intersection with the querying_parties, + an CONTRACT_PAYLOAD_NOT_FOUND error will be raised. + operationId: ContractService_GetContract + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetContractRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetContractResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/dars: + post: + tags: + - PackageManagementService + description: |- + Upload a DAR file to the participant. + + If vetting is enabled in the request, the DAR is checked for upgrade compatibility + with the set of the already vetted packages on the target vetting synchronizer + See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer. + operationId: PackageManagementService_UploadDarFile + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UploadDarFileRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UploadDarFileResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/dars/validate: + post: + tags: + - PackageManagementService + description: |- + Validates the DAR and checks the upgrade compatibility of the DAR's packages + with the set of the already vetted packages on the target vetting synchronizer. + See ValidateDarFileRequest for details regarding the target vetting synchronizer. + + The operation has no effect on the state of the participant or the Canton ledger: + the DAR payload and its packages are not persisted neither are the packages vetted. + operationId: PackageManagementService_ValidateDarFile + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ValidateDarFileRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ValidateDarFileResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/events/events-by-contract-id: + post: + tags: + - EventQueryService + description: |- + Get the create and the consuming exercise event for the contract with the provided ID. + No events will be returned for contracts that have been pruned because they + have already been archived before the latest pruning offset. + If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. + operationId: EventQueryService_GetEventsByContractId + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetEventsByContractIdRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetEventsByContractIdResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/idps: + get: + tags: + - IdentityProviderConfigService + description: List all existing identity provider configurations. + operationId: IdentityProviderConfigService_ListIdentityProviderConfigs + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListIdentityProviderConfigsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - IdentityProviderConfigService + description: |- + Create a new identity provider configuration. + The request will fail if the maximum allowed number of separate configurations is reached. + operationId: IdentityProviderConfigService_CreateIdentityProviderConfig + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateIdentityProviderConfigRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CreateIdentityProviderConfigResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/idps/{identity_provider_config.identity_provider_id}: + patch: + tags: + - IdentityProviderConfigService + description: |- + Update selected modifiable attribute of an identity provider config resource described + by the ``IdentityProviderConfig`` message. + operationId: IdentityProviderConfigService_UpdateIdentityProviderConfig + parameters: + - name: identity_provider_config.identity_provider_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateIdentityProviderConfigRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateIdentityProviderConfigResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/idps/{identity_provider_id}: + get: + tags: + - IdentityProviderConfigService + description: Get the identity provider configuration data by id. + operationId: IdentityProviderConfigService_GetIdentityProviderConfig + parameters: + - name: identity_provider_id + in: path + description: Required + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetIdentityProviderConfigResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + delete: + tags: + - IdentityProviderConfigService + description: Delete an existing identity provider configuration. + operationId: IdentityProviderConfigService_DeleteIdentityProviderConfig + parameters: + - name: identity_provider_id + in: path + description: |- + The identity provider config to delete. + + Required + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteIdentityProviderConfigResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/interactive-submission/execute: + post: + tags: + - InteractiveSubmissionService + description: |- + Execute a prepared submission _asynchronously_ on the ledger. + Requires a signature of the transaction from the submitting external party. + operationId: InteractiveSubmissionService_ExecuteSubmission + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ExecuteSubmissionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ExecuteSubmissionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/interactive-submission/executeAndWait: + post: + tags: + - InteractiveSubmissionService + description: |- + Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction + IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. + A malicious node could make a successfully committed request appeared failed and vice versa + operationId: InteractiveSubmissionService_ExecuteSubmissionAndWait + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ExecuteSubmissionAndWaitRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ExecuteSubmissionAndWaitResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/interactive-submission/executeAndWaitForTransaction: + post: + tags: + - InteractiveSubmissionService + description: |- + Similar to ExecuteSubmissionAndWait but additionally returns the transaction + IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. + A malicious node could make a successfully committed request appear as failed and vice versa + operationId: InteractiveSubmissionService_ExecuteSubmissionAndWaitForTransaction + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ExecuteSubmissionAndWaitForTransactionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ExecuteSubmissionAndWaitForTransactionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/interactive-submission/preferred-package-version: + get: + tags: + - InteractiveSubmissionService + description: |- + A preferred package is the highest-versioned package for a provided package-name + that is vetted by all the participants hosting the provided parties. + + Ledger API clients should use this endpoint for constructing command submissions + that are compatible with the provided preferred package, by making informed decisions on: + - which are the compatible packages that can be used to create contracts + - which contract or exercise choice argument version can be used in the command + - which choices can be executed on a template or interface of a contract + + Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. + + Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 + operationId: InteractiveSubmissionService_GetPreferredPackageVersion + parameters: + - name: parties + in: query + description: |- + The parties whose participants' vetting state should be considered when resolving the preferred package. + + Required: must be non-empty + schema: + type: array + items: + type: string + - name: package_name + in: query + description: |- + The package-name for which the preferred package should be resolved. + + Required + schema: + type: string + - name: synchronizer_id + in: query + description: |- + The synchronizer whose vetting state should be used for resolving this query. + If not specified, the vetting states of all synchronizers to which the participant is connected are used. + + Optional + schema: + type: string + - name: vetting_valid_at + in: query + description: |- + The timestamp at which the package vetting validity should be computed + on the latest topology snapshot as seen by the participant. + If not provided, the participant's current clock time is used. + + Optional + schema: + type: string + format: date-time + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetPreferredPackageVersionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/interactive-submission/preferred-packages: + post: + tags: + - InteractiveSubmissionService + description: |- + Compute the preferred packages for the vetting requirements in the request. + A preferred package is the highest-versioned package for a provided package-name + that is vetted by all the participants hosting the provided parties. + + Ledger API clients should use this endpoint for constructing command submissions + that are compatible with the provided preferred packages, by making informed decisions on: + - which are the compatible packages that can be used to create contracts + - which contract or exercise choice argument version can be used in the command + - which choices can be executed on a template or interface of a contract + + If the package preferences could not be computed due to no selection satisfying the requirements, + a `FAILED_PRECONDITION` error will be returned. + + Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. + + Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases + operationId: InteractiveSubmissionService_GetPreferredPackages + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetPreferredPackagesRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetPreferredPackagesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/interactive-submission/prepare: + post: + tags: + - InteractiveSubmissionService + description: Requires `readAs` scope for the submitting party when LAPI User authorization is enabled + operationId: InteractiveSubmissionService_PrepareSubmission + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PrepareSubmissionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PrepareSubmissionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/package-vetting/list: + post: + tags: + - PackageService + description: |- + Lists which participant node vetted what packages on which synchronizer. + Can be called by any authenticated user. + operationId: PackageService_ListVettedPackages + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ListVettedPackagesRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListVettedPackagesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/package-vetting/update: + post: + tags: + - PackageManagementService + description: Update the vetted packages of this participant + operationId: PackageManagementService_UpdateVettedPackages + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateVettedPackagesRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateVettedPackagesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/packages: + get: + tags: + - PackageService + description: Returns the identifiers of all supported packages. + operationId: PackageService_ListPackages + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListPackagesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/packages/{package_id}: + get: + tags: + - PackageService + description: Returns the contents of a single package. + operationId: PackageService_GetPackage + parameters: + - name: package_id + in: path + description: |- + The ID of the requested package. + Must be a valid PackageIdString (as described in ``value.proto``). + + Required + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetPackageResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/packages/{package_id}/status: + get: + tags: + - PackageService + description: Returns the status of a single package. + operationId: PackageService_GetPackageStatus + parameters: + - name: package_id + in: path + description: |- + The ID of the requested package. + Must be a valid PackageIdString (as described in ``value.proto``). + + Required + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetPackageStatusResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/parties: + get: + tags: + - PartyManagementService + description: |- + List the parties known by the participant. + The list returned contains parties whose ledger access is facilitated by + the participant and the ones maintained elsewhere. + operationId: PartyManagementService_ListKnownParties + parameters: + - name: page_token + in: query + description: |- + Pagination token to determine the specific page to fetch. Using the token guarantees that parties on a subsequent + page are all lexically greater than the last party on a previous page. Server does not store intermediate results + between calls chained by a series of page tokens. As a consequence, if new parties are being added and a page is + requested twice using the same token, more parties can be returned on the second call. + Leave empty to fetch the first page. + + Optional + schema: + type: string + - name: page_size + in: query + description: |- + Maximum number of results to be returned by the server. The server will return no more than that many results, + but it might return fewer. If the page_size is 0, the server will decide the number of results to be returned. + If the page_size exceeds the maximum supported by the server, an error will be returned. To obtain the server's + maximum consult the PartyManagementFeature descriptor available in the VersionService. + + Optional + schema: + type: integer + format: int32 + - name: identity_provider_id + in: query + description: |- + The id of the ``Identity Provider`` whose parties should be retrieved. + If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. + + Optional + schema: + type: string + - name: filter_party + in: query + description: |- + An optional filter for the party name, searching for all party names known to this node + starting with the given prefix. This can either be just a string or extend up to the full + identifier. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListKnownPartiesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - PartyManagementService + description: |- + Allocates a new party on a ledger and adds it to the set managed by the participant. + Caller specifies a party identifier suggestion, the actual identifier + allocated might be different and is implementation specific. + Caller can specify party metadata that is stored locally on the participant. + This call may: + + - Succeed, in which case the actual allocated identifier is visible in + the response. + - Respond with a gRPC error + + daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in + the consensus layer and call rejected if the identifier is already present. + canton: completely different globally unique identifier is allocated. + Behind the scenes calls to an internal protocol are made. As that protocol + is richer than the surface protocol, the arguments take implicit values + The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, + colon, minus and underscore limited to 255 chars + operationId: PartyManagementService_AllocateParty + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AllocatePartyRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AllocatePartyResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/parties/external/allocate: + post: + tags: + - PartyManagementService + description: |- + Alpha 3.3: Endpoint to allocate a new external party on a synchronizer + + Expected to be stable in 3.5 + + The external party must be hosted (at least) on this node with either confirmation or observation permissions + It can optionally be hosted on other nodes (then called a multi-hosted party). + If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes + before the party can be used. + Decentralized namespaces are supported but must be provided fully authorized by their owners. + The individual owner namespace transactions can be submitted in the same call (fully authorized as well). + In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is + effectively allocated and ready to use, similarly to the AllocateParty behavior. + For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). + operationId: PartyManagementService_AllocateExternalParty + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AllocateExternalPartyRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AllocateExternalPartyResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/parties/external/generate-topology: + post: + tags: + - PartyManagementService + description: |- + Alpha 3.3: Convenience endpoint to generate topology transactions for external signing + + Expected to be stable in 3.5 + + You may use this endpoint to generate the common external topology transactions + which can be signed externally and uploaded as part of the allocate party process + + Note that this request will create a normal namespace using the same key for the + identity as for signing. More elaborate schemes such as multi-signature + or decentralized parties require you to construct the topology transactions yourself. + operationId: PartyManagementService_GenerateExternalPartyTopology + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GenerateExternalPartyTopologyRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GenerateExternalPartyTopologyResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/parties/participant-id: + get: + tags: + - PartyManagementService + description: |- + Return the identifier of the participant. + All horizontally scaled replicas should return the same id. + daml-on-kv-ledger: returns an identifier supplied on command line at launch time + canton: returns globally unique identifier of the participant + operationId: PartyManagementService_GetParticipantId + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetParticipantIdResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/parties/{parties}: + get: + tags: + - PartyManagementService + description: |- + Get the party details of the given parties. Only known parties will be + returned in the list. + operationId: PartyManagementService_GetParties + parameters: + - name: parties + in: path + description: |- + The stable, unique identifier of the Daml parties. + Must be valid PartyIdStrings (as described in ``value.proto``). + + Required: must be non-empty + required: true + schema: + type: array + items: + type: string + - name: identity_provider_id + in: query + description: |- + The id of the ``Identity Provider`` whose parties should be retrieved. + If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetPartiesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/parties/{party_details.party}: + patch: + tags: + - PartyManagementService + description: |- + Update selected modifiable participant-local attributes of a party details resource. + Can update the participant's local information for local parties. + operationId: PartyManagementService_UpdatePartyDetails + parameters: + - name: party_details.party + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdatePartyDetailsRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UpdatePartyDetailsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/state/active-contracts: + post: + tags: + - StateService + description: |- + Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. + Once the stream of GetActiveContractsResponses completes, + the client SHOULD begin streaming updates from the update service, + starting at the GetActiveContractsRequest.active_at_offset specified in this request. + Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. + operationId: StateService_GetActiveContracts + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetActiveContractsRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetActiveContractsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/state/active-contracts-page: + post: + tags: + - StateService + description: |- + Returns a page of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. + Once all pages are fetched by repeated calls to ``GetActiveContractsPage``, + the client SHOULD begin retrieving updates from the update service, + starting at the ``GetActiveContractsPageResponse``.``active_at_offset`` specified in this request. + Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. + operationId: StateService_GetActiveContractsPage + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetActiveContractsPageRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetActiveContractsPageResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/state/connected-synchronizers: + get: + tags: + - StateService + description: Get the list of connected synchronizers at the time of the query. + operationId: StateService_GetConnectedSynchronizers + parameters: + - name: party + in: query + description: |- + The party of interest + Must be a valid PartyIdString (as described in ``value.proto``). + If empty, all synchronizers this node is connected to will be returned + + Optional + schema: + type: string + - name: participant_id + in: query + description: |- + The id of a participant whose mapping of a party to connected synchronizers is requested. + Must be a valid participant-id retrieved through a prior call to getParticipantId. + Defaults to the participant id of the host participant. + + Optional + schema: + type: string + - name: identity_provider_id + in: query + description: |- + The ID of the identity provider configured by ``Identity Provider Config`` + If not set, it's assumed the user is managed by the default identity provider. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetConnectedSynchronizersResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/state/latest-pruned-offsets: + get: + tags: + - StateService + description: Get the latest successfully pruned ledger offsets + operationId: StateService_GetLatestPrunedOffsets + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetLatestPrunedOffsetsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/state/ledger-end: + get: + tags: + - StateService + description: |- + Get the current ledger end. + Subscriptions started with the returned offset will serve events after this RPC was called. + operationId: StateService_GetLedgerEnd + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetLedgerEndResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/updates: + post: + tags: + - UpdateService + description: |- + Read the ledger's filtered update stream for the specified contents and filters. + It returns the event types in accordance with the stream contents selected. Also the selection criteria + for individual events depends on the transaction shape chosen. + + - ACS delta: a requesting party must be a stakeholder of an event for it to be included. + - ledger effects: a requesting party must be a witness of an event for it to be included. + operationId: UpdateService_GetUpdates + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdatesRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdatesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/updates/get-updates-page: + post: + tags: + - UpdateService + description: |- + Read a page of ledger's filtered updates. It returns the event types in accordance with + the specified contents and filters. + Additionally, the selection criteria for individual events depends on the transaction shape chosen. + + - ACS delta: an event is included only if the requesting party is a stakeholder. + - ledger effects: an event is included if the requesting party is a witness. + operationId: UpdateService_GetUpdatesPage + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdatesPageRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdatesPageResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/updates/update-by-id: + post: + tags: + - UpdateService + description: |- + Lookup an update by its ID. + If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. + operationId: UpdateService_GetUpdateById + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdateByIdRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdateResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/updates/update-by-offset: + post: + tags: + - UpdateService + description: |- + Lookup an update by its offset. + If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. + operationId: UpdateService_GetUpdateByOffset + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdateByOffsetRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetUpdateResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/users: + get: + tags: + - UserManagementService + description: List all existing users. + operationId: UserManagementService_ListUsers + parameters: + - name: page_token + in: query + description: |- + Pagination token to determine the specific page to fetch. + Leave empty to fetch the first page. + + Optional + schema: + type: string + - name: page_size + in: query + description: |- + 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 + schema: + type: integer + format: int32 + - name: identity_provider_id + in: query + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListUsersResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - UserManagementService + description: Create a new user. + operationId: UserManagementService_CreateUser + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/users/{user.id}: + patch: + tags: + - UserManagementService + description: Update selected modifiable attribute of a user resource described by the ``User`` message. + operationId: UserManagementService_UpdateUser + parameters: + - name: user.id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/users/{user_id}: + get: + tags: + - UserManagementService + description: Get the user data of a specific user or the authenticated user. + operationId: UserManagementService_GetUser + parameters: + - name: user_id + in: path + description: |- + The user whose data to retrieve. + If set to empty string (the default), then the data for the authenticated user will be retrieved. + + Optional + required: true + schema: + type: string + - name: identity_provider_id + in: query + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetUserResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + delete: + tags: + - UserManagementService + description: Delete an existing user and all its rights. + operationId: UserManagementService_DeleteUser + parameters: + - name: user_id + in: path + description: |- + The user to delete. + + Required + required: true + schema: + type: string + - name: identity_provider_id + in: query + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteUserResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/users/{user_id}/identity-provider-id: + patch: + tags: + - UserManagementService + description: Update the assignment of a user from one IDP to another. + operationId: UserManagementService_UpdateUserIdentityProviderId + parameters: + - name: user_id + in: path + description: |- + User to update + + Required + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserIdentityProviderIdRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserIdentityProviderIdResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/users/{user_id}/rights: + get: + tags: + - UserManagementService + description: List the set of all rights granted to a user. + operationId: UserManagementService_ListUserRights + parameters: + - name: user_id + in: path + description: |- + 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 + required: true + schema: + type: string + - name: identity_provider_id + in: query + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListUserRightsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - UserManagementService + description: |- + Grant rights to a user. + Granting rights does not affect the resource version of the corresponding user. + operationId: UserManagementService_GrantUserRights + parameters: + - name: user_id + in: path + description: |- + The user to whom to grant rights. + + Required + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GrantUserRightsRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GrantUserRightsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + patch: + tags: + - UserManagementService + description: |- + Revoke rights from a user. + Revoking rights does not affect the resource version of the corresponding user. + operationId: UserManagementService_RevokeUserRights + parameters: + - name: user_id + in: path + description: |- + The user from whom to revoke rights. + + Required + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RevokeUserRightsRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RevokeUserRightsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v2/version: + get: + tags: + - VersionService + description: Read the Ledger API version + operationId: VersionService_GetLedgerApiVersion + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetLedgerApiVersionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + ActiveContract: + type: object + properties: + created_event: + allOf: + - $ref: '#/components/schemas/CreatedEvent' + description: |- + The event as it appeared in the context of its last update (i.e. daml transaction or + reassignment). In particular, the last offset, node_id pair is preserved. + The last update is the most recent update created or assigned this contract on synchronizer_id synchronizer. + The offset of the CreatedEvent might point to an already pruned update, therefore it cannot necessarily be used + for lookups. + + Required + synchronizer_id: + type: string + description: |- + A valid synchronizer id + + Required + reassignment_counter: + type: string + description: |- + Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases + with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter + equals zero. + This field will be the reassignment_counter of the latest observable activation event on this synchronizer, which is + before the active_at_offset. + + Required + AllocateExternalPartyRequest: + type: object + properties: + synchronizer: + type: string + description: |- + TODO(#27670) support synchronizer aliases + Synchronizer ID on which to onboard the party + + Required + onboarding_transactions: + type: array + items: + $ref: '#/components/schemas/AllocateExternalPartyRequest_SignedTransaction' + description: |- + TopologyTransactions to onboard the external party + Can contain: + - A namespace for the party. + This can be either a single NamespaceDelegation, + or DecentralizedNamespaceDefinition along with its authorized namespace owners in the form of NamespaceDelegations. + May be provided, if so it must be fully authorized by the signatures in this request combined with the existing topology state. + - A PartyToParticipant to register the hosting relationship of the party, and the party's signing keys and threshold. + Must be provided. + + Required: must be non-empty + multi_hash_signatures: + type: array + items: + $ref: '#/components/schemas/Signature' + description: |- + Optional signatures of the combined hash of all onboarding_transactions + This may be used instead of providing signatures on each individual transaction + + Optional: can be empty + identity_provider_id: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the party is managed by the default identity provider. + + Optional + wait_for_allocation: + type: boolean + description: |- + When true, this RPC will attempt to wait for the party to be allocated on the synchronizer before returning. + When false, the allocation will happen asynchronously. + This is a best effort only as this synchronization is only possible for non decentralized parties (single hosting node). + For decentralized parties, this flag is ignored. + Defaults to true. + + Optional + user_id: + type: string + description: |- + The user who will get the act_as rights to the newly allocated party. + If set to an empty string (the default), no user will get rights to the party. + + Optional + description: |- + Required authorization: + ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)`` + AllocateExternalPartyRequest_SignedTransaction: + type: object + properties: + transaction: + type: string + description: |- + The serialized TopologyTransaction + + Required: must be non-empty + format: bytes + signatures: + type: array + items: + $ref: '#/components/schemas/Signature' + description: |- + Additional signatures for this transaction specifically + Use for transactions that require additional signatures beyond the namespace key signatures + e.g: PartyToParticipant must be signed by all registered keys + + Optional: can be empty + AllocateExternalPartyResponse: + type: object + properties: + party_id: + type: string + description: |- + The allocated party id + + Required + AllocatePartyRequest: + type: object + properties: + party_id_hint: + type: string + description: |- + A hint to the participant which party ID to allocate. It can be + ignored. + Must be a valid PartyIdString (as described in ``value.proto``). + + Optional + local_metadata: + allOf: + - $ref: '#/components/schemas/ObjectMeta' + description: |- + Participant-local metadata to be stored in the ``PartyDetails`` of this newly allocated party. + + Optional + identity_provider_id: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. + + Optional + synchronizer_id: + type: string + description: |- + The synchronizer, on which the party should be allocated. + For backwards compatibility, this field may be omitted, if the participant is connected to only one synchronizer. + Otherwise a synchronizer must be specified. + + Optional + user_id: + type: string + description: |- + The user who will get the act_as rights to the newly allocated party. + If set to an empty string (the default), no user will get rights to the party. + + Optional + description: |- + Required authorization: + ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)`` + AllocatePartyResponse: + type: object + properties: + party_details: + allOf: + - $ref: '#/components/schemas/PartyDetails' + description: |- + The allocated party details + + Required + Archived: + type: object + properties: + archived_event: + allOf: + - $ref: '#/components/schemas/ArchivedEvent' + description: Required + synchronizer_id: + type: string + description: |- + The synchronizer which sequenced the archival of the contract + + Required + ArchivedEvent: + type: object + properties: + offset: + type: string + description: |- + The offset of origin. + Offsets are managed by the participant nodes. + Transactions can thus NOT be assumed to have the same offsets on different participant nodes. + It is a valid absolute offset (positive integer) + + Required + node_id: + type: integer + description: |- + The position of this event in the originating transaction or reassignment. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of transactions. + Must be valid node ID (non-negative integer) + + Required + format: int32 + contract_id: + type: string + description: |- + The ID of the archived contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + Identifies the template that defines the choice that archived the contract. + This template's package-id may differ from the target contract's package-id + if the target contract has been upgraded or downgraded. + + The identifier uses the package-id reference format. + + Required + witness_parties: + type: array + items: + type: string + description: |- + The parties that are notified of this event. For an ``ArchivedEvent``, + these are the intersection of the stakeholders of the contract in + question and the parties specified in the ``TransactionFilter``. The + stakeholders are the union of the signatories and the observers of + the contract. + Each one of its elements must be a valid PartyIdString (as described + in ``value.proto``). + + Required: must be non-empty + package_name: + type: string + description: |- + The package name of the contract. + + Required + implemented_interfaces: + type: array + items: + $ref: '#/components/schemas/Identifier' + description: |- + The interfaces implemented by the target template that have been + matched from the interface filter query. + Populated only in case interface filters with include_interface_view set. + + If defined, the identifier uses the package-id reference format. + + Optional: can be empty + description: Records that a contract has been archived, and choices may no longer be exercised on it. + AssignCommand: + type: object + properties: + reassignment_id: + type: string + description: |- + The ID from the unassigned event to be completed by this assignment. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + source: + type: string + description: |- + The ID of the source synchronizer + Must be a valid synchronizer id + + Required + target: + type: string + description: |- + The ID of the target synchronizer + Must be a valid synchronizer id + + Required + description: Assign a contract + AssignedEvent: + type: object + properties: + source: + type: string + description: |- + The ID of the source synchronizer. + Must be a valid synchronizer id. + + Required + target: + type: string + description: |- + The ID of the target synchronizer. + Must be a valid synchronizer id. + + Required + reassignment_id: + type: string + description: |- + The ID from the unassigned event. + For correlation capabilities. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + submitter: + type: string + description: |- + Party on whose behalf the assign command was executed. + Empty if the assignment happened offline via the repair service. + Must be a valid PartyIdString (as described in ``value.proto``). + + Optional + reassignment_counter: + type: string + description: |- + Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases + with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter + equals zero. + + Required + created_event: + allOf: + - $ref: '#/components/schemas/CreatedEvent' + description: |- + The offset of this event refers to the offset of the assignment, + while the node_id is the index of within the batch. + + Required + description: Records that a contract has been assigned, and it can be used on the target synchronizer. + Command: + type: object + properties: + create: + $ref: '#/components/schemas/CreateCommand' + exercise: + $ref: '#/components/schemas/ExerciseCommand' + exercise_by_key: + $ref: '#/components/schemas/ExerciseByKeyCommand' + create_and_exercise: + $ref: '#/components/schemas/CreateAndExerciseCommand' + description: A command can either create a new contract or exercise a choice on an existing contract. + Commands: + type: object + properties: + workflow_id: + type: string + description: |- + Identifier of the on-ledger workflow that this command is a part of. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + user_id: + type: string + description: |- + Uniquely identifies the participant user that issued the command. + Must be a valid UserIdString (as described in ``value.proto``). + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + command_id: + type: string + description: |- + Uniquely identifies the command. + The triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change, + where act_as is interpreted as a set of party names. + The change ID can be used for matching the intended ledger changes with all their completions. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + commands: + type: array + items: + $ref: '#/components/schemas/Command' + description: |- + Individual elements of this atomic command. Must be non-empty. + + Required: must be non-empty + deduplication_duration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. + deduplication_offset: + type: string + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer) or participant begin (zero). + min_ledger_time_abs: + type: string + description: |- + 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 + format: date-time + min_ledger_time_rel: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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: + type: array + items: + type: string + description: |- + Set of parties on whose behalf the command should be executed. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to act on behalf of each of the given parties. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + read_as: + type: array + items: + type: string + description: |- + 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: can be empty + submission_id: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + If omitted, the participant or the committer may set a value of their choice. + + Optional + disclosed_contracts: + type: array + items: + $ref: '#/components/schemas/DisclosedContract' + description: |- + Additional contracts used to resolve contract & contract key lookups. + + Optional: can be empty + synchronizer_id: + type: string + description: |- + Must be a valid synchronizer id + + Optional + package_id_selection_preference: + type: array + items: + type: string + description: |- + The package-id selection preference of the client for resolving + package names and interface instances in command submission and interpretation + + Optional: can be empty + prefetch_contract_keys: + type: array + items: + $ref: '#/components/schemas/PrefetchContractKey' + description: |- + Fetches the contract keys into the caches to speed up the command processing. + Should only contain contract keys that are expected to be resolved during interpretation of the commands. + Keys of disclosed contracts do not need prefetching. + + Optional: can be empty + taps_max_passes: + type: integer + description: |- + The maximum number of passes for the Topology-Aware Package Selection (TAPS). + Higher values can increase the chance of successful package selection for routing of interpreted transactions. + If unset, this defaults to the value defined in the participant configuration. + The provided value must not exceed the limit specified in the participant configuration. + + Optional + format: uint32 + description: A composite command that groups multiple commands together. + Completion: + type: object + properties: + command_id: + type: string + description: |- + The ID of the succeeded or failed command. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + status: + allOf: + - $ref: '#/components/schemas/Status' + description: |- + Identifies the exact type of the error. + It uses the same format of conveying error details as it is used for the RPC responses of the APIs. + + Optional + update_id: + type: string + description: |- + The update_id of the transaction or reassignment that resulted from the command with command_id. + + Only set for successfully executed commands. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + user_id: + type: string + description: |- + The user-id that was used for the submission, as described in ``commands.proto``. + Must be a valid UserIdString (as described in ``value.proto``). + + Required + act_as: + type: array + items: + type: string + description: |- + The set of parties on whose behalf the commands were executed. + Contains the ``act_as`` parties from ``commands.proto`` + filtered to the requesting parties in CompletionStreamRequest. + The order of the parties need not be the same as in the submission. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + submission_id: + type: string + description: |- + The submission ID this completion refers to, as described in ``commands.proto``. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + deduplication_offset: + type: string + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + + Must be a valid absolute offset (positive integer) or participant begin (zero). + deduplication_duration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Specifies the length of the deduplication period. + It is measured in record time of completions. + + Must be non-negative. + trace_context: + allOf: + - $ref: '#/components/schemas/TraceContext' + description: |- + The Ledger API trace context + + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + offset: + type: string + description: |- + May be used in a subsequent CompletionStreamRequest to resume the consumption of this stream at a later time. + Must be a valid absolute offset (positive integer). + + Required + synchronizer_time: + allOf: + - $ref: '#/components/schemas/SynchronizerTime' + description: |- + The synchronizer along with its record time. + The synchronizer id provided, in case of + + - successful/failed transactions: identifies the synchronizer of the transaction + - for successful/failed unassign commands: identifies the source synchronizer + - for successful/failed assign commands: identifies the target synchronizer + + Required + paid_traffic_cost: + type: string + description: |- + The traffic cost paid by this participant node for the confirmation request + for the submitted command. + + Commands whose execution is rejected before their corresponding + confirmation request is ordered by the synchronizer will report a paid + traffic cost of zero. + If a confirmation request is ordered for a command, but the request fails + (e.g., due to contention with a concurrent contract archival), the traffic + cost is paid and reported on the failed completion for the request. + + If you want to correlate the traffic cost of a successful completion + with the transaction that resulted from the command, you can use the + ``offset`` field to retrieve the transaction using + ``UpdateService.GetUpdateByOffset`` on the same participant node; or alternatively use the ``update_id`` + field to retrieve the transaction using ``UpdateService.GetUpdateById`` on any participant node + that sees the transaction. + + Note: for completions processed before the participant started serving + traffic cost on the Ledger API, this field will be set to zero. + Additionally, the total cost incurred by the submitting node for the submission of the transaction may be greater + than the reported cost, for example if retries were issued due to failed submissions to the synchronizer. + The cost reported here is the one paid for ordering the confirmation request. + + Optional + description: 'A completion represents the status of a submitted command on the ledger: it can be successful or failed.' + CompletionStreamRequest: + type: object + properties: + user_id: + type: string + description: |- + Only completions of commands submitted with the same user_id will be visible in the stream. + Must be a valid UserIdString (as described in ``value.proto``). + + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + parties: + type: array + items: + type: string + description: |- + Non-empty list of parties whose data should be included. + The stream shows only completions of commands for which at least one of the ``act_as`` parties is in the given set of parties. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + begin_exclusive: + type: string + description: |- + This optional field indicates the minimum offset for completions. This can be used to resume an earlier completion stream. + If not set the ledger uses the ledger begin offset instead. + If specified, it must be a valid absolute offset (positive integer) or zero (ledger begin offset). + If the ledger has been pruned, this parameter must be specified and greater than the pruning offset. + + Optional + CompletionStreamResponse: + type: object + properties: + completion: + $ref: '#/components/schemas/Completion' + offset_checkpoint: + $ref: '#/components/schemas/OffsetCheckpoint' + CostEstimation: + type: object + properties: + estimation_timestamp: + type: string + description: |- + Timestamp at which the estimation was made + + Required + format: date-time + confirmation_request_traffic_cost_estimation: + type: string + description: |- + Estimated traffic cost of the confirmation request associated with the transaction + + Required + confirmation_response_traffic_cost_estimation: + type: string + description: |- + Estimated traffic cost of the confirmation response associated with the transaction + This field can also be used as an indication of the cost that other potential confirming nodes + of the party will incur to approve or reject the transaction + + Required + total_traffic_cost_estimation: + type: string + description: |- + Sum of the fields above + + Required + description: |- + Estimation of the cost of submitting the prepared transaction + The estimation is done against the synchronizer chosen during preparation of the transaction + (or the one explicitly requested). + The cost of re-assigning contracts to another synchronizer when necessary is not included in the estimation. + CostEstimationHints: + type: object + properties: + disabled: + type: boolean + description: |- + Disable cost estimation + Default (not set) is false + + Optional + expected_signatures: + type: array + items: + type: integer + format: enum + description: |- + Details on the keys that will be used to sign the transaction (how many and of which type). + Signature size impacts the cost of the transaction. + If empty, the signature sizes will be approximated with threshold-many signatures (where threshold is defined + in the PartyToParticipant of the external party), using keys in the order they are registered. + Empty list is equivalent to not providing this field + + Optional: can be empty + description: Hints to improve cost estimation precision of a prepared transaction + Create: + type: object + properties: + lf_version: + type: string + description: |- + Specific LF version of the node + + Required + contract_id: + type: string + description: Required + package_name: + type: string + description: Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + argument: + allOf: + - $ref: '#/components/schemas/Value' + description: Required + signatories: + type: array + items: + type: string + description: 'Required: must be non-empty' + stakeholders: + type: array + items: + type: string + description: 'Required: must be non-empty' + description: Create Node + CreateAndExerciseCommand: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template of the contract the client wants to create. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + create_arguments: + allOf: + - $ref: '#/components/schemas/Record' + description: |- + The arguments required for creating a contract from this template. + + Required + choice: + type: string + description: |- + The name of the choice the client wants to exercise. + Must be a valid NameString (as described in ``value.proto``). + + Required + choice_argument: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The argument for this choice. + + Required + description: Create a contract and exercise a choice on it in the same transaction. + CreateCommand: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template of contract the client wants to create. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + create_arguments: + allOf: + - $ref: '#/components/schemas/Record' + description: |- + The arguments required for creating a contract from this template. + + Required + description: Create a new contract instance based on a template. + CreateIdentityProviderConfigRequest: + type: object + properties: + identity_provider_config: + allOf: + - $ref: '#/components/schemas/IdentityProviderConfig' + description: Required + CreateIdentityProviderConfigResponse: + type: object + properties: + identity_provider_config: + allOf: + - $ref: '#/components/schemas/IdentityProviderConfig' + description: Required + CreateUserRequest: + type: object + properties: + user: + allOf: + - $ref: '#/components/schemas/User' + description: |- + The user to create. + + Required + rights: + type: array + items: + $ref: '#/components/schemas/Right' + description: |- + The rights to be assigned to the user upon creation, + which SHOULD include appropriate rights for the ``user.primary_party``. + + Optional: can be empty + description: 'Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(user.identity_provider_id)``' + CreateUserResponse: + type: object + properties: + user: + allOf: + - $ref: '#/components/schemas/User' + description: |- + Created user. + + Required + Created: + type: object + properties: + created_event: + allOf: + - $ref: '#/components/schemas/CreatedEvent' + description: |- + The event as it appeared in the context of its original update (i.e. daml transaction or + reassignment) on this participant node. You can use its offset and node_id to find the + corresponding update and the node within it. + + Required + synchronizer_id: + type: string + description: |- + The synchronizer which sequenced the creation of the contract + + Required + CreatedEvent: + type: object + properties: + offset: + type: string + description: |- + The offset of origin, which has contextual meaning, please see description at messages that include a CreatedEvent. + Offsets are managed by the participant nodes. + Transactions can thus NOT be assumed to have the same offsets on different participant nodes. + It is a valid absolute offset (positive integer) + + Required + node_id: + type: integer + description: |- + The position of this event in the originating transaction or reassignment. + The origin has contextual meaning, please see description at messages that include a CreatedEvent. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of transactions. + Must be valid node ID (non-negative integer) + + Required + format: int32 + contract_id: + type: string + description: |- + The ID of the created contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template of the created contract. + The identifier uses the package-id reference format. + + Required + contract_key: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The key of the created contract. + This will be set if and only if ``template_id`` defines a contract key. + + Optional + contract_key_hash: + type: string + description: |- + The hash of contract_key. + This will be set if and only if ``template_id`` defines a contract key. + + Optional: can be empty + format: bytes + create_arguments: + allOf: + - $ref: '#/components/schemas/Record' + description: |- + The arguments that have been used to create the contract. + + Required + created_event_blob: + type: string + description: |- + Opaque representation of contract create event payload intended for forwarding + to an API server as a contract disclosed as part of a command + submission. + + Optional: can be empty + format: bytes + interface_views: + type: array + items: + $ref: '#/components/schemas/InterfaceView' + description: |- + Interface views specified in the transaction filter. + Includes an ``InterfaceView`` for each interface for which there is a ``InterfaceFilter`` with + + - its party in the ``witness_parties`` of this event, + - and which is implemented by the template of this event, + - and which has ``include_interface_view`` set. + + Optional: can be empty + witness_parties: + type: array + items: + type: string + description: |- + The parties that are notified of this event. When a ``CreatedEvent`` + is returned as part of a transaction tree or ledger-effects transaction, this will include all + the parties specified in the ``TransactionFilter`` that are witnesses of the event + (the stakeholders of the contract and all informees of all the ancestors + of this create action that this participant knows about). + If served as part of a ACS delta transaction those will + be limited to all parties specified in the ``TransactionFilter`` that + are stakeholders of the contract (i.e. either signatories or observers). + If the ``CreatedEvent`` is returned as part of an AssignedEvent, + ActiveContract or IncompleteUnassigned (so the event is related to + an assignment or unassignment): this will include all parties of the + ``TransactionFilter`` that are stakeholders of the contract. + + The behavior of reading create events visible to parties not hosted + on the participant node serving the Ledger API is undefined. Concretely, + there is neither a guarantee that the participant node will serve all their + create events on the ACS stream, nor is there a guarantee that matching archive + events are delivered for such create events. + + For most clients this is not a problem, as they only read events for parties + that are hosted on the participant node. If you need to read events + for parties that may not be hosted at all times on the participant node, + subscribe to the ``TopologyEvent``s for that party by setting a corresponding + ``UpdateFormat``. Using these events, query the ACS as-of an offset where the + party is hosted on the participant node, and ignore create events at offsets + where the party is not hosted on the participant node. + + Required: must be non-empty + signatories: + type: array + items: + type: string + description: |- + The signatories for this contract as specified by the template. + + Required: must be non-empty + observers: + type: array + items: + type: string + description: |- + The observers for this contract as specified explicitly by the template or implicitly as choice controllers. + This field never contains parties that are signatories. + + Optional: can be empty + created_at: + type: string + description: |- + Ledger effective time of the transaction that created the contract. + + Required + format: date-time + package_name: + type: string + description: |- + The package name of the created contract. + + Required + acs_delta: + type: boolean + description: |- + Whether this event would be part of respective ACS_DELTA shaped stream, + and should therefore considered when tracking contract activeness on the client-side. + + Required + representative_package_id: + type: string + description: |- + A package-id present in the participant package store that typechecks the contract's argument. + This may differ from the package-id of the template used to create the contract. + For contracts created before Canton 3.4, this field matches the contract's creation package-id. + + NOTE: Experimental, server internal concept, not for client consumption. Subject to change without notice. + + Required + description: Records that a contract has been created, and choices may now be exercised on it. + CumulativeFilter: + type: object + properties: + wildcard_filter: + allOf: + - $ref: '#/components/schemas/WildcardFilter' + description: |- + A wildcard filter that matches all templates + + Optional + interface_filter: + allOf: + - $ref: '#/components/schemas/InterfaceFilter' + description: |- + Include an ``InterfaceView`` for every ``InterfaceFilter`` matching a contract. + The ``InterfaceFilter`` instances MUST each use a unique ``interface_id``. + + Optional + template_filter: + allOf: + - $ref: '#/components/schemas/TemplateFilter' + description: |- + A template for which the data will be included in the + ``create_arguments`` of a matching ``CreatedEvent``. + If a contract is simultaneously selected by a template filter and one or more interface filters, + the corresponding ``include_created_event_blob`` are consolidated using an OR operation. + + Optional + description: |- + A filter that matches all contracts that are either an instance of one of + the ``template_filters`` or that match one of the ``interface_filters``. + DamlTransaction: + type: object + properties: + version: + type: string + description: |- + serialization version, will be >= max(nodes version) + + Required + roots: + type: array + items: + type: string + description: |- + Root nodes of the transaction + + Required: must be non-empty + nodes: + type: array + items: + $ref: '#/components/schemas/DamlTransaction_Node' + description: |- + List of nodes in the transaction + + Required: must be non-empty + node_seeds: + type: array + items: + $ref: '#/components/schemas/DamlTransaction_NodeSeed' + description: |- + Node seeds are values associated with certain nodes used for generating cryptographic salts + + Required: must be non-empty + description: |- + Daml Transaction. + This represents the effect on the ledger if this transaction is successfully committed. + DamlTransaction_Node: + type: object + properties: + node_id: + type: string + description: Required + v1: + allOf: + - $ref: '#/components/schemas/Node' + description: |- + Start at 1000 so we can add more fields before if necessary + When new versions will be added, they will show here + + Required + description: |- + A transaction may contain nodes with different versions. + Each node must be hashed using the hashing algorithm corresponding to its specific version. + [docs-entry-start: DamlTransaction.Node] + DamlTransaction_NodeSeed: + type: object + properties: + node_id: + type: integer + description: Required + format: int32 + seed: + type: string + description: 'Required: must be non-empty' + format: bytes + DeleteIdentityProviderConfigResponse: + type: object + properties: {} + description: Does not (yet) contain any data. + DeleteUserResponse: + type: object + properties: {} + description: Does not (yet) contain any data. + DisclosedContract: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template id of the contract. + The identifier uses the package-id reference format. + + If provided, used to validate the template id of the contract serialized in the created_event_blob. + + Optional + contract_id: + type: string + description: |- + The contract id + + If provided, used to validate the contract id of the contract serialized in the created_event_blob. + + Optional + created_event_blob: + type: string + description: |- + Opaque byte string containing the complete payload required by the Daml engine + to reconstruct a contract not known to the receiving participant. + + Required: must be non-empty + format: bytes + synchronizer_id: + type: string + description: |- + The ID of the synchronizer where the contract is currently assigned + + Optional + description: |- + An additional contract that is used to resolve + contract & contract key lookups. + Enum: + type: object + properties: + enum_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + Omitted from the transaction stream when verbose streaming is not enabled. + Optional when submitting commands. + constructor: + type: string + description: |- + Determines which of the Variant's alternatives is encoded in this message. + Must be a valid NameString. + Required + description: A value with finite set of alternative representations. + Event: + type: object + properties: + created: + allOf: + - $ref: '#/components/schemas/CreatedEvent' + description: |- + The event as it appeared in the context of its original daml transaction on this participant node. + In particular, the offset, node_id pair of the daml transaction are preserved. + archived: + $ref: '#/components/schemas/ArchivedEvent' + exercised: + $ref: '#/components/schemas/ExercisedEvent' + description: |- + Events in transactions can have two primary shapes: + + - ACS delta: events can be CreatedEvent or ArchivedEvent + - ledger effects: events can be CreatedEvent or ExercisedEvent + + In the update service the events are restricted to the events + visible for the parties specified in the transaction filter. Each + event message type below contains a ``witness_parties`` field which + indicates the subset of the requested parties that can see the event + in question. + EventFormat: + type: object + properties: + filters_by_party: + type: object + additionalProperties: + $ref: '#/components/schemas/Filters' + description: |- + Each key must be a valid PartyIdString (as described in ``value.proto``). + The interpretation of the filter depends on the transaction-shape being filtered: + + 1. For **ledger-effects** create and exercise events are returned, for which the witnesses include at least one of + the listed parties and match the per-party filter. + 2. For **transaction and active-contract-set streams** create and archive events are returned for all contracts whose + stakeholders include at least one of the listed parties and match the per-party filter. + + Optional: can be empty + filters_for_any_party: + allOf: + - $ref: '#/components/schemas/Filters' + description: |- + Wildcard filters that apply to all the parties existing on the participant. The interpretation of the filters is the same + with the per-party filter as described above. + + Optional + verbose: + type: boolean + description: |- + 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 + description: |- + A format for events which defines both which events should be included + and what data should be computed and included for them. + + Note that some of the filtering behavior depends on the `TransactionShape`, + which is expected to be specified alongside usages of `EventFormat`. + ExecuteSubmissionAndWaitForTransactionRequest: + type: object + properties: + prepared_transaction: + allOf: + - $ref: '#/components/schemas/PreparedTransaction' + description: |- + the prepared transaction + Typically this is the value of the `prepared_transaction` field in `PrepareSubmissionResponse` + obtained from calling `prepareSubmission`. + + Required + party_signatures: + allOf: + - $ref: '#/components/schemas/PartySignatures' + description: |- + The party(ies) signatures that authorize the prepared submission to be executed by this node. + Each party can provide one or more signatures.. + and one or more parties can sign. + Note that currently, only single party submissions are supported. + + Required + deduplication_duration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. + deduplication_offset: + type: string + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer). + submission_id: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + user_id: + type: string + description: |- + See [PrepareSubmissionRequest.user_id] + + Optional + hashing_scheme_version: + type: integer + description: |- + The hashing scheme version used when building the hash + + Required + format: enum + min_ledger_time: + allOf: + - $ref: '#/components/schemas/MinLedgerTime' + description: |- + If set will influence the chosen ledger effective time but will not result in a submission delay so any override + should be scheduled to executed within the window allowed by synchronizer. + + Optional + transaction_format: + allOf: + - $ref: '#/components/schemas/TransactionFormat' + description: |- + If no ``transaction_format`` is provided, a default will be used where ``transaction_shape`` is set to + TRANSACTION_SHAPE_ACS_DELTA, ``event_format`` is defined with ``filters_by_party`` containing wildcard-template + filter for all original ``act_as`` and ``read_as`` parties and the ``verbose`` flag is set. + When the ``transaction_shape`` TRANSACTION_SHAPE_ACS_DELTA shape is used (explicitly or is defaulted to as explained above), + events will only be returned if the submitting party is hosted on this node. + + Optional + ExecuteSubmissionAndWaitForTransactionResponse: + type: object + properties: + transaction: + allOf: + - $ref: '#/components/schemas/Transaction' + description: |- + The transaction that resulted from the submitted command. + The transaction might contain no events (request conditions result in filtering out all of them). + + Required + ExecuteSubmissionAndWaitRequest: + type: object + properties: + prepared_transaction: + allOf: + - $ref: '#/components/schemas/PreparedTransaction' + description: |- + the prepared transaction + Typically this is the value of the `prepared_transaction` field in `PrepareSubmissionResponse` + obtained from calling `prepareSubmission`. + + Required + party_signatures: + allOf: + - $ref: '#/components/schemas/PartySignatures' + description: |- + The party(ies) signatures that authorize the prepared submission to be executed by this node. + Each party can provide one or more signatures.. + and one or more parties can sign. + Note that currently, only single party submissions are supported. + + Required + deduplication_duration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. + deduplication_offset: + type: string + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer). + submission_id: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + user_id: + type: string + description: |- + See [PrepareSubmissionRequest.user_id] + + Optional + hashing_scheme_version: + type: integer + description: |- + The hashing scheme version used when building the hash + + Required + format: enum + min_ledger_time: + allOf: + - $ref: '#/components/schemas/MinLedgerTime' + description: |- + If set will influence the chosen ledger effective time but will not result in a submission delay so any override + should be scheduled to executed within the window allowed by synchronizer. + + Optional + ExecuteSubmissionAndWaitResponse: + type: object + properties: + update_id: + type: string + description: |- + The id of the transaction that resulted from the submitted command. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + completion_offset: + type: string + description: |- + The details of the offset field are described in ``community/ledger-api/README.md``. + + Required + ExecuteSubmissionRequest: + type: object + properties: + prepared_transaction: + allOf: + - $ref: '#/components/schemas/PreparedTransaction' + description: |- + the prepared transaction + Typically this is the value of the `prepared_transaction` field in `PrepareSubmissionResponse` + obtained from calling `prepareSubmission`. + + Required + party_signatures: + allOf: + - $ref: '#/components/schemas/PartySignatures' + description: |- + The party(ies) signatures that authorize the prepared submission to be executed by this node. + Each party can provide one or more signatures.. + and one or more parties can sign. + Note that currently, only single party submissions are supported. + + Required + deduplication_duration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. + deduplication_offset: + type: string + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer). + submission_id: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + user_id: + type: string + description: |- + See [PrepareSubmissionRequest.user_id] + + Optional + hashing_scheme_version: + type: integer + description: |- + The hashing scheme version used when building the hash + + Required + format: enum + min_ledger_time: + allOf: + - $ref: '#/components/schemas/MinLedgerTime' + description: |- + If set will influence the chosen ledger effective time but will not result in a submission delay so any override + should be scheduled to executed within the window allowed by synchronizer. + + Optional + ExecuteSubmissionResponse: + type: object + properties: {} + Exercise: + type: object + properties: + lf_version: + type: string + description: |- + Specific LF version of the node + + Required + contract_id: + type: string + description: Required + package_name: + type: string + description: Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + signatories: + type: array + items: + type: string + description: 'Required: must be non-empty' + stakeholders: + type: array + items: + type: string + description: 'Required: must be non-empty' + acting_parties: + type: array + items: + type: string + description: 'Required: must be non-empty' + interface_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The identifier uses the package-id reference format. + + Optional + choice_id: + type: string + description: Required + chosen_value: + allOf: + - $ref: '#/components/schemas/Value' + description: Required + consuming: + type: boolean + description: Required + children: + type: array + items: + type: string + description: 'Optional: can be empty' + exercise_result: + allOf: + - $ref: '#/components/schemas/Value' + description: Optional + choice_observers: + type: array + items: + type: string + description: 'Optional: can be empty' + description: Exercise node + ExerciseByKeyCommand: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template of contract the client wants to exercise. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + contract_key: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The key of the contract the client wants to exercise upon. + + Required + choice: + type: string + description: |- + The name of the choice the client wants to exercise. + Must be a valid NameString (as described in ``value.proto``) + + Required + choice_argument: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The argument for this choice. + + Required + description: Exercise a choice on an existing contract specified by its key. + ExerciseCommand: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template or interface of the contract the client wants to exercise. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + To exercise a choice on an interface, specify the interface identifier in the template_id field. + + Required + contract_id: + type: string + description: |- + The ID of the contract the client wants to exercise upon. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + choice: + type: string + description: |- + The name of the choice the client wants to exercise. + Must be a valid NameString (as described in ``value.proto``) + + Required + choice_argument: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The argument for this choice. + + Required + description: Exercise a choice on an existing contract. + ExercisedEvent: + type: object + properties: + offset: + type: string + description: |- + The offset of origin. + Offsets are managed by the participant nodes. + Transactions can thus NOT be assumed to have the same offsets on different participant nodes. + It is a valid absolute offset (positive integer) + + Required + node_id: + type: integer + description: |- + The position of this event in the originating transaction or reassignment. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of transactions. + Must be valid node ID (non-negative integer) + + Required + format: int32 + contract_id: + type: string + description: |- + The ID of the target contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + Identifies the template that defines the executed choice. + This template's package-id may differ from the target contract's package-id + if the target contract has been upgraded or downgraded. + + The identifier uses the package-id reference format. + + Required + interface_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The interface where the choice is defined, if inherited. + If defined, the identifier uses the package-id reference format. + + Optional + choice: + type: string + description: |- + The choice that was exercised on the target contract. + Must be a valid NameString (as described in ``value.proto``). + + Required + choice_argument: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The argument of the exercised choice. + + Required + acting_parties: + type: array + items: + type: string + description: |- + The parties that exercised the choice. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + consuming: + type: boolean + description: |- + If true, the target contract may no longer be exercised. + + Required + witness_parties: + type: array + items: + type: string + description: |- + 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, + the actors and all informees of all the ancestors of this event this + participant knows about. + If not consuming, the witnesses are the union of the signatories, + the actors and all informees of all the ancestors of this event this + participant knows about. + In both cases the witnesses are limited to the querying parties, or not + limited in case anyParty filters are used. + Note that the actors might not necessarily be observers + and thus stakeholders. 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: must be non-empty + last_descendant_node_id: + type: integer + description: |- + Specifies the upper boundary of the node ids of the events in the same transaction that appeared as a result of + this ``ExercisedEvent``. This allows unambiguous identification of all the members of the subtree rooted at this + node. A full subtree can be constructed when all descendant nodes are present in the stream. If nodes are heavily + filtered, it is only possible to determine if a node is in a consequent subtree or not. + + Required + format: int32 + exercise_result: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The result of exercising the choice. + + Optional + package_name: + type: string + description: |- + The package name of the contract. + + Required + implemented_interfaces: + type: array + items: + $ref: '#/components/schemas/Identifier' + description: |- + If the event is consuming, the interfaces implemented by the target template that have been + matched from the interface filter query. + Populated only in case interface filters with include_interface_view set. + + The identifier uses the package-id reference format. + + Optional: can be empty + acs_delta: + type: boolean + description: |- + Whether this event would be part of respective ACS_DELTA shaped stream, + and should therefore considered when tracking contract activeness on the client-side. + + Required + description: Records that a choice has been exercised on a target contract. + ExperimentalCommandInspectionService: + type: object + properties: + supported: + type: boolean + description: Required + description: Whether the Ledger API supports command inspection service + ExperimentalFeatures: + type: object + properties: + static_time: + allOf: + - $ref: '#/components/schemas/ExperimentalStaticTime' + description: Optional + command_inspection_service: + allOf: + - $ref: '#/components/schemas/ExperimentalCommandInspectionService' + description: Optional + description: See the feature message definitions for descriptions. + ExperimentalStaticTime: + type: object + properties: + supported: + type: boolean + description: Required + description: Ledger is in the static time mode and exposes a time service. + FeaturesDescriptor: + type: object + properties: + experimental: + allOf: + - $ref: '#/components/schemas/ExperimentalFeatures' + description: |- + Features under development or features that are used + for ledger implementation testing purposes only. + + Daml applications SHOULD not depend on these in production. + + Required + user_management: + allOf: + - $ref: '#/components/schemas/UserManagementFeature' + description: |- + 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. + + Required + party_management: + allOf: + - $ref: '#/components/schemas/PartyManagementFeature' + description: |- + If set, then the Ledger API server supports party management configurability. + It is recommended that clients query this field to gracefully adjust their behavior to + maximum party page size. + + Required + offset_checkpoint: + allOf: + - $ref: '#/components/schemas/OffsetCheckpointFeature' + description: |- + It contains the timeouts related to the periodic offset checkpoint emission + + Required + package_feature: + allOf: + - $ref: '#/components/schemas/PackageFeature' + description: |- + If set, then the Ledger API server supports package listing + configurability. It is recommended that clients query this field to + gracefully adjust their behavior to maximum package listing page size. + + Required + Fetch: + type: object + properties: + lf_version: + type: string + description: |- + Specific LF version of the node + + Required + contract_id: + type: string + description: Required + package_name: + type: string + description: Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + signatories: + type: array + items: + type: string + description: 'Required: must be non-empty' + stakeholders: + type: array + items: + type: string + description: 'Required: must be non-empty' + acting_parties: + type: array + items: + type: string + description: 'Required: must be non-empty' + interface_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: Optional + description: Fetch node + Filters: + type: object + properties: + cumulative: + type: array + items: + $ref: '#/components/schemas/CumulativeFilter' + description: |- + Every filter in the cumulative list expands the scope of the resulting stream. Each interface, + template or wildcard filter means additional events that will match the query. + The impact of include_interface_view and include_created_event_blob fields in the filters will + also be accumulated. + A template or an interface SHOULD NOT appear twice in the accumulative field. + A wildcard filter SHOULD NOT be defined more than once in the accumulative field. + If no ``CumulativeFilter`` defined, the default of a single ``WildcardFilter`` with + include_created_event_blob unset is used. + + Optional: can be empty + description: The union of a set of template filters, interface filters, or a wildcard. + GenMap: + type: object + properties: + entries: + type: array + items: + $ref: '#/components/schemas/GenMap_Entry' + GenMap_Entry: + type: object + properties: + key: + $ref: '#/components/schemas/Value' + value: + $ref: '#/components/schemas/Value' + GenerateExternalPartyTopologyRequest: + type: object + properties: + synchronizer: + type: string + description: |- + Synchronizer-id for which we are building this request. + TODO(#27670) support synchronizer aliases + + Required + party_hint: + type: string + description: |- + The actual party id will be constructed from this hint and a fingerprint of the public key + + Required + public_key: + allOf: + - $ref: '#/components/schemas/SigningPublicKey' + description: |- + Public key + + Required + local_participant_observation_only: + type: boolean + description: |- + If true, then the local participant will only be observing, not confirming. Default false. + + Optional + other_confirming_participant_uids: + type: array + items: + type: string + description: |- + Other participant ids which should be confirming for this party + + Optional: can be empty + confirmation_threshold: + type: integer + description: |- + Confirmation threshold >= 1 for the party. Defaults to all available confirmers (or if set to 0). + + Optional + format: uint32 + observing_participant_uids: + type: array + items: + type: string + description: |- + Other observing participant ids for this party + + Optional: can be empty + GenerateExternalPartyTopologyResponse: + type: object + properties: + party_id: + type: string + description: |- + The generated party id + + Required + public_key_fingerprint: + type: string + description: |- + The fingerprint of the supplied public key + + Required + topology_transactions: + type: array + items: + type: string + format: bytes + description: |- + The serialized topology transactions which need to be signed and submitted as part of the allocate party process + Note that the serialization includes the versioning information. Therefore, the transaction here is serialized + as an `UntypedVersionedMessage` which in turn contains the serialized `TopologyTransaction` in the version + supported by the synchronizer. + + Required: must be non-empty + multi_hash: + type: string + description: |- + the multi-hash which may be signed instead of each individual transaction + + Required: must be non-empty + format: bytes + description: Response message with topology transactions and the multi-hash to be signed. + GetActiveContractsPageRequest: + type: object + properties: + active_at_offset: + type: string + description: |- + The offset at which the snapshot of the active contracts will be computed. + Must be no greater than the current ledger end offset. + Must be greater than or equal to the last pruning offset. + Optional, if defined, it must be a valid absolute offset (positive integer) or ledger begin offset (zero). + If zero, the empty set will be returned. + If not defined, the current ledger end will be used and it will be populated in the response. + + Optional + event_format: + allOf: + - $ref: '#/components/schemas/EventFormat' + description: |- + Format of the contract_entries in the result. In case of CreatedEvent the presentation will be of + TRANSACTION_SHAPE_ACS_DELTA. + + Required + max_page_size: + type: integer + description: |- + The result page will contain at most max_page_size entries of the respective active contract snapshot. + The server might reject max_page_size breaching the server-specified limit. + Optional, if not defined, the default will be determined by the server. + + Optional + format: int32 + page_token: + type: string + description: |- + To get the next page of the active contracts snapshot, the ``page_token`` should be set to the + ``next_page_token`` of the last ``GetActiveContractsPageResponse``. + The page token only works if subsequent requests: + + - are executed on the same participant, + - use the same active_at_offset and event_format, + - and the participant's store was not pruned to after the active_at_offset. + + If not specified, the first page of the active contracts snapshot will be returned. + + Optional: can be empty + format: bytes + GetActiveContractsPageResponse: + type: object + properties: + active_contracts: + type: array + items: + $ref: '#/components/schemas/GetActiveContractsResponse' + description: |- + The collection of active contracts for this page response. + + Required: must be non-empty + active_at_offset: + type: string + description: |- + The active_at_offset which was specified in the request, or the calculated active_at_offset from the actual + ledger end from at the evaluation of the request. + + Required + next_page_token: + type: string + description: |- + If not present this is the last page. If present, this token must be used to get the next page. + + Optional: can be empty + format: bytes + GetActiveContractsRequest: + type: object + properties: + active_at_offset: + type: string + description: |- + The offset at which the snapshot of the active contracts will be computed. + Must be no greater than the current ledger end offset. + Must be greater than or equal to the last pruning offset. + Must be a valid absolute offset (positive integer) or ledger begin offset (zero). + If zero, the empty set will be returned. + + Required + event_format: + allOf: + - $ref: '#/components/schemas/EventFormat' + description: |- + Format of the contract_entries in the result. In case of CreatedEvent the presentation will be of + TRANSACTION_SHAPE_ACS_DELTA. + + Required + stream_continuation_token: + type: string + description: |- + Opaque representation of a continuation token defining a position in the active contracts snapshot. + The prefix of the active contracts snapshot will be omitted up to and including the element from which + the continuation token was read. + To reuse the continuation token from a `GetActiveContractsPageResponse`: + + - subsequent request must be executed on the same participant with the same version of canton, + - subsequent request must have the same active_at_offset, + - subsequent request must have the same event_format + - and the participant must not have been pruned after the active_at_offset. + + If not specified, the whole active contracts snapshot will be returned. + + Optional: can be empty + format: bytes + description: |- + If the given offset is different than the ledger end, and there are (un)assignments in-flight at the given offset, + the snapshot may fail with "FAILED_PRECONDITION/PARTICIPANT_PRUNED_DATA_ACCESSED". + Note that it is ok to request acs snapshots for party migration with offsets other than ledger end, because party + migration is not concerned with incomplete (un)assignments. + GetActiveContractsResponse: + type: object + properties: + workflow_id: + type: string + description: |- + The workflow ID used in command submission which corresponds to the contract_entry. Only set if + the ``workflow_id`` for the command was set. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + active_contract: + allOf: + - $ref: '#/components/schemas/ActiveContract' + description: |- + The contract is active on the assigned synchronizer, meaning: there was an activation event on the given synchronizer ( + created, assigned), which is not followed by a deactivation event (archived, unassigned) on the same + synchronizer, until the active_at_offset. + Since activeness is defined as a per synchronizer concept, it is possible, that a contract is active on one + synchronizer, but already archived on another. + There will be one such message for each synchronizer the contract is active on. + incomplete_unassigned: + allOf: + - $ref: '#/components/schemas/IncompleteUnassigned' + description: |- + Included iff the unassigned event was before or at the active_at_offset, but there was no corresponding + assigned event before or at the active_at_offset. + incomplete_assigned: + allOf: + - $ref: '#/components/schemas/IncompleteAssigned' + description: |- + Important: this message is not indicating that the contract is active on the target synchronizer! + Included iff the assigned event was before or at the active_at_offset, but there was no corresponding + unassigned event before or at the active_at_offset. + stream_continuation_token: + type: string + description: |- + Opaque representation of a continuation token which can be used in the request to bypass the already processed part + of the active contracts snapshot. + Only populated for the streaming ``GetActiveContracts`` rpc call. + + Optional: can be empty + format: bytes + GetConnectedSynchronizersResponse: + type: object + properties: + connected_synchronizers: + type: array + items: + $ref: '#/components/schemas/GetConnectedSynchronizersResponse_ConnectedSynchronizer' + description: 'Optional: can be empty' + GetConnectedSynchronizersResponse_ConnectedSynchronizer: + type: object + properties: + synchronizer_alias: + type: string + description: |- + The alias of the synchronizer + + Required + synchronizer_id: + type: string + description: |- + The ID of the synchronizer + + Required + permission: + type: integer + description: |- + The permission on the synchronizer + Set if a party was used in the request, otherwise unspecified. + + Optional + format: enum + GetContractRequest: + type: object + properties: + contract_id: + type: string + description: |- + The ID of the contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + querying_parties: + type: array + items: + type: string + description: |- + The list of querying parties + The stakeholders of the referenced contract must have an intersection with any of these parties + to return the result. + If no querying_parties specified, all possible contracts could be returned. + + Optional: can be empty + GetContractResponse: + type: object + properties: + created_event: + allOf: + - $ref: '#/components/schemas/CreatedEvent' + description: |- + The representative_package_id will be always set to the contract package ID, therefore this endpoint should + not be used to lookup contract which entered the participant via party replication or repair service. + The witnesses field will contain only the querying_parties which are also stakeholders of the contract as well. + The following fields of the created event cannot be populated, so those should not be used / parsed: + + - offset + - node_id + - created_event_blob + - interface_views + - acs_delta + + Required + GetEventsByContractIdRequest: + type: object + properties: + contract_id: + type: string + description: |- + The contract id being queried. + + Required + event_format: + allOf: + - $ref: '#/components/schemas/EventFormat' + description: |- + Format of the events in the result, the presentation will be of TRANSACTION_SHAPE_ACS_DELTA. + + Required + GetEventsByContractIdResponse: + type: object + properties: + created: + allOf: + - $ref: '#/components/schemas/Created' + description: |- + The create event for the contract with the ``contract_id`` given in the request + provided it exists and has not yet been pruned. + + Optional + archived: + allOf: + - $ref: '#/components/schemas/Archived' + description: |- + The archive event for the contract with the ``contract_id`` given in the request + provided such an archive event exists and it has not yet been pruned. + + Optional + GetIdentityProviderConfigResponse: + type: object + properties: + identity_provider_config: + allOf: + - $ref: '#/components/schemas/IdentityProviderConfig' + description: Required + GetLatestPrunedOffsetsResponse: + type: object + properties: + participant_pruned_up_to_inclusive: + type: string + description: |- + It will always be a non-negative integer. + If positive, the absolute offset up to which the ledger has been pruned, + disregarding the state of all divulged contracts pruning. + If zero, the ledger has not been pruned yet. + + Optional + all_divulged_contracts_pruned_up_to_inclusive: + type: string + description: |- + It will always be a non-negative integer. + If positive, the absolute offset up to which all divulged events have been pruned on the ledger. + It can be at or before the ``participant_pruned_up_to_inclusive`` offset. + For more details about all divulged events pruning, + see ``PruneRequest.prune_all_divulged_contracts`` in ``participant_pruning_service.proto``. + If zero, the divulged events have not been pruned yet. + + Optional + GetLedgerApiVersionResponse: + type: object + properties: + version: + type: string + description: |- + The version of the ledger API. + + Required + features: + allOf: + - $ref: '#/components/schemas/FeaturesDescriptor' + description: |- + 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. + + Required + GetLedgerEndResponse: + type: object + properties: + offset: + type: string + description: |- + It will always be a non-negative integer. + If zero, the participant view of the ledger is empty. + If positive, the absolute offset of the ledger as viewed by the participant. + + Optional + GetPackageResponse: + type: object + properties: + hash_function: + type: integer + description: |- + The hash function we use to calculate the hash. + + Required + format: enum + archive_payload: + type: string + description: |- + Contains a ``daml_lf`` ArchivePayload. See further details in ``daml_lf.proto``. + + Required: must be non-empty + format: bytes + hash: + type: string + description: |- + The hash of the archive payload, can also used as a ``package_id``. + Must be a valid PackageIdString (as described in ``value.proto``). + + Required + GetPackageStatusResponse: + type: object + properties: + package_status: + type: integer + description: |- + The status of the package. + + Required + format: enum + GetParticipantIdResponse: + type: object + properties: + participant_id: + type: string + description: |- + Identifier of the participant, which SHOULD be globally unique. + Must be a valid ParticipantIdStrings (as describe in ``value.proto``). + + Required + GetPartiesResponse: + type: object + properties: + party_details: + type: array + items: + $ref: '#/components/schemas/PartyDetails' + description: |- + 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: must be non-empty + GetPreferredPackageVersionResponse: + type: object + properties: + package_preference: + allOf: + - $ref: '#/components/schemas/PackagePreference' + description: |- + Not populated when no preferred package is found + + Optional + GetPreferredPackagesRequest: + type: object + properties: + package_vetting_requirements: + type: array + items: + $ref: '#/components/schemas/PackageVettingRequirement' + description: |- + The package-name vetting requirements for which the preferred packages should be resolved. + + Generally it is enough to provide the requirements for the intended command's root package-names. + Additional package-name requirements can be provided when additional Daml transaction informees need to use + package dependencies of the command's root packages. + + Required: must be non-empty + synchronizer_id: + type: string + description: |- + The synchronizer whose vetting state should be used for resolving this query. + If not specified, the vetting states of all synchronizers to which the participant is connected are used. + + Optional + vetting_valid_at: + type: string + description: |- + The timestamp at which the package vetting validity should be computed + on the latest topology snapshot as seen by the participant. + If not provided, the participant's current clock time is used. + + Optional + format: date-time + GetPreferredPackagesResponse: + type: object + properties: + package_references: + type: array + items: + $ref: '#/components/schemas/PackageReference' + description: |- + The package references of the preferred packages. + Must contain one package reference for each requested package-name. + + If you build command submissions whose content depends on the returned + preferred packages, then we recommend submitting the preferred package-ids + in the ``package_id_selection_preference`` of the command submission to + avoid race conditions with concurrent changes of the on-ledger package vetting state. + + Required: must be non-empty + synchronizer_id: + type: string + description: |- + The synchronizer for which the package preferences are computed. + If the synchronizer_id was specified in the request, then it matches the request synchronizer_id. + + Required + GetUpdateByIdRequest: + type: object + properties: + update_id: + type: string + description: |- + The ID of a particular update. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + update_format: + allOf: + - $ref: '#/components/schemas/UpdateFormat' + description: |- + The format for the update. + + Required + GetUpdateByOffsetRequest: + type: object + properties: + offset: + type: string + description: |- + The offset of the update being looked up. + Must be a valid absolute offset (positive integer). + + Required + update_format: + allOf: + - $ref: '#/components/schemas/UpdateFormat' + description: |- + The format for the update. + + Required + GetUpdateResponse: + type: object + properties: + transaction: + $ref: '#/components/schemas/Transaction' + reassignment: + $ref: '#/components/schemas/Reassignment' + topology_transaction: + $ref: '#/components/schemas/TopologyTransaction' + GetUpdatesPageRequest: + type: object + properties: + begin_offset_exclusive: + type: string + description: |- + Exclusive lower bound offset of the requested ledger section (non-negative integer). + The response page will only contain updates whose offset is strictly greater than this. + If set to zero or not defined, the lower bound is set to the actual pruning offset or to the beginning of the + ledger if the participant was not pruned yet. + If set to positive and the ledger has been pruned, this parameter must be greater or equal than the pruning offset. + + Optional + end_offset_inclusive: + type: string + description: |- + Inclusive upper bound offset of the requested ledger section. + If specified the response will only contain updates whose offset is less than or equal to this. + If not specified response will only contain updates whose offset is less than the current ledger-end. + + Optional + max_page_size: + type: integer + description: |- + The result page will contain the first max_page_size Updates of all matching updates. + The server may reject queries with max_page_size above server specified limits. + If not specified, the default max_page_size is determined by the server. + + Optional + format: int32 + update_format: + allOf: + - $ref: '#/components/schemas/UpdateFormat' + description: Required + descending_order: + type: boolean + description: |- + If set, the page will populate the elements in descending order starting from the end_offset_inclusive. + + Optional + page_token: + type: string + description: |- + To get the next page of updates, the ``page_token`` should be set to the + ``next_page_token`` of the last ``GetUpdatesPageResponse``. + To achieve correct paging: subsequent requests must + + - be executed on the same participant with the same version of canton, + - have the same begin_offset_exclusive, + - have the same end_offset_inclusive, + - have the same update_format and + - have the same descending_order. + + If not specified, the first page of updates will be returned. + + Optional: can be empty + format: bytes + GetUpdatesPageResponse: + type: object + properties: + updates: + type: array + items: + $ref: '#/components/schemas/GetUpdateResponse' + description: |- + The first max_page_size updates that match the filter in the request. + In case descending_order was selected, the order of the updates is in reversed offset order. + + Optional: can be empty + lowest_page_offset_exclusive: + type: string + description: |- + Represents the lower bound of this page. + + Required + highest_page_offset_inclusive: + type: string + description: |- + Represents the upper bound of the page. + + Required + next_page_token: + type: string + description: |- + If the value is not populated, this is the last page. + If the value is populated, this token can be used to get the next page. + If the original ``GetFirstUpdatePageRequest`` end_offset_inclusive was not specified and the request uses + ascending order, then this token will always be populated, so you can use it to "tail" the ledger by + repeatedly polling with the new page token returned. + + Optional: can be empty + format: bytes + GetUpdatesRequest: + type: object + properties: + begin_exclusive: + type: string + description: Required + end_inclusive: + type: string + description: |- + Inclusive higher bound offset of the requested ledger section. + If specified the response will only contain transactions whose offset is less than or equal to this. + If not specified, + + - the descending_order must not be selected, + - the stream will not terminate. + + Optional + update_format: + allOf: + - $ref: '#/components/schemas/UpdateFormat' + description: |- + The update format for this request + + Required + descending_order: + type: boolean + description: |- + If set, the stream will populate the elements in descending order. + + Optional + GetUpdatesResponse: + type: object + properties: + transaction: + $ref: '#/components/schemas/Transaction' + reassignment: + $ref: '#/components/schemas/Reassignment' + offset_checkpoint: + $ref: '#/components/schemas/OffsetCheckpoint' + topology_transaction: + $ref: '#/components/schemas/TopologyTransaction' + GetUserResponse: + type: object + properties: + user: + allOf: + - $ref: '#/components/schemas/User' + description: |- + Retrieved user. + + Required + GlobalKey: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + package_name: + type: string + description: Required + key: + allOf: + - $ref: '#/components/schemas/Value' + description: Required + hash: + type: string + description: 'Required: must be non-empty' + format: bytes + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + GrantUserRightsRequest: + type: object + properties: + user_id: + type: string + description: |- + The user to whom to grant rights. + + Required + rights: + type: array + items: + $ref: '#/components/schemas/Right' + description: |- + The rights to grant. + + Optional: can be empty + identity_provider_id: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + description: |- + Add the rights to the set of rights granted to the user. + + Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)`` + GrantUserRightsResponse: + type: object + properties: + newly_granted_rights: + type: array + items: + $ref: '#/components/schemas/Right' + description: |- + The rights that were newly granted by the request. + + Optional: can be empty + Identifier: + type: object + properties: + package_id: + type: string + description: |- + Generally, the identifier of the Daml package that contains the entity. + When encoding a package-id, it must be a valid PackageIdString. + + The field is overloaded to also be able to contain the package-name of the Daml package. + This is supported if the entity referenced is either an interface or template. + When representing the Daml package-name, the encoding is of form `#` + where `#` (not a valid package-id character) + is used as a discriminator for signalling a package-name encoding. + + Required + module_name: + type: string + description: |- + The dot-separated module name of the identifier. + Required + entity_name: + type: string + description: |- + The dot-separated name of the entity (e.g. record, template, ...) within the module. + Required + description: |- + Unique identifier of an entity. + Throughout this API, the following terminology is being used: + + - if a Daml package-id is encoded in the package_id field, it is referred to as using a "package-id reference format" + - if a Daml package-name is encoded in the package_id field, it is referred to as using a "package-name reference format" + IdentityProviderConfig: + type: object + properties: + identity_provider_id: + type: string + description: |- + The identity provider identifier + Must be a valid LedgerString (as describe in ``value.proto``). + + Required + is_deactivated: + type: boolean + description: |- + When set, the callers using JWT tokens issued by this identity provider are denied all access + to the Ledger API. + Modifiable + + Optional + issuer: + type: string + description: |- + Specifies the issuer of the JWT token. + The issuer value is a case sensitive URL using the https scheme that contains scheme, host, + and optionally, port number and path components and no query or fragment components. + Modifiable + + Can be left empty when used in `UpdateIdentityProviderConfigRequest` if the issuer is not being updated. + + Required + jwks_url: + type: string + description: |- + The JWKS (JSON Web Key Set) URL. + The Ledger API uses JWKs (JSON Web Keys) from the provided URL to verify that the JWT has been + signed with the loaded JWK. Only RS256 (RSA Signature with SHA-256) signing algorithm is supported. + Modifiable + + Required + audience: + type: string + description: |- + Specifies the audience of the JWT token. + When set, the callers using JWT tokens issued by this identity provider are allowed to get an access + only if the "aud" claim includes the string specified here + Modifiable + + Optional + IncompleteAssigned: + type: object + properties: + assigned_event: + allOf: + - $ref: '#/components/schemas/AssignedEvent' + description: Required + IncompleteUnassigned: + type: object + properties: + created_event: + allOf: + - $ref: '#/components/schemas/CreatedEvent' + description: |- + The event as it appeared in the context of its last activation update (i.e. daml transaction or + reassignment). In particular, the last activation offset, node_id pair is preserved. + The last activation update is the most recent update created or assigned this contract on synchronizer_id synchronizer before + the unassigned_event. + The offset of the CreatedEvent might point to an already pruned update, therefore it cannot necessarily be used + for lookups. + + Required + unassigned_event: + allOf: + - $ref: '#/components/schemas/UnassignedEvent' + description: Required + InterfaceFilter: + type: object + properties: + interface_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The interface that a matching contract must implement. + The ``interface_id`` needs to be valid: corresponding interface should be defined in + one of the available packages at the time of the query. + Both package-name and package-id reference formats for the identifier are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + include_interface_view: + type: boolean + description: |- + Whether to include the interface view on the contract in the returned ``CreatedEvent``. + Use this to access contract data in a uniform manner in your API client. + + Optional + include_created_event_blob: + type: boolean + description: |- + Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``. + Use this to access the contract create event payload in your API client + for submitting it as a disclosed contract with future commands. + + Optional + description: This filter matches contracts that implement a specific interface. + InterfaceView: + type: object + properties: + interface_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The interface implemented by the matched event. + The identifier uses the package-id reference format. + + Required + view_status: + allOf: + - $ref: '#/components/schemas/Status' + description: |- + Whether the view was successfully computed, and if not, + the reason for the error. The error is reported using the same rules + for error codes and messages as the errors returned for API requests. + + Required + view_value: + allOf: + - $ref: '#/components/schemas/Record' + description: |- + The value of the interface's view method on this event. + Set if it was requested in the ``InterfaceFilter`` and it could be + successfully computed. + + Optional + implementation_package_id: + type: string + description: |- + The package defining the interface implementation used to compute the view. + Can be different from the package that was used to create the contract itself, + as the contract arguments can be upgraded or downgraded using smart-contract upgrading + as part of computing the interface view. + Populated if the view computation is successful, otherwise empty. + + Optional + description: View of a create event matched by an interface filter. + List: + type: object + properties: + elements: + type: array + items: + $ref: '#/components/schemas/Value' + description: |- + The elements must all be of the same concrete value type. + Optional + description: A homogenous collection of values. + ListIdentityProviderConfigsResponse: + type: object + properties: + identity_provider_configs: + type: array + items: + $ref: '#/components/schemas/IdentityProviderConfig' + description: |- + The list of identity provider configs + + Required: must be non-empty + ListKnownPartiesResponse: + type: object + properties: + party_details: + type: array + items: + $ref: '#/components/schemas/PartyDetails' + description: |- + The details of all Daml parties known by the participant. + + Required: must be non-empty + next_page_token: + type: string + description: |- + Pagination token to retrieve the next page. + Empty, if there are no further results. + + Optional + ListPackagesResponse: + type: object + properties: + package_ids: + type: array + items: + type: string + description: |- + The IDs of all Daml-LF packages supported by the server. + Each element must be a valid PackageIdString (as described in ``value.proto``). + + Required: must be non-empty + ListUserRightsResponse: + type: object + properties: + rights: + type: array + items: + $ref: '#/components/schemas/Right' + description: |- + All rights of the user. + + Optional: can be empty + ListUsersResponse: + type: object + properties: + users: + type: array + items: + $ref: '#/components/schemas/User' + description: |- + A subset of users of the participant node that fit into this page. + Can be empty if no more users + + Optional: can be empty + next_page_token: + type: string + description: |- + Pagination token to retrieve the next page. + Empty, if there are no further results. + + Optional + ListVettedPackagesRequest: + type: object + properties: + package_metadata_filter: + allOf: + - $ref: '#/components/schemas/PackageMetadataFilter' + description: |- + The package metadata filter the returned vetted packages set must satisfy. + + Optional + topology_state_filter: + allOf: + - $ref: '#/components/schemas/TopologyStateFilter' + description: |- + The topology filter the returned vetted packages set must satisfy. + + Optional + page_token: + type: string + description: |- + Pagination token to determine the specific page to fetch. Using the token + guarantees that ``VettedPackages`` on a subsequent page are all greater + (``VettedPackages`` are sorted by synchronizer ID then participant ID) than + the last ``VettedPackages`` on a previous page. + + The server does not store intermediate results between calls chained by a + series of page tokens. As a consequence, if new vetted packages are being + added and a page is requested twice using the same token, more packages can + be returned on the second call. + + Leave unspecified (i.e. as empty string) to fetch the first page. + + Optional + page_size: + type: integer + description: |- + Maximum number of ``VettedPackages`` results to return in a single page. + + If the page_size is unspecified (i.e. left as 0), the server will decide + the number of results to be returned. + + If the page_size exceeds the maximum supported by the server, an + error will be returned. + + To obtain the server's maximum consult the PackageService descriptor + available in the VersionService. + + Optional + format: uint32 + ListVettedPackagesResponse: + type: object + properties: + vetted_packages: + type: array + items: + $ref: '#/components/schemas/VettedPackages' + description: |- + All ``VettedPackages`` that contain at least one ``VettedPackage`` matching + both a ``PackageMetadataFilter`` and a ``TopologyStateFilter``. + Sorted by synchronizer_id then participant_id. + + Optional: can be empty + next_page_token: + type: string + description: |- + Pagination token to retrieve the next page. + Empty string if there are no further results. + + Optional + Metadata: + type: object + properties: + submitter_info: + allOf: + - $ref: '#/components/schemas/Metadata_SubmitterInfo' + description: Required + synchronizer_id: + type: string + description: Required + mediator_group: + type: integer + description: Required + format: uint32 + transaction_uuid: + type: string + description: Required + preparation_time: + type: string + description: Required + input_contracts: + type: array + items: + $ref: '#/components/schemas/Metadata_InputContract' + description: |- + Not populated if the transaction has no input contracts + + Optional: can be empty + min_ledger_effective_time: + type: string + description: Optional + max_ledger_effective_time: + type: string + description: Optional + global_key_mapping: + type: array + items: + $ref: '#/components/schemas/Metadata_GlobalKeyMappingEntry' + description: |- + Contextual information needed to process the transaction but not signed, either because it's already indirectly + signed by signing the transaction, or because it doesn't impact the ledger state + + Optional: can be empty + max_record_time: + type: string + description: |- + Maximum timestamp at which the transaction can be recorded onto the ledger via the synchronizer `synchronizer_id`. + If submitted after it will be rejected even if otherwise valid, in which case it needs to be prepared and signed again + with a new valid max_record_time. + Unsigned in 3.3 to avoid a breaking protocol change + Will be signed in 3.4+ + Set max_record_time in the PreparedTransactionRequest to get this field set accordingly + + Optional + description: |- + Transaction Metadata + Refer to the hashing documentation for information on how it should be hashed. + Metadata_GlobalKeyMappingEntry: + type: object + properties: + key: + allOf: + - $ref: '#/components/schemas/GlobalKey' + description: Required + value: + allOf: + - $ref: '#/components/schemas/Value' + description: Optional + Metadata_InputContract: + type: object + properties: + v1: + allOf: + - $ref: '#/components/schemas/Create' + description: When new versions will be added, they will show here + created_at: + type: string + description: Required + event_blob: + type: string + description: 'Required: must be non-empty' + format: bytes + Metadata_SubmitterInfo: + type: object + properties: + act_as: + type: array + items: + type: string + description: 'Required: must be non-empty' + command_id: + type: string + description: Required + MinLedgerTime: + type: object + properties: + min_ledger_time_abs: + type: string + description: |- + Lower bound for the ledger time assigned to the resulting transaction. + The ledger time of a transaction is assigned as part of command interpretation. + Important note: for interactive submissions, if the transaction depends on time, it **must** be signed + and submitted within a time window around the ledger time assigned to the transaction during the prepare method. + The time delta around that ledger time is a configuration of the ledger, usually short, around 1 minute. + If however the transaction does not depend on time, the available time window to sign and submit the transaction is bound + by the preparation time, which is also assigned in the "prepare" step (this request), + but can be configured with a much larger skew, allowing for more time to sign the request (in the order of hours). + Must not be set at the same time as min_ledger_time_rel. + Optional + format: date-time + min_ledger_time_rel: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Same as min_ledger_time_abs, but specified as a duration, starting from the time this request is received by the server. + Must not be set at the same time as min_ledger_time_abs. + Optional + Node: + type: object + properties: + create: + $ref: '#/components/schemas/Create' + fetch: + $ref: '#/components/schemas/Fetch' + exercise: + $ref: '#/components/schemas/Exercise' + rollback: + $ref: '#/components/schemas/Rollback' + ObjectMeta: + type: object + properties: + resource_version: + type: string + description: |- + An opaque, non-empty value, populated by a participant server which represents the internal version of the resource + this ``ObjectMeta`` message is attached to. The participant server will change it to a unique value each time the corresponding resource is updated. + You must not rely on the format of resource version. The participant server might change it without notice. + You can obtain the newest resource version value by issuing a read request. + You may use it for concurrent change detection by passing it back unmodified in an update request. + The participant server will then compare the passed value with the value maintained by the system to determine + if any other updates took place since you had read the resource version. + Upon a successful update you are guaranteed that no other update took place during your read-modify-write sequence. + However, if another update took place during your read-modify-write sequence then your update will fail with an appropriate error. + Concurrent change control is optional. It will be applied only if you include a resource version in an update request. + When creating a new instance of a resource you must leave the resource version empty. + Its value will be populated by the participant server upon successful resource creation. + + Optional + annotations: + type: object + additionalProperties: + type: string + description: |- + A set of modifiable key-value pairs that can be used to represent arbitrary, client-specific metadata. + Constraints: + + 1. The total size over all keys and values cannot exceed 256kb in UTF-8 encoding. + 2. Keys are composed of an optional prefix segment and a required name segment such that: + + - key prefix, when present, must be a valid DNS subdomain with at most 253 characters, followed by a '/' (forward slash) character, + - name segment must have at most 63 characters that are either alphanumeric ([a-z0-9A-Z]), or a '.' (dot), '-' (dash) or '_' (underscore); + and it must start and end with an alphanumeric character. + + 3. Values can be any non-empty strings. + + Keys with empty prefix are reserved for end-users. + Properties set by external tools or internally by the participant server must use non-empty key prefixes. + Duplicate keys are disallowed by the semantics of the protobuf3 maps. + See: https://developers.google.com/protocol-buffers/docs/proto3#maps + Annotations may be a part of a modifiable resource. + Use the resource's update RPC to update its annotations. + In order to add a new annotation or update an existing one using an update RPC, provide the desired annotation in the update request. + In order to remove an annotation using an update RPC, provide the target annotation's key but set its value to the empty string in the update request. + Modifiable + + Optional: can be empty + description: |- + Represents metadata corresponding to a participant resource (e.g. a participant user or participant local information about a party). + + Based on ``ObjectMeta`` meta used in Kubernetes API. + See https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/generated.proto#L640 + OffsetCheckpoint: + type: object + properties: + offset: + type: string + description: |- + The participant's offset, the details of the offset field are described in ``community/ledger-api/README.md``. + Must be a valid absolute offset (positive integer). + + Required + synchronizer_times: + type: array + items: + $ref: '#/components/schemas/SynchronizerTime' + description: |- + The times associated with each synchronizer at this offset. + + Optional: can be empty + description: |- + OffsetCheckpoints may be used to: + + - detect time out of commands. + - provide an offset which can be used to restart consumption. + OffsetCheckpointFeature: + type: object + properties: + max_offset_checkpoint_emission_delay: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + The maximum delay to emmit a new OffsetCheckpoint if it exists + + Required + Optional: + type: object + properties: + value: + $ref: '#/components/schemas/Value' + description: |- + 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. + PackageFeature: + type: object + properties: + max_vetted_packages_page_size: + type: integer + description: |- + The maximum number of vetted packages the server can return in a single + response (page) when listing them. + + Required + format: int32 + PackageMetadataFilter: + type: object + properties: + package_ids: + type: array + items: + type: string + description: |- + If this list is non-empty, any vetted package with a package ID in this + list will match the filter. + + Optional: can be empty + package_name_prefixes: + type: array + items: + type: string + description: |- + If this list is non-empty, any vetted package with a name matching at least + one prefix in this list will match the filter. + + Optional: can be empty + description: |- + Filter the VettedPackages by package metadata. + + A PackageMetadataFilter without package_ids and without package_name_prefixes + matches any vetted package. + + Non-empty fields specify candidate values of which at least one must match. + If both fields are set, then a candidate is returned if it matches one of the fields. + PackagePreference: + type: object + properties: + package_reference: + allOf: + - $ref: '#/components/schemas/PackageReference' + description: |- + The package reference of the preferred package. + + Required + synchronizer_id: + type: string + description: |- + The synchronizer for which the preferred package was computed. + If the synchronizer_id was specified in the request, then it matches the request synchronizer_id. + + Required + PackageReference: + type: object + properties: + package_id: + type: string + description: Required + package_name: + type: string + description: Required + package_version: + type: string + description: Required + PackageVettingRequirement: + type: object + properties: + parties: + type: array + items: + type: string + description: |- + The parties whose participants' vetting state should be considered when resolving the preferred package. + + Required: must be non-empty + package_name: + type: string + description: |- + The package-name for which the preferred package should be resolved. + + Required + description: Defines a package-name for which the commonly vetted package with the highest version must be found. + ParticipantAuthorizationAdded: + type: object + properties: + party_id: + type: string + description: Required + participant_id: + type: string + description: Required + participant_permission: + type: integer + description: Required + format: enum + ParticipantAuthorizationChanged: + type: object + properties: + party_id: + type: string + description: Required + participant_id: + type: string + description: Required + participant_permission: + type: integer + description: Required + format: enum + ParticipantAuthorizationOnboarding: + type: object + properties: + party_id: + type: string + description: Required + participant_id: + type: string + description: Required + participant_permission: + type: integer + description: Required + format: enum + ParticipantAuthorizationRevoked: + type: object + properties: + party_id: + type: string + description: Required + participant_id: + type: string + description: Required + ParticipantAuthorizationTopologyFormat: + type: object + properties: + parties: + type: array + items: + type: string + description: |- + List of parties for which the topology transactions should be sent. + Empty means: for all parties. + + Optional: can be empty + description: A format specifying which participant authorization topology transactions to include and how to render them. + PartyDetails: + type: object + properties: + party: + type: string + description: |- + The stable unique identifier of a Daml party. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required + is_local: + type: boolean + description: |- + true if party is hosted by the participant and the party shares the same identity provider as the user issuing the request. + + Optional + local_metadata: + allOf: + - $ref: '#/components/schemas/ObjectMeta' + description: |- + Participant-local metadata of this party. + Modifiable + + Optional + identity_provider_id: + type: string + description: |- + The id of the ``Identity Provider`` + Optional, if not set, there could be 3 options: + + 1. the party is managed by the default identity provider. + 2. party is not hosted by the participant. + 3. party is hosted by the participant, but is outside of the user's identity provider. + + Optional + PartyManagementFeature: + type: object + properties: + max_parties_page_size: + type: integer + description: |- + The maximum number of parties the server can return in a single response (page). + + Required + format: int32 + PartySignatures: + type: object + properties: + signatures: + type: array + items: + $ref: '#/components/schemas/SinglePartySignatures' + description: |- + Additional signatures provided by all individual parties + + Required: must be non-empty + description: Additional signatures provided by the submitting parties + PrefetchContractKey: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template of contract the client wants to prefetch. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + contract_key: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The key of the contract the client wants to prefetch. + + Required + description: Preload contracts + PrepareSubmissionRequest: + type: object + properties: + user_id: + type: string + description: |- + Uniquely identifies the participant user that prepares the transaction. + Must be a valid UserIdString (as described in ``value.proto``). + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + command_id: + type: string + description: |- + Uniquely identifies the command. + The triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change, + where act_as is interpreted as a set of party names. + The change ID can be used for matching the intended ledger changes with all their completions. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + commands: + type: array + items: + $ref: '#/components/schemas/Command' + description: |- + Individual elements of this atomic command. Must be non-empty. + Limitation: Only single command transaction are currently supported by the API. + The field is marked as repeated in preparation for future support of multiple commands. + + Required: must be non-empty + min_ledger_time: + allOf: + - $ref: '#/components/schemas/MinLedgerTime' + description: Optional + max_record_time: + type: string + description: |- + Maximum timestamp at which the transaction can be recorded onto the ledger via the synchronizer specified in the `PrepareSubmissionResponse`. + If submitted after it will be rejected even if otherwise valid, in which case it needs to be prepared and signed again + with a new valid max_record_time. + Use this to limit the time-to-life of a prepared transaction, + which is useful to know when it can definitely not be accepted + anymore and resorting to preparing another transaction for the same + intent is safe again. + + Optional + format: date-time + act_as: + type: array + items: + type: string + description: |- + Set of parties on whose behalf the command should be executed, if submitted. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to **read** (not act) on behalf of each of the given parties. This is because this RPC merely prepares a transaction + and does not execute it. Therefore read authorization is sufficient even for actAs parties. + Note: This may change, and more specific authorization scope may be introduced in the future. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + read_as: + type: array + items: + type: string + description: |- + Set of parties on whose behalf (in addition to all parties listed in ``act_as``) contracts can be retrieved. + This affects Daml operations such as ``fetch``, ``fetchByKey``, ``lookupByKey``, ``exercise``, and ``exerciseByKey``. + Note: A command can only use contracts that are visible to at least + one of the parties in ``act_as`` or ``read_as``. This visibility check is independent from the Daml authorization + rules for fetch operations. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to read contract data on behalf of each of the given parties. + + Optional: can be empty + disclosed_contracts: + type: array + items: + $ref: '#/components/schemas/DisclosedContract' + description: |- + Additional contracts used to resolve contract & contract key lookups. + + Optional: can be empty + synchronizer_id: + type: string + description: |- + Must be a valid synchronizer id + If not set, a suitable synchronizer that this node is connected to will be chosen + + Optional + package_id_selection_preference: + type: array + items: + type: string + description: |- + The package-id selection preference of the client for resolving + package names and interface instances in command submission and interpretation + + Optional: can be empty + verbose_hashing: + type: boolean + description: |- + When true, the response will contain additional details on how the transaction was encoded and hashed + This can be useful for troubleshooting of hash mismatches. Should only be used for debugging. + Defaults to false + + Optional + prefetch_contract_keys: + type: array + items: + $ref: '#/components/schemas/PrefetchContractKey' + description: |- + Fetches the contract keys into the caches to speed up the command processing. + Should only contain contract keys that are expected to be resolved during interpretation of the commands. + Keys of disclosed contracts do not need prefetching. + + Optional: can be empty + estimate_traffic_cost: + allOf: + - $ref: '#/components/schemas/CostEstimationHints' + description: |- + Hints to improve the accuracy of traffic cost estimation. + The estimation logic assumes that this node will be used for the execution of the transaction + If another node is used instead, the estimation may be less precise. + Request amplification is not accounted for in the estimation: each amplified request will + result in the cost of the confirmation request to be charged additionally. + + Traffic cost estimation is enabled by default if this field is not set + To turn off cost estimation, set the CostEstimationHints#disabled field to true + + Optional + hashing_scheme_version: + type: integer + description: |- + The hashing scheme version to be used when building the hash. + Defaults to HASHING_SCHEME_VERSION_V2. + + Optional + format: enum + taps_max_passes: + type: integer + description: |- + The maximum number of passes for the Topology-Aware Package Selection (TAPS). + Higher values can increase the chance of successful package selection for routing of interpreted transactions. + If unset, this defaults to the value defined in the participant configuration. + The provided value must not exceed the limit specified in the participant configuration. + + Optional + format: uint32 + PrepareSubmissionResponse: + type: object + properties: + prepared_transaction: + allOf: + - $ref: '#/components/schemas/PreparedTransaction' + description: |- + The interpreted transaction, it represents the ledger changes necessary to execute the commands specified in the request. + Clients MUST display the content of the transaction to the user for them to validate before signing the hash if the preparing participant is not trusted. + + Required + prepared_transaction_hash: + type: string + description: |- + Hash of the transaction, this is what needs to be signed by the party to authorize the transaction. + Only provided for convenience, clients MUST recompute the hash from the raw transaction if the preparing participant is not trusted. + May be removed in future versions + + Required: must be non-empty + format: bytes + hashing_scheme_version: + type: integer + description: |- + The hashing scheme version used when building the hash + + Required + format: enum + hashing_details: + type: string + description: |- + Optional additional details on how the transaction was encoded and hashed. Only set if verbose_hashing = true in the request + Note that there are no guarantees on the stability of the format or content of this field. + Its content should NOT be parsed and should only be used for troubleshooting purposes. + + Optional + cost_estimation: + allOf: + - $ref: '#/components/schemas/CostEstimation' + description: |- + Traffic cost estimation of the prepared transaction + + Optional + PreparedTransaction: + type: object + properties: + transaction: + allOf: + - $ref: '#/components/schemas/DamlTransaction' + description: |- + Daml Transaction representing the ledger effect if executed. See below + + Required + metadata: + allOf: + - $ref: '#/components/schemas/Metadata' + description: |- + Metadata context necessary to execute the transaction + + Required + description: |- + * + Prepared Transaction Message + PriorTopologySerial: + type: object + properties: + prior: + type: integer + description: Previous transaction's serial. + format: uint32 + description: |- + The serial of last ``VettedPackages`` topology transaction on a given + participant and synchronizer. + Reassignment: + type: object + properties: + update_id: + type: string + description: |- + Assigned by the server. Useful for correlating logs. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + command_id: + type: string + description: |- + The ID of the command which resulted in this reassignment. Missing for everyone except the submitting party on the submitting participant. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + workflow_id: + type: string + description: |- + The workflow ID used in reassignment command submission. Only set if the ``workflow_id`` for the command was set. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + offset: + type: string + description: |- + The participant's offset. The details of this field are described in ``community/ledger-api/README.md``. + Must be a valid absolute offset (positive integer). + + Required + events: + type: array + items: + $ref: '#/components/schemas/ReassignmentEvent' + description: |- + The collection of reassignment events. + + Required: must be non-empty + trace_context: + allOf: + - $ref: '#/components/schemas/TraceContext' + description: |- + Ledger API trace context + + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + record_time: + type: string + description: |- + The time at which the reassignment was recorded. The record time refers to the source/target + synchronizer for an unassign/assign event respectively. + + Required + format: date-time + synchronizer_id: + type: string + description: |- + A valid synchronizer id. + Identifies the synchronizer that synchronized this Reassignment. + + Required + paid_traffic_cost: + type: string + description: |- + The traffic cost that this participant node paid for the corresponding (un)assignment request. + + Not set for transactions that were + - initiated by another participant + - initiated offline via the repair service + - processed before the participant started serving traffic cost on the Ledger API + - returned as part of a query filtering for a non submitting party + + Optional + description: Complete view of an on-ledger reassignment. + ReassignmentCommand: + type: object + properties: + unassign_command: + $ref: '#/components/schemas/UnassignCommand' + assign_command: + $ref: '#/components/schemas/AssignCommand' + ReassignmentCommands: + type: object + properties: + workflow_id: + type: string + description: |- + Identifier of the on-ledger workflow that this command is a part of. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + user_id: + type: string + description: |- + Uniquely identifies the participant user that issued the command. + Must be a valid UserIdString (as described in ``value.proto``). + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + command_id: + type: string + description: |- + Uniquely identifies the command. + The triple (user_id, submitter, command_id) constitutes the change ID for the intended ledger change. + The change ID can be used for matching the intended ledger changes with all their completions. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + submitter: + type: string + description: |- + Party on whose behalf the command should be executed. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to act on behalf of the given party. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required + submission_id: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + If omitted, the participant or the committer may set a value of their choice. + + Optional + commands: + type: array + items: + $ref: '#/components/schemas/ReassignmentCommand' + description: |- + Individual elements of this reassignment. Must be non-empty. + + Required: must be non-empty + ReassignmentEvent: + type: object + properties: + unassigned: + $ref: '#/components/schemas/UnassignedEvent' + assigned: + $ref: '#/components/schemas/AssignedEvent' + Record: + type: object + properties: + record_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + Omitted from the transaction stream when verbose streaming is not enabled. + Optional when submitting commands. + fields: + type: array + items: + $ref: '#/components/schemas/RecordField' + description: |- + The nested values of the record. + Required + description: Contains nested values. + RecordField: + type: object + properties: + label: + type: string + description: |- + When reading a transaction stream, it's omitted if verbose streaming is not enabled. + When submitting a command, it's optional: + + - if all keys within a single record are present, the order in which fields appear does not matter. however, each key must appear exactly once. + - if any of the keys within a single record are omitted, the order of fields MUST match the order of declaration in the Daml template. + + Must be a valid NameString + value: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + A nested value of a record. + Required + description: A named nested value within a record. + RevokeUserRightsRequest: + type: object + properties: + user_id: + type: string + description: |- + The user from whom to revoke rights. + + Required + rights: + type: array + items: + $ref: '#/components/schemas/Right' + description: |- + The rights to revoke. + + Optional: can be empty + identity_provider_id: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + description: |- + Remove the rights from the set of rights granted to the user. + + Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)`` + RevokeUserRightsResponse: + type: object + properties: + newly_revoked_rights: + type: array + items: + $ref: '#/components/schemas/Right' + description: |- + The rights that were actually revoked by the request. + + Optional: can be empty + Right: + type: object + properties: + participant_admin: + allOf: + - $ref: '#/components/schemas/Right_ParticipantAdmin' + description: The user can administer the participant node. + can_act_as: + allOf: + - $ref: '#/components/schemas/Right_CanActAs' + description: The user can act as a specific party. + can_read_as: + allOf: + - $ref: '#/components/schemas/Right_CanReadAs' + description: The user can read ledger data visible to a specific party. + identity_provider_admin: + allOf: + - $ref: '#/components/schemas/Right_IdentityProviderAdmin' + description: The user can administer users and parties assigned to the same identity provider as the one of the user. + can_read_as_any_party: + allOf: + - $ref: '#/components/schemas/Right_CanReadAsAnyParty' + description: The user can read as any party on a participant + can_execute_as: + allOf: + - $ref: '#/components/schemas/Right_CanExecuteAs' + description: The user can prepare and execute submissions as a specific party. + can_execute_as_any_party: + allOf: + - $ref: '#/components/schemas/Right_CanExecuteAsAnyParty' + description: The user can prepare and execute submissions as any party on a participant. + description: A right granted to a user. + Right_CanActAs: + type: object + properties: + party: + type: string + description: |- + The right to authorize commands for this party. + + Required + Right_CanExecuteAs: + type: object + properties: + party: + type: string + description: |- + The right to prepare and execute submissions as this party. + This right does not entitle the user to perform any reads. + If reading is required, a separate ReadAs right must be added. + Right to execute as a party is also implicitly contained in the CanActAs right. + + Required + Right_CanExecuteAsAnyParty: + type: object + properties: {} + description: |- + The rights of a user to prepare and execute transactions as any party. + Its utility is predominantly for users that perform interactive submissions + on behalf of many parties. + Right_CanReadAs: + type: object + properties: + party: + type: string + description: |- + The right to read ledger data visible to this party. + + Required + Right_CanReadAsAnyParty: + type: object + properties: {} + description: |- + The rights of a participant's super reader. Its utility is predominantly for + feeding external tools, such as PQS, continually without the need to change subscriptions + as new parties pop in and out of existence. + Right_IdentityProviderAdmin: + type: object + properties: {} + description: |- + The right to administer the identity provider that the user is assigned to. + It means, being able to manage users and parties that are also assigned + to the same identity provider. + Right_ParticipantAdmin: + type: object + properties: {} + description: The right to administer the participant node. + Rollback: + type: object + properties: + children: + type: array + items: + type: string + description: 'Required: must be non-empty' + description: Rollback Node + Signature: + type: object + properties: + format: + type: integer + description: Required + format: enum + signature: + type: string + description: 'Required: must be non-empty' + format: bytes + signed_by: + type: string + description: |- + The fingerprint/id of the keypair used to create this signature and needed to verify. + + Required + signing_algorithm_spec: + type: integer + description: |- + The signing algorithm specification used to produce this signature + + Required + format: enum + SigningPublicKey: + type: object + properties: + format: + type: integer + description: |- + The serialization format of the public key + + Required + format: enum + key_data: + type: string + description: |- + Serialized public key in the format specified above + + Required: must be non-empty + format: bytes + key_spec: + type: integer + description: |- + The key specification + + Required + format: enum + SinglePartySignatures: + type: object + properties: + party: + type: string + description: |- + Submitting party + + Required + signatures: + type: array + items: + $ref: '#/components/schemas/Signature' + description: |- + Signatures + + Required: must be non-empty + description: Signatures provided by a single party + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' + SubmitAndWaitForReassignmentRequest: + type: object + properties: + reassignment_commands: + allOf: + - $ref: '#/components/schemas/ReassignmentCommands' + description: |- + The reassignment commands to be submitted. + + Required + event_format: + allOf: + - $ref: '#/components/schemas/EventFormat' + description: |- + If no event_format provided, the result will contain no events. + The events in the result, will take shape TRANSACTION_SHAPE_ACS_DELTA. + + Optional + description: This reassignment is executed as a single atomic update. + SubmitAndWaitForReassignmentResponse: + type: object + properties: + reassignment: + allOf: + - $ref: '#/components/schemas/Reassignment' + description: |- + The reassignment that resulted from the submitted reassignment command. + The reassignment might contain no events (request conditions result in filtering out all of them). + + Required + SubmitAndWaitForTransactionRequest: + type: object + properties: + commands: + allOf: + - $ref: '#/components/schemas/Commands' + description: |- + The commands to be submitted. + + Required + transaction_format: + allOf: + - $ref: '#/components/schemas/TransactionFormat' + description: |- + If no ``transaction_format`` is provided, a default will be used where ``transaction_shape`` is set to + TRANSACTION_SHAPE_ACS_DELTA, ``event_format`` is defined with ``filters_by_party`` containing wildcard-template + filter for all original ``act_as`` and ``read_as`` parties and the ``verbose`` flag is set. + + Optional + description: These commands are executed as a single atomic transaction. + SubmitAndWaitForTransactionResponse: + type: object + properties: + transaction: + allOf: + - $ref: '#/components/schemas/Transaction' + description: |- + The transaction that resulted from the submitted command. + The transaction might contain no events (request conditions result in filtering out all of them). + + Required + SubmitAndWaitResponse: + type: object + properties: + update_id: + type: string + description: |- + The id of the transaction that resulted from the submitted command. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + completion_offset: + type: string + description: |- + The details of the offset field are described in ``community/ledger-api/README.md``. + + Required + SubmitReassignmentRequest: + type: object + properties: + reassignment_commands: + allOf: + - $ref: '#/components/schemas/ReassignmentCommands' + description: |- + The reassignment command to be submitted. + + Required + SubmitReassignmentResponse: + type: object + properties: {} + SubmitResponse: + type: object + properties: {} + SynchronizerTime: + type: object + properties: + synchronizer_id: + type: string + description: |- + The id of the synchronizer. + + Required + record_time: + type: string + description: |- + All commands with a maximum record time below this value MUST be considered lost if their completion has not arrived before this checkpoint. + + Required + format: date-time + TemplateFilter: + type: object + properties: + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + A template for which the payload should be included in the response. + The ``template_id`` needs to be valid: corresponding template should be defined in + one of the available packages at the time of the query. + Both package-name and package-id reference formats for the identifier are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + include_created_event_blob: + type: boolean + description: |- + Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``. + Use this to access the contract event payload in your API client + for submitting it as a disclosed contract with future commands. + + Optional + description: This filter matches contracts of a specific template. + TextMap: + type: object + properties: + entries: + type: array + items: + $ref: '#/components/schemas/TextMap_Entry' + TextMap_Entry: + type: object + properties: + key: + type: string + value: + $ref: '#/components/schemas/Value' + TopologyEvent: + type: object + properties: + participant_authorization_changed: + $ref: '#/components/schemas/ParticipantAuthorizationChanged' + participant_authorization_revoked: + $ref: '#/components/schemas/ParticipantAuthorizationRevoked' + participant_authorization_added: + $ref: '#/components/schemas/ParticipantAuthorizationAdded' + participant_authorization_onboarding: + $ref: '#/components/schemas/ParticipantAuthorizationOnboarding' + TopologyFormat: + type: object + properties: + include_participant_authorization_events: + allOf: + - $ref: '#/components/schemas/ParticipantAuthorizationTopologyFormat' + description: |- + Include participant authorization topology events in streams. + If unset, no participant authorization topology events are emitted in the stream. + + Optional + description: A format specifying which topology transactions to include and how to render them. + TopologyStateFilter: + type: object + properties: + participant_ids: + type: array + items: + type: string + description: |- + If this list is non-empty, only vetted packages hosted on participants + listed in this field match the filter. + Query the current Ledger API's participant's ID via the public + ``GetParticipantId`` command in ``PartyManagementService``. + + Optional: can be empty + synchronizer_ids: + type: array + items: + type: string + description: |- + If this list is non-empty, only vetted packages from the topology state of + the synchronizers in this list match the filter. + + Optional: can be empty + description: |- + Filter the vetted packages by the participant and synchronizer that they are + hosted on. + + Empty fields are ignored, such that a ``TopologyStateFilter`` without + participant_ids and without synchronizer_ids matches a vetted package hosted + on any participant and synchronizer. + + Non-empty fields specify candidate values of which at least one must match. + If both fields are set then at least one candidate value must match from each + field. + TopologyTransaction: + type: object + properties: + update_id: + type: string + description: |- + Assigned by the server. Useful for correlating logs. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + offset: + type: string + description: |- + The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. + It is a valid absolute offset (positive integer). + + Required + synchronizer_id: + type: string + description: |- + A valid synchronizer id. + Identifies the synchronizer that synchronized the topology transaction. + + Required + record_time: + type: string + description: |- + The time at which the changes in the topology transaction become effective. There is a small delay between a + topology transaction being sequenced and the changes it contains becoming effective. Topology transactions appear + in order relative to a synchronizer based on their effective time rather than their sequencing time. + + Required + format: date-time + events: + type: array + items: + $ref: '#/components/schemas/TopologyEvent' + description: |- + A non-empty list of topology events. + + Required: must be non-empty + trace_context: + allOf: + - $ref: '#/components/schemas/TraceContext' + description: |- + Ledger API trace context + + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + TraceContext: + type: object + properties: + traceparent: + type: string + description: |- + https://www.w3.org/TR/trace-context/ + + Optional + tracestate: + type: string + description: Optional + Transaction: + type: object + properties: + update_id: + type: string + description: |- + Assigned by the server. Useful for correlating logs. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + command_id: + type: string + description: |- + 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: + type: string + description: |- + The workflow ID used in command submission. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + effective_at: + type: string + description: |- + Ledger effective time. + + Required + format: date-time + events: + type: array + items: + $ref: '#/components/schemas/Event' + description: |- + The collection of events. + Contains: + + - ``CreatedEvent`` or ``ArchivedEvent`` in case of ACS_DELTA transaction shape + - ``CreatedEvent`` or ``ExercisedEvent`` in case of LEDGER_EFFECTS transaction shape + + Required: must be non-empty + offset: + type: string + description: |- + The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. + It is a valid absolute offset (positive integer). + + Required + synchronizer_id: + type: string + description: |- + A valid synchronizer id. + Identifies the synchronizer that synchronized the transaction. + + Required + trace_context: + allOf: + - $ref: '#/components/schemas/TraceContext' + description: |- + Ledger API trace context + + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + record_time: + type: string + description: |- + The time at which the transaction was recorded. The record time refers to the synchronizer + which synchronized the transaction. + + Required + format: date-time + external_transaction_hash: + type: string + description: |- + For transaction externally signed, contains the external transaction hash + signed by the external party. Can be used to correlate an external submission with a committed transaction. + + Optional: can be empty + format: bytes + paid_traffic_cost: + type: string + description: |- + The traffic cost that this participant node paid for the confirmation + request for this transaction. + + Not set for transactions that were + - initiated by another participant + - initiated offline via the repair service + - processed before the participant started serving traffic cost on the Ledger API + - returned as part of a query filtering for a non submitting party + + Optional + description: Filtered view of an on-ledger transaction's create and archive events. + TransactionFormat: + type: object + properties: + event_format: + allOf: + - $ref: '#/components/schemas/EventFormat' + description: Required + transaction_shape: + type: integer + description: |- + What transaction shape to use for interpreting the filters of the event format. + + Required + format: enum + description: |- + A format that specifies what events to include in Daml transactions + and what data to compute and include for them. + UnassignCommand: + type: object + properties: + contract_id: + type: string + description: |- + The ID of the contract the client wants to unassign. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + source: + type: string + description: |- + The ID of the source synchronizer + Must be a valid synchronizer id + + Required + target: + type: string + description: |- + The ID of the target synchronizer + Must be a valid synchronizer id + + Required + description: Unassign a contract + UnassignedEvent: + type: object + properties: + reassignment_id: + type: string + description: |- + The ID of the unassignment. This needs to be used as an input for a assign ReassignmentCommand. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + contract_id: + type: string + description: |- + The ID of the reassigned contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + template_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + The template of the reassigned contract. + The identifier uses the package-id reference format. + + Required + source: + type: string + description: |- + The ID of the source synchronizer + Must be a valid synchronizer id + + Required + target: + type: string + description: |- + The ID of the target synchronizer + Must be a valid synchronizer id + + Required + submitter: + type: string + description: |- + Party on whose behalf the unassign command was executed. + Empty if the unassignment happened offline via the repair service. + Must be a valid PartyIdString (as described in ``value.proto``). + + Optional + reassignment_counter: + type: string + description: |- + Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases + with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter + equals zero. + + Required + assignment_exclusivity: + type: string + description: |- + Assignment exclusivity + Before this time (measured on the target synchronizer), only the submitter of the unassignment can initiate the assignment + Defined for reassigning participants. + + Optional + format: date-time + witness_parties: + type: array + items: + type: string + description: |- + The parties that are notified of this event. + + Required: must be non-empty + package_name: + type: string + description: |- + The package name of the contract. + + Required + offset: + type: string + description: |- + The offset of origin. + Offsets are managed by the participant nodes. + Reassignments can thus NOT be assumed to have the same offsets on different participant nodes. + Must be a valid absolute offset (positive integer) + + Required + node_id: + type: integer + description: |- + The position of this event in the originating reassignment. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of reassignments. + Must be valid node ID (non-negative integer) + + Required + format: int32 + description: Records that a contract has been unassigned, and it becomes unusable on the source synchronizer + UpdateFormat: + type: object + properties: + include_transactions: + allOf: + - $ref: '#/components/schemas/TransactionFormat' + description: |- + Include Daml transactions in streams. + If unset, no transactions are emitted in the stream. + + Optional + include_reassignments: + allOf: + - $ref: '#/components/schemas/EventFormat' + description: |- + Include (un)assignments in the stream. + The events in the result take the shape TRANSACTION_SHAPE_ACS_DELTA. + If unset, no (un)assignments are emitted in the stream. + + Optional + include_topology_events: + allOf: + - $ref: '#/components/schemas/TopologyFormat' + description: |- + Include topology events in streams. + If unset no topology events are emitted in the stream. + + Optional + description: A format specifying what updates to include and how to render them. + UpdateIdentityProviderConfigRequest: + type: object + properties: + identity_provider_config: + allOf: + - $ref: '#/components/schemas/IdentityProviderConfig' + description: |- + The identity provider config to update. + Modifiable + + Required + update_mask: + type: string + description: |- + An update mask specifies how and which properties of the ``IdentityProviderConfig`` message are to be updated. + An update mask consists of a set of update paths. + A valid update path points to a field or a subfield relative to the ``IdentityProviderConfig`` message. + A valid update mask must: + + 1. contain at least one update path, + 2. contain only valid update paths. + + Fields that can be updated are marked as ``Modifiable``. + For additional information see the documentation for standard protobuf3's ``google.protobuf.FieldMask``. + + Required + format: field-mask + UpdateIdentityProviderConfigResponse: + type: object + properties: + identity_provider_config: + allOf: + - $ref: '#/components/schemas/IdentityProviderConfig' + description: |- + Updated identity provider config + + Required + UpdatePartyDetailsRequest: + type: object + properties: + party_details: + allOf: + - $ref: '#/components/schemas/PartyDetails' + description: |- + Party to be updated + Modifiable + + Required + update_mask: + type: string + description: |- + An update mask specifies how and which properties of the ``PartyDetails`` message are to be updated. + An update mask consists of a set of update paths. + A valid update path points to a field or a subfield relative to the ``PartyDetails`` message. + A valid update mask must: + + 1. contain at least one update path, + 2. contain only valid update paths. + + Fields that can be updated are marked as ``Modifiable``. + An update path can also point to non-``Modifiable`` fields such as 'party' and 'local_metadata.resource_version' + because they are used: + + 1. to identify the party details resource subject to the update, + 2. for concurrent change control. + + An update path can also point to non-``Modifiable`` fields such as 'is_local' + as long as the values provided in the update request match the server values. + Examples of update paths: 'local_metadata.annotations', 'local_metadata'. + For additional information see the documentation for standard protobuf3's ``google.protobuf.FieldMask``. + For similar Ledger API see ``com.daml.ledger.api.v2.admin.UpdateUserRequest``. + + Required + format: field-mask + description: 'Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(party_details.identity_provider_id)``' + UpdatePartyDetailsResponse: + type: object + properties: + party_details: + allOf: + - $ref: '#/components/schemas/PartyDetails' + description: |- + Updated party details + + Required + UpdateUserIdentityProviderIdRequest: + type: object + properties: + user_id: + type: string + description: |- + User to update + + Required + source_identity_provider_id: + type: string + description: |- + Current identity provider ID of the user + If omitted, the default IDP is assumed + + Optional + target_identity_provider_id: + type: string + description: |- + Target identity provider ID of the user + If omitted, the default IDP is assumed + + Optional + description: 'Required authorization: ``HasRight(ParticipantAdmin)``' + UpdateUserIdentityProviderIdResponse: + type: object + properties: {} + UpdateUserRequest: + type: object + properties: + user: + allOf: + - $ref: '#/components/schemas/User' + description: |- + The user to update. + Modifiable + + Required + update_mask: + type: string + description: |- + An update mask specifies how and which properties of the ``User`` message are to be updated. + An update mask consists of a set of update paths. + A valid update path points to a field or a subfield relative to the ``User`` message. + A valid update mask must: + + 1. contain at least one update path, + 2. contain only valid update paths. + + Fields that can be updated are marked as ``Modifiable``. + An update path can also point to a non-``Modifiable`` fields such as 'id' and 'metadata.resource_version' + because they are used: + + 1. to identify the user resource subject to the update, + 2. for concurrent change control. + + Examples of valid update paths: 'primary_party', 'metadata', 'metadata.annotations'. + For additional information see the documentation for standard protobuf3's ``google.protobuf.FieldMask``. + For similar Ledger API see ``com.daml.ledger.api.v2.admin.UpdatePartyDetailsRequest``. + + Required + format: field-mask + description: 'Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(user.identity_provider_id)``' + UpdateUserResponse: + type: object + properties: + user: + allOf: + - $ref: '#/components/schemas/User' + description: |- + Updated user + + Required + UpdateVettedPackagesRequest: + type: object + properties: + changes: + type: array + items: + $ref: '#/components/schemas/VettedPackagesChange' + description: |- + Changes to apply to the current vetting state of the participant on the + specified synchronizer. The changes are applied in order. + Any package not changed will keep their previous vetting state. + + Required: must be non-empty + dry_run: + type: boolean + description: |- + If dry_run is true, then the changes are only prepared, but not applied. If + a request would trigger an error when run (e.g. TOPOLOGY_DEPENDENCIES_NOT_VETTED), + it will also trigger an error when dry_run. + + Use this flag to preview a change before applying it. + Defaults to false. + + Optional + synchronizer_id: + type: string + description: |- + If set, the requested changes will take place on the specified + synchronizer. If synchronizer_id is unset and the participant is only + connected to a single synchronizer, that synchronizer will be used by + default. If synchronizer_id is unset and the participant is connected to + multiple synchronizers, the request will error out with + PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER. + + Optional + expected_topology_serial: + allOf: + - $ref: '#/components/schemas/PriorTopologySerial' + description: |- + The serial of the last ``VettedPackages`` topology transaction of this + participant and on this synchronizer. + + Execution of the request fails if this is not correct. Use this to guard + against concurrent changes. + + If left unspecified, no validation is done against the last transaction's + serial. + + Optional + update_vetted_packages_force_flags: + type: array + items: + type: integer + format: enum + description: |- + Controls whether potentially unsafe vetting updates are allowed. + + Optional: can be empty + UpdateVettedPackagesResponse: + type: object + properties: + past_vetted_packages: + allOf: + - $ref: '#/components/schemas/VettedPackages' + description: |- + All vetted packages on this participant and synchronizer, before the + specified changes. Empty if no vetting state existed beforehand. + + Not populated if no vetted topology state exists prior to the update. + + Optional + new_vetted_packages: + allOf: + - $ref: '#/components/schemas/VettedPackages' + description: |- + All vetted packages on this participant and synchronizer, after the specified changes. + + Required + UploadDarFileRequest: + type: object + properties: + dar_file: + type: string + description: |- + 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: must be non-empty + format: bytes + submission_id: + type: string + description: |- + Unique submission identifier. + If not populated, a random identifier will be generated. + + Optional + vetting_change: + type: integer + description: |- + How to vet packages in the DAR being uploaded + + Optional + format: enum + synchronizer_id: + type: string + description: |- + Only used if VettingChange is set to VETTING_CHANGE_VET_ALL_PACKAGES, in + order to specify which synchronizer to vet on. + + If synchronizer_id is set, the synchronizer with this ID will be used. If + synchronizer_id is unset and the participant is only connected to a single + synchronizer, that synchronizer will be used by default. If synchronizer_id + is unset and the participant is connected to multiple synchronizers, the + request will error out with PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER. + + Optional + UploadDarFileResponse: + type: object + properties: {} + description: A message that is received when the upload operation succeeded. + User: + type: object + properties: + id: + type: string + description: |- + The user identifier, which must be a non-empty string of at most 128 + characters that are either alphanumeric ASCII characters or one of the symbols "@^$.!`-#+'~_|:()". + + Required + primary_party: + type: string + description: |- + 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. + Modifiable + + Optional + is_deactivated: + type: boolean + description: |- + When set, then the user is denied all access to the Ledger API. + Otherwise, the user has access to the Ledger API as per the user's rights. + Modifiable + + Optional + metadata: + allOf: + - $ref: '#/components/schemas/ObjectMeta' + description: |- + The metadata of this user. + Note that the ``metadata.resource_version`` tracks changes to the properties described by the ``User`` message and not the user's rights. + Modifiable + + Optional + identity_provider_id: + type: string + description: |- + The ID of the identity provider configured by ``Identity Provider Config`` + If not set, assume the user is managed by the default identity provider. + + Optional + primary_party_authentication: + type: boolean + description: |- + If set to true, the user may authenticate against the Ledger API by signing + a Party JWT using the primary party's signing key. + Modifiable + + Optional + description: |- + Users are used to dynamically manage the rights given to Daml applications. + They are stored and managed per participant node. + UserManagementFeature: + type: object + properties: + supported: + type: boolean + description: |- + Whether the Ledger API server provides the user management service. + + Required + max_rights_per_user: + type: integer + description: |- + 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. + + Required + format: int32 + max_users_page_size: + type: integer + description: |- + 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. + + Required + format: int32 + ValidateDarFileRequest: + type: object + properties: + dar_file: + type: string + description: |- + 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: must be non-empty + format: bytes + submission_id: + type: string + description: |- + Unique submission identifier. If not defined, defaults to a random identifier. + + Optional + synchronizer_id: + type: string + description: |- + If synchronizer_id is set, the synchronizer with this ID will be used. If + synchronizer_id is unset and the participant is only connected to a single + synchronizer, that synchronizer will be used by default. If synchronizer_id + is unset and the participant is connected to multiple synchronizers, the + request will error out with PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER. + + Optional + description: |- + Performs the same checks that UploadDarFileRequest would perform, but doesn't + upload the DAR. + ValidateDarFileResponse: + type: object + properties: {} + Value: + type: object + properties: + bool: + type: boolean + description: True or false. + int64: + type: string + date: + type: integer + description: |- + 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 + format: int32 + timestamp: + type: string + description: |- + 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 + numeric: + type: string + description: |- + 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 + + .. code-block:: none + + [+-]?\d{1,38}(.\d{0,37})? + + and should be representable by a Numeric without loss of precision. + party: + type: string + description: |- + An agent operating on the ledger. + Must be a valid PartyIdString. + text: + type: string + description: A string. + contract_id: + type: string + description: |- + Identifier of an on-ledger contract. Commands which reference an unknown or already archived contract ID will fail. + Must be a valid LedgerString. + optional: + allOf: + - $ref: '#/components/schemas/Optional' + description: The Optional type, None or Some + list: + allOf: + - $ref: '#/components/schemas/List' + description: Represents a homogeneous list of values. + text_map: + allOf: + - $ref: '#/components/schemas/TextMap' + description: The TextMap type + gen_map: + allOf: + - $ref: '#/components/schemas/GenMap' + description: The GenMap type + record: + $ref: '#/components/schemas/Record' + variant: + $ref: '#/components/schemas/Variant' + enum: + allOf: + - $ref: '#/components/schemas/Enum' + description: The Enum type + description: |- + Encodes values that the ledger accepts as command arguments and emits as contract arguments. + + The values encoding use different classes of non-empty strings as identifiers. Those classes are + defined as follows: + + - NameStrings are strings with length <= 1000 that match the regexp ``[A-Za-z\$_][A-Za-z0-9\$_]*``. + - PackageIdStrings are strings with length <= 64 that match the regexp ``[A-Za-z0-9\-_ ]+``. + - PartyIdStrings are strings with length <= 255 that match the regexp ``[A-Za-z0-9:\-_ ]+``. + - ParticipantIdStrings are strings with length <= 255 that match the regexp ``[A-Za-z0-9:\-_ ]+``. + - LedgerStrings are strings with length <= 255 that match the regexp ``[A-Za-z0-9#:\-_/ ]+``. + - UserIdStrings are strings with length <= 128 that match the regexp ``[a-zA-Z0-9@^$.!`\-#+'~_|:]+``. + Variant: + type: object + properties: + variant_id: + allOf: + - $ref: '#/components/schemas/Identifier' + description: |- + Omitted from the transaction stream when verbose streaming is not enabled. + Optional when submitting commands. + constructor: + type: string + description: |- + Determines which of the Variant's alternatives is encoded in this message. + Must be a valid NameString. + Required + value: + allOf: + - $ref: '#/components/schemas/Value' + description: |- + The value encoded within the Variant. + Required + description: A value with alternative representations. + VettedPackage: + type: object + properties: + package_id: + type: string + description: |- + Package ID of this package + + Required + valid_from_inclusive: + type: string + description: |- + The time from which this package is vetted. Empty if vetting time has no + lower bound. + + Optional + format: date-time + valid_until_exclusive: + type: string + description: |- + The time until which this package is vetted. Empty if vetting time has no + upper bound. + + Optional + format: date-time + package_name: + type: string + description: |- + Name of this package. + Only available if the package has been uploaded to the current participant. + + Optional + package_version: + type: string + description: |- + Version of this package. + Only available if the package has been uploaded to the current participant. + + Optional + description: |- + A package that is vetting on a given participant and synchronizer, + modelled after ``VettedPackage`` in `topology.proto `_, + enriched with the package name and version. + VettedPackages: + type: object + properties: + packages: + type: array + items: + $ref: '#/components/schemas/VettedPackage' + description: |- + Sorted by package_name and package_version where known, and package_id as a + last resort. + + Required: must be non-empty + participant_id: + type: string + description: |- + Participant on which these packages are vetted. + + Required + synchronizer_id: + type: string + description: |- + Synchronizer on which these packages are vetted. + + Required + topology_serial: + type: integer + description: |- + Serial of last ``VettedPackages`` topology transaction of this participant + and on this synchronizer. + + Required + format: uint32 + description: |- + The list of packages vetted on a given participant and synchronizer, modelled + after ``VettedPackages`` in `topology.proto `_. + The list only contains packages that matched a filter in the query that + originated it. + VettedPackagesChange: + type: object + properties: + vet: + allOf: + - $ref: '#/components/schemas/VettedPackagesChange_Vet' + description: Add packages to or update packages in the set of vetted packages. + unvet: + allOf: + - $ref: '#/components/schemas/VettedPackagesChange_Unvet' + description: Remove packages from the set of vetted packages. + description: A change to the set of vetted packages. + VettedPackagesChange_Unvet: + type: object + properties: + packages: + type: array + items: + $ref: '#/components/schemas/VettedPackagesRef' + description: |- + Packages to be unvetted. + + If a reference in this list matches multiple packages, they are all + unvetted. + + Required: must be non-empty + description: Remove packages from the set of vetted packages + VettedPackagesChange_Vet: + type: object + properties: + packages: + type: array + items: + $ref: '#/components/schemas/VettedPackagesRef' + description: |- + Packages to be vetted. + + If a reference in this list matches more than one package, the change is + considered ambiguous and the entire update request is rejected. In other + words, every reference must match exactly one package. + + Required: must be non-empty + new_valid_from_inclusive: + type: string + description: |- + The time from which these packages should be vetted, prior lower bounds + are overwritten. + Optional + format: date-time + new_valid_until_exclusive: + type: string + description: |- + The time until which these packages should be vetted, prior upper bounds + are overwritten. + Optional + format: date-time + description: |- + Set vetting bounds of a list of packages. Packages that were not previously + vetted have their bounds added, previous vetting bounds are overwritten. + VettedPackagesRef: + type: object + properties: + package_id: + type: string + description: |- + Package's package id must be the same as this field. + + Optional + package_name: + type: string + description: |- + Package's name must be the same as this field. + + Optional + package_version: + type: string + description: |- + Package's version must be the same as this field. + + Optional + description: |- + A reference to identify one or more packages. + + A reference matches a package if its ``package_id`` matches the package's ID, + its ``package_name`` matches the package's name, and its ``package_version`` + matches the package's version. If an attribute in the reference is left + unspecified (i.e. as an empty string), that attribute is treated as a + wildcard. At a minimum, ``package_id`` or the ``package_name`` must be + specified. + + If a reference does not match any package, the reference is considered + unresolved and the entire update request is rejected. + WildcardFilter: + type: object + properties: + include_created_event_blob: + type: boolean + description: |- + Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``. + Use this to access the contract create event payload in your API client + for submitting it as a disclosed contract with future commands. + + Optional + description: This filter matches all templates. +tags: + - name: CommandCompletionService + description: |- + Allows clients to observe the status of their submissions. + Commands may be submitted via the Command Submission Service. + The on-ledger effects of their submissions are disclosed by the Update Service. + + Commands may fail in 2 distinct manners: + + 1. Failure communicated synchronously in the gRPC error of the submission. + 2. Failure communicated asynchronously in a Completion, see ``completion.proto``. + + Note that not only successfully submitted commands MAY produce a completion event. For example, the participant MAY + choose to produce a completion event for a rejection of a duplicate command. + + Clients that do not receive a successful completion about their submission MUST NOT assume that it was successful. + Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions. + - name: CommandService + description: |- + Command Service is able to correlate submitted commands with completion data, identify timeouts, and return contextual + information with each tracking result. This supports the implementation of stateless clients. + + Note that submitted commands generally produce completion events as well, even in case a command gets rejected. + For example, the participant SHOULD produce a completion event for a rejection of a duplicate command. + - name: CommandSubmissionService + description: |- + Allows clients to attempt advancing the ledger's state by submitting commands. + The final states of their submissions are disclosed by the Command Completion Service. + The on-ledger effects of their submissions are disclosed by the Update Service. + + Commands may fail in 2 distinct manners: + + 1. Failure communicated synchronously in the gRPC error of the submission. + 2. Failure communicated asynchronously in a Completion, see ``completion.proto``. + + Note that not only successfully submitted commands MAY produce a completion event. For example, the participant MAY + choose to produce a completion event for a rejection of a duplicate command. + + Clients that do not receive a successful completion about their submission MUST NOT assume that it was successful. + Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions. + - name: ContractService + description: This service is experimental / alpha, therefore no backwards compatibility is guaranteed. + - name: EventQueryService + description: |- + Query events by contract id. + + Note that querying by contract key is not (yet) supported, as contract keys + are not supported (yet) in multi-synchronizer scenarios. + - name: IdentityProviderConfigService + description: |- + Identity Provider Config Service makes it possible for participant node administrators + to setup and manage additional identity providers at runtime. + + This allows using access tokens from identity providers unknown at deployment time. When an identity + provider is configured, independent IDP administrators can manage their own set of parties and users. + Such parties and users have a matching `identity_provider_id` defined and are inaccessible to + administrators from other identity providers. A user will only be authenticated if the corresponding JWT + token is issued by the appropriate identity provider. + Users and parties without `identity_provider_id` defined are assumed to be using the default identity provider, + which is configured statically at the participant node's deployment time. + + The Ledger API uses the "iss" claim of a JWT token to match the token to a specific IDP. If there is no match, + the default IDP is assumed. + + The fields of request messages (and sub-messages) are marked either as ``Optional`` or ``Required``: + + 1. ``Optional`` denoting the client may leave the field unset when sending a request. + 2. ``Required`` denoting the client must set the field to a non-default value when sending a request. + + An identity provider config resource is described by the ``IdentityProviderConfig`` message, + An identity provider config resource, once it has been created, can be modified. + In order to update the properties represented by the ``IdentityProviderConfig`` message use the ``UpdateIdentityProviderConfig`` RPC. + The only fields that can be modified are those marked as ``Modifiable``. + - name: InteractiveSubmissionService + description: |- + Service allowing interactive construction of command submissions + + The prepare and execute endpoints allow to submit commands in 2-steps: + + 1. prepare transaction from commands, + 2. submit the prepared transaction + + This gives callers the ability to sign the daml transaction with their own signing keys + - name: PackageManagementService + description: |- + 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. + - name: PackageService + description: Allows clients to query the Daml-LF packages that are supported by the server. + - name: PartyManagementService + description: |- + This service allows inspecting the party management state of the ledger known to the participant + and managing the participant-local party metadata. + + The authorization rules for its RPCs are specified on the ``Request`` + messages as boolean expressions over these facts: + + 1. ``HasRight(r)`` denoting whether the authenticated user has right ``r`` and + 2. ``IsAuthenticatedIdentityProviderAdmin(idp)`` denoting whether ``idp`` is equal to the ``identity_provider_id`` + of the authenticated user and the user has an IdentityProviderAdmin right. + + If `identity_provider_id` is set to an empty string, then it's effectively set to the value of access token's 'iss' field if that is provided. + If `identity_provider_id` remains an empty string, the default identity provider will be assumed. + + The fields of request messages (and sub-messages) are marked either as ``Optional`` or ``Required``: + + 1. ``Optional`` denoting the client may leave the field unset when sending a request. + 2. ``Required`` denoting the client must set the field to a non-default value when sending a request. + + A party details resource is described by the ``PartyDetails`` message, + A party details resource, once it has been created, can be modified using the ``UpdatePartyDetails`` RPC. + The only fields that can be modified are those marked as ``Modifiable``. + - name: StateService + description: Allows clients to get state from the ledger. + - name: UpdateService + description: |- + Allows clients to read updates (transactions, (un)assignments, topology events) from the ledger. + + ``GetUpdates`` provides a comprehensive stream of updates/changes + which happened on the virtual shared ledger. These streams are indexed with ledger + offsets, which are strictly increasing. + The virtual shared ledger consist of changes happening on multiple synchronizers which are + connected to the serving participant. Each update belongs to one synchronizer, this is + provided in the result (the ``synchronizer_id`` field in ``Transaction`` + for transactions, the ``source`` field in ``UnassignedEvent`` and the ``target`` field in ``AssignedEvent``). + Consumers can rely on strong causal guarantees on the virtual shared ledger for a single + synchronizer: updates which have greater offsets are happened after than updates with smaller + offsets for the same synchronizer. Across different synchronizers this is not guaranteed. + - name: UserManagementService + description: |- + 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 ``Request`` + messages as boolean expressions over these facts: + + 1. ``HasRight(r)`` denoting whether the authenticated user has right ``r`` and + 2. ``IsAuthenticatedUser(uid)`` denoting whether ``uid`` is the empty string or equal to the id of the authenticated user. + 3. ``IsAuthenticatedIdentityProviderAdmin(idp)`` denoting whether ``idp`` is equal to the ``identity_provider_id`` + of the authenticated user and the user has an IdentityProviderAdmin right. + + If `user_id` is set to the empty string (the default), then the data for the authenticated user will be retrieved. + If `identity_provider_id` is set to an empty string, then it's effectively set to the value of access token's 'iss' field if that is provided. + If `identity_provider_id` remains an empty string, the default identity provider will be assumed. + + The fields of request messages (and sub-messages) are marked either as ``Optional`` or ``Required``: + + 1. ``Optional`` denoting the client may leave the field unset when sending a request. + 2. ``Required`` denoting the client must set the field to a non-default value when sending a request. + + A user resource consists of: + + 1. a set of properties represented by the ``User`` message, + 2. a set of user rights, where each right is represented by the ``Right`` message. + + A user resource, once it has been created, can be modified. + In order to update the properties represented by the ``User`` message use the ``UpdateUser`` RPC. The only fields that can be modified are those marked as ``Modifiable``. + In order to grant or revoke user rights use ``GrantRights' and ``RevokeRights`` RPCs. + - name: VersionService + description: Allows clients to retrieve information about the ledger API version diff --git a/http-annotations-evidence/reproduce.sh b/http-annotations-evidence/reproduce.sh new file mode 100755 index 0000000000..215926bc39 --- /dev/null +++ b/http-annotations-evidence/reproduce.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Regenerates every artefact under http-annotations-evidence/ from the +# annotated .proto files on this branch. Run from the repo root. + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$REPO_ROOT" + +EVIDENCE_DIR="$REPO_ROOT/http-annotations-evidence" +PROTO_ROOT="$REPO_ROOT/community/ledger-api-proto/src/main/protobuf" +EXTERNAL_PROTOS="$REPO_ROOT/community/lib/google-common-protos-scala/target/protobuf_external" + +if ! command -v buf >/dev/null 2>&1; then + echo "buf not found in PATH; install from https://buf.build/docs/installation" >&2 + exit 1 +fi + +echo "== fetching google.api / google.rpc protos ==" +mkdir -p "$EXTERNAL_PROTOS/google/api" "$EXTERNAL_PROTOS/google/rpc" +curl -fsSL -o "$EXTERNAL_PROTOS/google/api/annotations.proto" \ + https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto +curl -fsSL -o "$EXTERNAL_PROTOS/google/api/http.proto" \ + https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto +curl -fsSL -o "$EXTERNAL_PROTOS/google/rpc/status.proto" \ + https://raw.githubusercontent.com/googleapis/googleapis/master/google/rpc/status.proto + +PATHS=( + "$PROTO_ROOT/com/daml/ledger/api/v2/command_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/command_submission_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/command_completion_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/contract_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/event_query_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/package_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/state_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/update_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/version_service.proto" + "$PROTO_ROOT/com/daml/ledger/api/v2/admin" + "$PROTO_ROOT/com/daml/ledger/api/v2/interactive" +) +BUF_PATH_ARGS=() +for p in "${PATHS[@]}"; do BUF_PATH_ARGS+=("--path" "$p"); done + +echo "== buf generate: OpenAPI 3.0.3 ==" +rm -rf "$EVIDENCE_DIR/openapi-3.0/gen" +( cd "$EVIDENCE_DIR/openapi-3.0" \ + && buf generate "${BUF_PATH_ARGS[@]}" "$PROTO_ROOT" ) +mv "$EVIDENCE_DIR/openapi-3.0/gen/openapi.yaml" "$EVIDENCE_DIR/openapi-3.0/openapi.yaml" +rmdir "$EVIDENCE_DIR/openapi-3.0/gen" + +echo "== buf generate: Swagger 2.0 ==" +rm -rf "$EVIDENCE_DIR/swagger-2.0/gen" +( cd "$EVIDENCE_DIR/swagger-2.0" \ + && buf generate "${BUF_PATH_ARGS[@]}" "$PROTO_ROOT" ) +mv "$EVIDENCE_DIR/swagger-2.0/gen/canton-ledger-api.swagger.yaml" \ + "$EVIDENCE_DIR/swagger-2.0/canton-ledger-api.swagger.yaml" +rmdir "$EVIDENCE_DIR/swagger-2.0/gen" + +echo "== regenerating coverage-comparison ==" +JSONAPI_YAML="$REPO_ROOT/community/ledger/ledger-json-api/src/test/resources/json-api-docs/openapi.yaml" +COVERAGE_DIR="$EVIDENCE_DIR/coverage-comparison" +mkdir -p "$COVERAGE_DIR" + +grep -oE '^ /v2/[^:]+' "$JSONAPI_YAML" | sort -u \ + > "$COVERAGE_DIR/paths-jsonapi.txt" + +grep -oE '^ /v2/[^:]+' "$EVIDENCE_DIR/openapi-3.0/openapi.yaml" \ + | sed 's/^ //' | sort -u > "$COVERAGE_DIR/paths-proto.txt" + +# Path-parameter name normalization: proto field names ↔ tapir placeholder names. +sed -E ' + s|\{identity_provider_config\.identity_provider_id\}|{idp-id}|g + s|\{identity_provider_id\}|{idp-id}|g + s|\{package_id\}|{package-id}|g + s|\{user\.id\}|{user-id}|g + s|\{user_id\}|{user-id}|g + s|\{party_details\.party\}|{party}|g + s|\{parties\}|{party}|g +' "$COVERAGE_DIR/paths-proto.txt" | sed 's/^/ /' | sort -u \ + > "$COVERAGE_DIR/paths-proto-normalized.txt" + +comm -23 "$COVERAGE_DIR/paths-jsonapi.txt" "$COVERAGE_DIR/paths-proto-normalized.txt" \ + > "$COVERAGE_DIR/jsonapi-only.txt" +comm -13 "$COVERAGE_DIR/paths-jsonapi.txt" "$COVERAGE_DIR/paths-proto-normalized.txt" \ + > "$COVERAGE_DIR/proto-only.txt" + +echo "== done ==" +echo " openapi-3.0/openapi.yaml: $(wc -l < "$EVIDENCE_DIR/openapi-3.0/openapi.yaml") lines" +echo " swagger-2.0/...swagger.yaml: $(wc -l < "$EVIDENCE_DIR/swagger-2.0/canton-ledger-api.swagger.yaml") lines" +echo " jsonapi-only paths: $(wc -l < "$COVERAGE_DIR/jsonapi-only.txt")" +echo " proto-only paths (after norm): $(wc -l < "$COVERAGE_DIR/proto-only.txt")" diff --git a/http-annotations-evidence/swagger-2.0/buf.gen.yaml b/http-annotations-evidence/swagger-2.0/buf.gen.yaml new file mode 100644 index 0000000000..b0f8d4dbfa --- /dev/null +++ b/http-annotations-evidence/swagger-2.0/buf.gen.yaml @@ -0,0 +1,11 @@ +version: v2 +plugins: + - remote: buf.build/grpc-ecosystem/openapiv2:v2.28.0 + out: gen + opt: + - allow_delete_body=true + - json_names_for_fields=true + - openapi_naming_strategy=fqn + - allow_merge=true + - merge_file_name=canton-ledger-api + - output_format=yaml diff --git a/http-annotations-evidence/swagger-2.0/canton-ledger-api.swagger.yaml b/http-annotations-evidence/swagger-2.0/canton-ledger-api.swagger.yaml new file mode 100644 index 0000000000..b285a23959 --- /dev/null +++ b/http-annotations-evidence/swagger-2.0/canton-ledger-api.swagger.yaml @@ -0,0 +1,6958 @@ +swagger: "2.0" +info: + title: com/daml/ledger/api/v2/admin/command_inspection_service.proto + version: version not set +tags: + - name: CommandInspectionService + - name: IdentityProviderConfigService + - name: PackageManagementService + - name: ParticipantPruningService + - name: PartyManagementService + - name: UserManagementService + - name: CommandCompletionService + - name: CommandService + - name: CommandSubmissionService + - name: ContractService + - name: EventQueryService + - name: InteractiveSubmissionService + - name: PackageService + - name: StateService + - name: UpdateService + - name: VersionService +consumes: + - application/json +produces: + - application/json +paths: + /v2/commands/async/submit: + post: + summary: Submit a single composite command. + operationId: CommandSubmissionService_Submit + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: commands + description: |- + The commands to be submitted in a single transaction. + + Required + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.Commands' + tags: + - CommandSubmissionService + /v2/commands/async/submit-reassignment: + post: + summary: Submit a single reassignment. + operationId: CommandSubmissionService_SubmitReassignment + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitReassignmentResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitReassignmentRequest' + tags: + - CommandSubmissionService + /v2/commands/completions: + post: + summary: Subscribe to command completion events. + operationId: CommandCompletionService_CompletionStream + responses: + "200": + description: A successful response.(streaming responses) + schema: + type: object + properties: + result: + $ref: '#/definitions/com.daml.ledger.api.v2.CompletionStreamResponse' + error: + $ref: '#/definitions/google.rpc.Status' + title: Stream result of com.daml.ledger.api.v2.CompletionStreamResponse + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.CompletionStreamRequest' + tags: + - CommandCompletionService + /v2/commands/submit-and-wait: + post: + summary: |- + Submits a single composite command and waits for its result. + Propagates the gRPC error of failed submissions including Daml interpretation errors. + operationId: CommandService_SubmitAndWait + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitAndWaitResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: commands + description: |- + The commands to be submitted. + + Required + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.Commands' + tags: + - CommandService + /v2/commands/submit-and-wait-for-reassignment: + post: + summary: |- + Submits a single composite reassignment command, waits for its result, and returns the reassignment. + Propagates the gRPC error of failed submission. + operationId: CommandService_SubmitAndWaitForReassignment + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForReassignmentResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + description: This reassignment is executed as a single atomic update. + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForReassignmentRequest' + tags: + - CommandService + /v2/commands/submit-and-wait-for-transaction: + post: + summary: |- + Submits a single composite command, waits for its result, and returns the transaction. + Propagates the gRPC error of failed submissions including Daml interpretation errors. + operationId: CommandService_SubmitAndWaitForTransaction + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForTransactionResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + description: These commands are executed as a single atomic transaction. + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.SubmitAndWaitForTransactionRequest' + tags: + - CommandService + /v2/contracts/contract-by-id: + post: + summary: |- + Looking up contract data by contract ID. + This endpoint is experimental / alpha, therefore no backwards compatibility is guaranteed. + This endpoint must not be used to look up contracts which entered the participant via party replication + or repair service. + If there is no contract exist with the contract ID, or there is no intersection with the querying_parties, + an CONTRACT_PAYLOAD_NOT_FOUND error will be raised. + operationId: ContractService_GetContract + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetContractResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetContractRequest' + tags: + - ContractService + /v2/dars: + post: + summary: Upload a DAR file to the participant. + description: |- + If vetting is enabled in the request, the DAR is checked for upgrade compatibility + with the set of the already vetted packages on the target vetting synchronizer + See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer. + operationId: PackageManagementService_UploadDarFile + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UploadDarFileResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UploadDarFileRequest' + tags: + - PackageManagementService + /v2/dars/validate: + post: + summary: |- + Validates the DAR and checks the upgrade compatibility of the DAR's packages + with the set of the already vetted packages on the target vetting synchronizer. + See ValidateDarFileRequest for details regarding the target vetting synchronizer. + description: |- + The operation has no effect on the state of the participant or the Canton ledger: + the DAR payload and its packages are not persisted neither are the packages vetted. + operationId: PackageManagementService_ValidateDarFile + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ValidateDarFileResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + description: |- + Performs the same checks that UploadDarFileRequest would perform, but doesn't + upload the DAR. + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ValidateDarFileRequest' + tags: + - PackageManagementService + /v2/events/events-by-contract-id: + post: + summary: |- + Get the create and the consuming exercise event for the contract with the provided ID. + No events will be returned for contracts that have been pruned because they + have already been archived before the latest pruning offset. + If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. + operationId: EventQueryService_GetEventsByContractId + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetEventsByContractIdResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetEventsByContractIdRequest' + tags: + - EventQueryService + /v2/idps: + get: + summary: List all existing identity provider configurations. + operationId: IdentityProviderConfigService_ListIdentityProviderConfigs + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ListIdentityProviderConfigsResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + tags: + - IdentityProviderConfigService + post: + summary: |- + Create a new identity provider configuration. + The request will fail if the maximum allowed number of separate configurations is reached. + operationId: IdentityProviderConfigService_CreateIdentityProviderConfig + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.CreateIdentityProviderConfigResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.CreateIdentityProviderConfigRequest' + tags: + - IdentityProviderConfigService + /v2/idps/{identityProviderConfig.identityProviderId}: + patch: + summary: |- + Update selected modifiable attribute of an identity provider config resource described + by the ``IdentityProviderConfig`` message. + operationId: IdentityProviderConfigService_UpdateIdentityProviderConfig + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdateIdentityProviderConfigResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: identityProviderConfig.identityProviderId + description: |- + The identity provider identifier + Must be a valid LedgerString (as describe in ``value.proto``). + + Required + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.IdentityProviderConfigService.UpdateIdentityProviderConfigBody' + tags: + - IdentityProviderConfigService + /v2/idps/{identityProviderId}: + get: + summary: Get the identity provider configuration data by id. + operationId: IdentityProviderConfigService_GetIdentityProviderConfig + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GetIdentityProviderConfigResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: identityProviderId + description: Required + in: path + required: true + type: string + tags: + - IdentityProviderConfigService + delete: + summary: Delete an existing identity provider configuration. + operationId: IdentityProviderConfigService_DeleteIdentityProviderConfig + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.DeleteIdentityProviderConfigResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: identityProviderId + description: |- + The identity provider config to delete. + + Required + in: path + required: true + type: string + tags: + - IdentityProviderConfigService + /v2/interactive-submission/execute: + post: + summary: |- + Execute a prepared submission _asynchronously_ on the ledger. + Requires a signature of the transaction from the submitting external party. + operationId: InteractiveSubmissionService_ExecuteSubmission + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.ExecuteSubmissionResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.ExecuteSubmissionRequest' + tags: + - InteractiveSubmissionService + /v2/interactive-submission/executeAndWait: + post: + summary: |- + Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction + IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. + A malicious node could make a successfully committed request appeared failed and vice versa + operationId: InteractiveSubmissionService_ExecuteSubmissionAndWait + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitRequest' + tags: + - InteractiveSubmissionService + /v2/interactive-submission/executeAndWaitForTransaction: + post: + summary: |- + Similar to ExecuteSubmissionAndWait but additionally returns the transaction + IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. + A malicious node could make a successfully committed request appear as failed and vice versa + operationId: InteractiveSubmissionService_ExecuteSubmissionAndWaitForTransaction + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitForTransactionResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitForTransactionRequest' + tags: + - InteractiveSubmissionService + /v2/interactive-submission/preferred-package-version: + get: + summary: |- + A preferred package is the highest-versioned package for a provided package-name + that is vetted by all the participants hosting the provided parties. + description: |- + Ledger API clients should use this endpoint for constructing command submissions + that are compatible with the provided preferred package, by making informed decisions on: + - which are the compatible packages that can be used to create contracts + - which contract or exercise choice argument version can be used in the command + - which choices can be executed on a template or interface of a contract + + Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. + + Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 + operationId: InteractiveSubmissionService_GetPreferredPackageVersion + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.GetPreferredPackageVersionResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: parties + description: |- + The parties whose participants' vetting state should be considered when resolving the preferred package. + + Required: must be non-empty + in: query + required: false + type: array + items: + type: string + collectionFormat: multi + - name: packageName + description: |- + The package-name for which the preferred package should be resolved. + + Required + in: query + required: false + type: string + - name: synchronizerId + description: |- + The synchronizer whose vetting state should be used for resolving this query. + If not specified, the vetting states of all synchronizers to which the participant is connected are used. + + Optional + in: query + required: false + type: string + - name: vettingValidAt + description: |- + The timestamp at which the package vetting validity should be computed + on the latest topology snapshot as seen by the participant. + If not provided, the participant's current clock time is used. + + Optional + in: query + required: false + type: string + format: date-time + tags: + - InteractiveSubmissionService + /v2/interactive-submission/preferred-packages: + post: + summary: |- + Compute the preferred packages for the vetting requirements in the request. + A preferred package is the highest-versioned package for a provided package-name + that is vetted by all the participants hosting the provided parties. + description: |- + Ledger API clients should use this endpoint for constructing command submissions + that are compatible with the provided preferred packages, by making informed decisions on: + - which are the compatible packages that can be used to create contracts + - which contract or exercise choice argument version can be used in the command + - which choices can be executed on a template or interface of a contract + + If the package preferences could not be computed due to no selection satisfying the requirements, + a `FAILED_PRECONDITION` error will be returned. + + Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. + + Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases + operationId: InteractiveSubmissionService_GetPreferredPackages + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.GetPreferredPackagesResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.GetPreferredPackagesRequest' + tags: + - InteractiveSubmissionService + /v2/interactive-submission/prepare: + post: + summary: Requires `readAs` scope for the submitting party when LAPI User authorization is enabled + operationId: InteractiveSubmissionService_PrepareSubmission + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PrepareSubmissionResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PrepareSubmissionRequest' + tags: + - InteractiveSubmissionService + /v2/package-vetting/list: + post: + summary: |- + Lists which participant node vetted what packages on which synchronizer. + Can be called by any authenticated user. + operationId: PackageService_ListVettedPackages + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.ListVettedPackagesResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.ListVettedPackagesRequest' + tags: + - PackageService + /v2/package-vetting/update: + post: + summary: Update the vetted packages of this participant + operationId: PackageManagementService_UpdateVettedPackages + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdateVettedPackagesResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdateVettedPackagesRequest' + tags: + - PackageManagementService + /v2/packages: + get: + summary: Returns the identifiers of all supported packages. + operationId: PackageService_ListPackages + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.ListPackagesResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + tags: + - PackageService + /v2/packages/{packageId}: + get: + summary: Returns the contents of a single package. + operationId: PackageService_GetPackage + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetPackageResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: packageId + description: |- + The ID of the requested package. + Must be a valid PackageIdString (as described in ``value.proto``). + + Required + in: path + required: true + type: string + tags: + - PackageService + /v2/packages/{packageId}/status: + get: + summary: Returns the status of a single package. + operationId: PackageService_GetPackageStatus + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetPackageStatusResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: packageId + description: |- + The ID of the requested package. + Must be a valid PackageIdString (as described in ``value.proto``). + + Required + in: path + required: true + type: string + tags: + - PackageService + /v2/parties: + get: + summary: |- + List the parties known by the participant. + The list returned contains parties whose ledger access is facilitated by + the participant and the ones maintained elsewhere. + operationId: PartyManagementService_ListKnownParties + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ListKnownPartiesResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: pageToken + description: |- + Pagination token to determine the specific page to fetch. Using the token guarantees that parties on a subsequent + page are all lexically greater than the last party on a previous page. Server does not store intermediate results + between calls chained by a series of page tokens. As a consequence, if new parties are being added and a page is + requested twice using the same token, more parties can be returned on the second call. + Leave empty to fetch the first page. + + Optional + in: query + required: false + type: string + - name: pageSize + description: |- + Maximum number of results to be returned by the server. The server will return no more than that many results, + but it might return fewer. If the page_size is 0, the server will decide the number of results to be returned. + If the page_size exceeds the maximum supported by the server, an error will be returned. To obtain the server's + maximum consult the PartyManagementFeature descriptor available in the VersionService. + + Optional + in: query + required: false + type: integer + format: int32 + - name: identityProviderId + description: |- + The id of the ``Identity Provider`` whose parties should be retrieved. + If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. + + Optional + in: query + required: false + type: string + - name: filterParty + description: |- + An optional filter for the party name, searching for all party names known to this node + starting with the given prefix. This can either be just a string or extend up to the full + identifier. + + Optional + in: query + required: false + type: string + tags: + - PartyManagementService + post: + summary: |- + Allocates a new party on a ledger and adds it to the set managed by the participant. + Caller specifies a party identifier suggestion, the actual identifier + allocated might be different and is implementation specific. + Caller can specify party metadata that is stored locally on the participant. + This call may: + description: |- + - Succeed, in which case the actual allocated identifier is visible in + the response. + - Respond with a gRPC error + + daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in + the consensus layer and call rejected if the identifier is already present. + canton: completely different globally unique identifier is allocated. + Behind the scenes calls to an internal protocol are made. As that protocol + is richer than the surface protocol, the arguments take implicit values + The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, + colon, minus and underscore limited to 255 chars + operationId: PartyManagementService_AllocateParty + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.AllocatePartyResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.AllocatePartyRequest' + tags: + - PartyManagementService + /v2/parties/external/allocate: + post: + summary: 'Alpha 3.3: Endpoint to allocate a new external party on a synchronizer' + description: |- + Expected to be stable in 3.5 + + The external party must be hosted (at least) on this node with either confirmation or observation permissions + It can optionally be hosted on other nodes (then called a multi-hosted party). + If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes + before the party can be used. + Decentralized namespaces are supported but must be provided fully authorized by their owners. + The individual owner namespace transactions can be submitted in the same call (fully authorized as well). + In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is + effectively allocated and ready to use, similarly to the AllocateParty behavior. + For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). + operationId: PartyManagementService_AllocateExternalParty + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.AllocateExternalPartyResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.AllocateExternalPartyRequest' + tags: + - PartyManagementService + /v2/parties/external/generate-topology: + post: + summary: 'Alpha 3.3: Convenience endpoint to generate topology transactions for external signing' + description: |- + Expected to be stable in 3.5 + + You may use this endpoint to generate the common external topology transactions + which can be signed externally and uploaded as part of the allocate party process + + Note that this request will create a normal namespace using the same key for the + identity as for signing. More elaborate schemes such as multi-signature + or decentralized parties require you to construct the topology transactions yourself. + operationId: PartyManagementService_GenerateExternalPartyTopology + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GenerateExternalPartyTopologyResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GenerateExternalPartyTopologyRequest' + tags: + - PartyManagementService + /v2/parties/participant-id: + get: + summary: |- + Return the identifier of the participant. + All horizontally scaled replicas should return the same id. + daml-on-kv-ledger: returns an identifier supplied on command line at launch time + canton: returns globally unique identifier of the participant + operationId: PartyManagementService_GetParticipantId + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GetParticipantIdResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + tags: + - PartyManagementService + /v2/parties/{parties}: + get: + summary: |- + Get the party details of the given parties. Only known parties will be + returned in the list. + operationId: PartyManagementService_GetParties + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GetPartiesResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: parties + description: |- + The stable, unique identifier of the Daml parties. + Must be valid PartyIdStrings (as described in ``value.proto``). + + Required: must be non-empty + in: path + required: true + type: array + items: + type: string + collectionFormat: csv + minItems: 1 + - name: identityProviderId + description: |- + The id of the ``Identity Provider`` whose parties should be retrieved. + If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. + + Optional + in: query + required: false + type: string + tags: + - PartyManagementService + /v2/parties/{partyDetails.party}: + patch: + summary: |- + Update selected modifiable participant-local attributes of a party details resource. + Can update the participant's local information for local parties. + operationId: PartyManagementService_UpdatePartyDetails + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdatePartyDetailsResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: partyDetails.party + description: |- + The stable unique identifier of a Daml party. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.PartyManagementService.UpdatePartyDetailsBody' + tags: + - PartyManagementService + /v2/state/active-contracts: + post: + summary: |- + Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. + Once the stream of GetActiveContractsResponses completes, + the client SHOULD begin streaming updates from the update service, + starting at the GetActiveContractsRequest.active_at_offset specified in this request. + Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. + operationId: StateService_GetActiveContracts + responses: + "200": + description: A successful response.(streaming responses) + schema: + type: object + properties: + result: + $ref: '#/definitions/com.daml.ledger.api.v2.GetActiveContractsResponse' + error: + $ref: '#/definitions/google.rpc.Status' + title: Stream result of com.daml.ledger.api.v2.GetActiveContractsResponse + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + description: |- + If the given offset is different than the ledger end, and there are (un)assignments in-flight at the given offset, + the snapshot may fail with "FAILED_PRECONDITION/PARTICIPANT_PRUNED_DATA_ACCESSED". + Note that it is ok to request acs snapshots for party migration with offsets other than ledger end, because party + migration is not concerned with incomplete (un)assignments. + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetActiveContractsRequest' + tags: + - StateService + /v2/state/active-contracts-page: + post: + summary: |- + Returns a page of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. + Once all pages are fetched by repeated calls to ``GetActiveContractsPage``, + the client SHOULD begin retrieving updates from the update service, + starting at the ``GetActiveContractsPageResponse``.``active_at_offset`` specified in this request. + Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. + operationId: StateService_GetActiveContractsPage + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetActiveContractsPageResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetActiveContractsPageRequest' + tags: + - StateService + /v2/state/connected-synchronizers: + get: + summary: Get the list of connected synchronizers at the time of the query. + operationId: StateService_GetConnectedSynchronizers + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetConnectedSynchronizersResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: party + description: |- + The party of interest + Must be a valid PartyIdString (as described in ``value.proto``). + If empty, all synchronizers this node is connected to will be returned + + Optional + in: query + required: false + type: string + - name: participantId + description: |- + The id of a participant whose mapping of a party to connected synchronizers is requested. + Must be a valid participant-id retrieved through a prior call to getParticipantId. + Defaults to the participant id of the host participant. + + Optional + in: query + required: false + type: string + - name: identityProviderId + description: |- + The ID of the identity provider configured by ``Identity Provider Config`` + If not set, it's assumed the user is managed by the default identity provider. + + Optional + in: query + required: false + type: string + tags: + - StateService + /v2/state/latest-pruned-offsets: + get: + summary: Get the latest successfully pruned ledger offsets + operationId: StateService_GetLatestPrunedOffsets + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetLatestPrunedOffsetsResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + tags: + - StateService + /v2/state/ledger-end: + get: + summary: |- + Get the current ledger end. + Subscriptions started with the returned offset will serve events after this RPC was called. + operationId: StateService_GetLedgerEnd + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetLedgerEndResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + tags: + - StateService + /v2/updates: + post: + summary: |- + Read the ledger's filtered update stream for the specified contents and filters. + It returns the event types in accordance with the stream contents selected. Also the selection criteria + for individual events depends on the transaction shape chosen. + description: |- + - ACS delta: a requesting party must be a stakeholder of an event for it to be included. + - ledger effects: a requesting party must be a witness of an event for it to be included. + operationId: UpdateService_GetUpdates + responses: + "200": + description: A successful response.(streaming responses) + schema: + type: object + properties: + result: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdatesResponse' + error: + $ref: '#/definitions/google.rpc.Status' + title: Stream result of com.daml.ledger.api.v2.GetUpdatesResponse + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + description: |- + Exclusive lower bound offset of the requested ledger section (non-negative integer). + The response will only contain transactions whose offset is strictly greater than this. + If set to zero, the lower bound is set to the beginning of the ledger. + If the participant has been pruned, this parameter must be greater or equal than the pruning offset. + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdatesRequest' + tags: + - UpdateService + /v2/updates/get-updates-page: + post: + summary: |- + Read a page of ledger's filtered updates. It returns the event types in accordance with + the specified contents and filters. + Additionally, the selection criteria for individual events depends on the transaction shape chosen. + description: |- + - ACS delta: an event is included only if the requesting party is a stakeholder. + - ledger effects: an event is included if the requesting party is a witness. + operationId: UpdateService_GetUpdatesPage + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdatesPageResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdatesPageRequest' + tags: + - UpdateService + /v2/updates/update-by-id: + post: + summary: |- + Lookup an update by its ID. + If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. + operationId: UpdateService_GetUpdateById + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdateResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdateByIdRequest' + tags: + - UpdateService + /v2/updates/update-by-offset: + post: + summary: |- + Lookup an update by its offset. + If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. + operationId: UpdateService_GetUpdateByOffset + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdateResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdateByOffsetRequest' + tags: + - UpdateService + /v2/users: + get: + summary: List all existing users. + operationId: UserManagementService_ListUsers + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ListUsersResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: pageToken + description: |- + Pagination token to determine the specific page to fetch. + Leave empty to fetch the first page. + + Optional + in: query + required: false + type: string + - name: pageSize + description: |- + 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 + in: query + required: false + type: integer + format: int32 + - name: identityProviderId + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + in: query + required: false + type: string + tags: + - UserManagementService + post: + summary: Create a new user. + operationId: UserManagementService_CreateUser + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.CreateUserResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.CreateUserRequest' + tags: + - UserManagementService + /v2/users/{user.id}: + patch: + summary: Update selected modifiable attribute of a user resource described by the ``User`` message. + operationId: UserManagementService_UpdateUser + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdateUserResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: user.id + description: |- + The user identifier, which must be a non-empty string of at most 128 + characters that are either alphanumeric ASCII characters or one of the symbols "@^$.!`-#+'~_|:()". + + Required + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UserManagementService.UpdateUserBody' + tags: + - UserManagementService + /v2/users/{userId}: + get: + summary: Get the user data of a specific user or the authenticated user. + operationId: UserManagementService_GetUser + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GetUserResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: userId + description: |- + The user whose data to retrieve. + If set to empty string (the default), then the data for the authenticated user will be retrieved. + + Optional + in: path + required: true + type: string + - name: identityProviderId + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + in: query + required: false + type: string + tags: + - UserManagementService + delete: + summary: Delete an existing user and all its rights. + operationId: UserManagementService_DeleteUser + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.DeleteUserResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: userId + description: |- + The user to delete. + + Required + in: path + required: true + type: string + - name: identityProviderId + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + in: query + required: false + type: string + tags: + - UserManagementService + /v2/users/{userId}/identity-provider-id: + patch: + summary: Update the assignment of a user from one IDP to another. + operationId: UserManagementService_UpdateUserIdentityProviderId + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdateUserIdentityProviderIdResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: userId + description: |- + User to update + + Required + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UserManagementService.UpdateUserIdentityProviderIdBody' + tags: + - UserManagementService + /v2/users/{userId}/rights: + get: + summary: List the set of all rights granted to a user. + operationId: UserManagementService_ListUserRights + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ListUserRightsResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: userId + description: |- + 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 + in: path + required: true + type: string + - name: identityProviderId + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + in: query + required: false + type: string + tags: + - UserManagementService + post: + summary: |- + Grant rights to a user. + Granting rights does not affect the resource version of the corresponding user. + operationId: UserManagementService_GrantUserRights + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.GrantUserRightsResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: userId + description: |- + The user to whom to grant rights. + + Required + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UserManagementService.GrantUserRightsBody' + tags: + - UserManagementService + patch: + summary: |- + Revoke rights from a user. + Revoking rights does not affect the resource version of the corresponding user. + operationId: UserManagementService_RevokeUserRights + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.RevokeUserRightsResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + parameters: + - name: userId + description: |- + The user from whom to revoke rights. + + Required + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UserManagementService.RevokeUserRightsBody' + tags: + - UserManagementService + /v2/version: + get: + summary: Read the Ledger API version + operationId: VersionService_GetLedgerApiVersion + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/com.daml.ledger.api.v2.GetLedgerApiVersionResponse' + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/google.rpc.Status' + tags: + - VersionService +definitions: + com.daml.ledger.api.v2.ActiveContract: + type: object + properties: + createdEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.CreatedEvent' + description: |- + The event as it appeared in the context of its last update (i.e. daml transaction or + reassignment). In particular, the last offset, node_id pair is preserved. + The last update is the most recent update created or assigned this contract on synchronizer_id synchronizer. + The offset of the CreatedEvent might point to an already pruned update, therefore it cannot necessarily be used + for lookups. + + Required + synchronizerId: + type: string + description: Required + title: A valid synchronizer id + reassignmentCounter: + type: string + format: uint64 + description: |- + Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases + with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter + equals zero. + This field will be the reassignment_counter of the latest observable activation event on this synchronizer, which is + before the active_at_offset. + + Required + com.daml.ledger.api.v2.Archived: + type: object + properties: + archivedEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.ArchivedEvent' + title: Required + synchronizerId: + type: string + description: Required + title: The synchronizer which sequenced the archival of the contract + com.daml.ledger.api.v2.ArchivedEvent: + type: object + properties: + offset: + type: string + format: int64 + description: Required + title: |- + The offset of origin. + Offsets are managed by the participant nodes. + Transactions can thus NOT be assumed to have the same offsets on different participant nodes. + It is a valid absolute offset (positive integer) + nodeId: + type: integer + format: int32 + description: Required + title: |- + The position of this event in the originating transaction or reassignment. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of transactions. + Must be valid node ID (non-negative integer) + contractId: + type: string + description: |- + The ID of the archived contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + Identifies the template that defines the choice that archived the contract. + This template's package-id may differ from the target contract's package-id + if the target contract has been upgraded or downgraded. + + The identifier uses the package-id reference format. + + Required + witnessParties: + type: array + items: + type: string + description: |- + The parties that are notified of this event. For an ``ArchivedEvent``, + these are the intersection of the stakeholders of the contract in + question and the parties specified in the ``TransactionFilter``. The + stakeholders are the union of the signatories and the observers of + the contract. + Each one of its elements must be a valid PartyIdString (as described + in ``value.proto``). + + Required: must be non-empty + packageName: + type: string + description: |- + The package name of the contract. + + Required + implementedInterfaces: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The interfaces implemented by the target template that have been + matched from the interface filter query. + Populated only in case interface filters with include_interface_view set. + + If defined, the identifier uses the package-id reference format. + + Optional: can be empty + description: Records that a contract has been archived, and choices may no longer be exercised on it. + com.daml.ledger.api.v2.AssignCommand: + type: object + properties: + reassignmentId: + type: string + description: |- + The ID from the unassigned event to be completed by this assignment. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + source: + type: string + description: Required + title: |- + The ID of the source synchronizer + Must be a valid synchronizer id + target: + type: string + description: Required + title: |- + The ID of the target synchronizer + Must be a valid synchronizer id + title: Assign a contract + com.daml.ledger.api.v2.AssignedEvent: + type: object + properties: + source: + type: string + description: |- + The ID of the source synchronizer. + Must be a valid synchronizer id. + + Required + target: + type: string + description: |- + The ID of the target synchronizer. + Must be a valid synchronizer id. + + Required + reassignmentId: + type: string + description: |- + The ID from the unassigned event. + For correlation capabilities. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + submitter: + type: string + description: |- + Party on whose behalf the assign command was executed. + Empty if the assignment happened offline via the repair service. + Must be a valid PartyIdString (as described in ``value.proto``). + + Optional + reassignmentCounter: + type: string + format: uint64 + description: |- + Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases + with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter + equals zero. + + Required + createdEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.CreatedEvent' + description: |- + The offset of this event refers to the offset of the assignment, + while the node_id is the index of within the batch. + + Required + description: Records that a contract has been assigned, and it can be used on the target synchronizer. + com.daml.ledger.api.v2.Command: + type: object + properties: + create: + $ref: '#/definitions/com.daml.ledger.api.v2.CreateCommand' + exercise: + $ref: '#/definitions/com.daml.ledger.api.v2.ExerciseCommand' + exerciseByKey: + $ref: '#/definitions/com.daml.ledger.api.v2.ExerciseByKeyCommand' + createAndExercise: + $ref: '#/definitions/com.daml.ledger.api.v2.CreateAndExerciseCommand' + description: A command can either create a new contract or exercise a choice on an existing contract. + com.daml.ledger.api.v2.Commands: + type: object + properties: + workflowId: + type: string + description: |- + Identifier of the on-ledger workflow that this command is a part of. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + userId: + type: string + description: |- + Uniquely identifies the participant user that issued the command. + Must be a valid UserIdString (as described in ``value.proto``). + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + commandId: + type: string + description: |- + Uniquely identifies the command. + The triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change, + where act_as is interpreted as a set of party names. + The change ID can be used for matching the intended ledger changes with all their completions. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + commands: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Command' + description: |- + Individual elements of this atomic command. Must be non-empty. + + Required: must be non-empty + deduplicationDuration: + type: string + description: |- + 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. + deduplicationOffset: + type: string + format: int64 + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer) or participant begin (zero). + minLedgerTimeAbs: + type: string + format: date-time + description: |- + 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 + minLedgerTimeRel: + type: string + description: |- + 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 + actAs: + type: array + items: + type: string + description: |- + Set of parties on whose behalf the command should be executed. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to act on behalf of each of the given parties. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + readAs: + type: array + items: + type: string + description: |- + 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: can be empty + submissionId: + type: string + description: |- + 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 + disclosedContracts: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.DisclosedContract' + description: |- + Additional contracts used to resolve contract & contract key lookups. + + Optional: can be empty + synchronizerId: + type: string + description: Optional + title: Must be a valid synchronizer id + packageIdSelectionPreference: + type: array + items: + type: string + description: 'Optional: can be empty' + title: |- + The package-id selection preference of the client for resolving + package names and interface instances in command submission and interpretation + prefetchContractKeys: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.PrefetchContractKey' + description: |- + Fetches the contract keys into the caches to speed up the command processing. + Should only contain contract keys that are expected to be resolved during interpretation of the commands. + Keys of disclosed contracts do not need prefetching. + + Optional: can be empty + tapsMaxPasses: + type: integer + format: int64 + description: |- + The maximum number of passes for the Topology-Aware Package Selection (TAPS). + Higher values can increase the chance of successful package selection for routing of interpreted transactions. + If unset, this defaults to the value defined in the participant configuration. + The provided value must not exceed the limit specified in the participant configuration. + + Optional + description: A composite command that groups multiple commands together. + com.daml.ledger.api.v2.Completion: + type: object + properties: + commandId: + type: string + description: |- + The ID of the succeeded or failed command. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + status: + $ref: '#/definitions/google.rpc.Status' + description: |- + Identifies the exact type of the error. + It uses the same format of conveying error details as it is used for the RPC responses of the APIs. + + Optional + updateId: + type: string + description: |- + The update_id of the transaction or reassignment that resulted from the command with command_id. + + Only set for successfully executed commands. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + userId: + type: string + description: |- + The user-id that was used for the submission, as described in ``commands.proto``. + Must be a valid UserIdString (as described in ``value.proto``). + + Required + actAs: + type: array + items: + type: string + description: |- + The set of parties on whose behalf the commands were executed. + Contains the ``act_as`` parties from ``commands.proto`` + filtered to the requesting parties in CompletionStreamRequest. + The order of the parties need not be the same as in the submission. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + submissionId: + type: string + description: |- + The submission ID this completion refers to, as described in ``commands.proto``. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + deduplicationOffset: + type: string + format: int64 + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + + Must be a valid absolute offset (positive integer) or participant begin (zero). + deduplicationDuration: + type: string + description: |- + Specifies the length of the deduplication period. + It is measured in record time of completions. + + Must be non-negative. + traceContext: + $ref: '#/definitions/com.daml.ledger.api.v2.TraceContext' + description: |- + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + title: The Ledger API trace context + offset: + type: string + format: int64 + description: |- + May be used in a subsequent CompletionStreamRequest to resume the consumption of this stream at a later time. + Must be a valid absolute offset (positive integer). + + Required + synchronizerTime: + $ref: '#/definitions/com.daml.ledger.api.v2.SynchronizerTime' + description: |- + - successful/failed transactions: identifies the synchronizer of the transaction + - for successful/failed unassign commands: identifies the source synchronizer + - for successful/failed assign commands: identifies the target synchronizer + + Required + title: |- + The synchronizer along with its record time. + The synchronizer id provided, in case of + paidTrafficCost: + type: string + format: int64 + description: |- + The traffic cost paid by this participant node for the confirmation request + for the submitted command. + + Commands whose execution is rejected before their corresponding + confirmation request is ordered by the synchronizer will report a paid + traffic cost of zero. + If a confirmation request is ordered for a command, but the request fails + (e.g., due to contention with a concurrent contract archival), the traffic + cost is paid and reported on the failed completion for the request. + + If you want to correlate the traffic cost of a successful completion + with the transaction that resulted from the command, you can use the + ``offset`` field to retrieve the transaction using + ``UpdateService.GetUpdateByOffset`` on the same participant node; or alternatively use the ``update_id`` + field to retrieve the transaction using ``UpdateService.GetUpdateById`` on any participant node + that sees the transaction. + + Note: for completions processed before the participant started serving + traffic cost on the Ledger API, this field will be set to zero. + Additionally, the total cost incurred by the submitting node for the submission of the transaction may be greater + than the reported cost, for example if retries were issued due to failed submissions to the synchronizer. + The cost reported here is the one paid for ordering the confirmation request. + + Optional + description: 'A completion represents the status of a submitted command on the ledger: it can be successful or failed.' + com.daml.ledger.api.v2.CompletionStreamRequest: + type: object + properties: + userId: + type: string + description: |- + Only completions of commands submitted with the same user_id will be visible in the stream. + Must be a valid UserIdString (as described in ``value.proto``). + + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + parties: + type: array + items: + type: string + description: |- + Non-empty list of parties whose data should be included. + The stream shows only completions of commands for which at least one of the ``act_as`` parties is in the given set of parties. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + beginExclusive: + type: string + format: int64 + description: |- + This optional field indicates the minimum offset for completions. This can be used to resume an earlier completion stream. + If not set the ledger uses the ledger begin offset instead. + If specified, it must be a valid absolute offset (positive integer) or zero (ledger begin offset). + If the ledger has been pruned, this parameter must be specified and greater than the pruning offset. + + Optional + com.daml.ledger.api.v2.CompletionStreamResponse: + type: object + properties: + completion: + $ref: '#/definitions/com.daml.ledger.api.v2.Completion' + offsetCheckpoint: + $ref: '#/definitions/com.daml.ledger.api.v2.OffsetCheckpoint' + com.daml.ledger.api.v2.CreateAndExerciseCommand: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template of the contract the client wants to create. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + createArguments: + $ref: '#/definitions/com.daml.ledger.api.v2.Record' + description: |- + The arguments required for creating a contract from this template. + + Required + choice: + type: string + description: |- + The name of the choice the client wants to exercise. + Must be a valid NameString (as described in ``value.proto``). + + Required + choiceArgument: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The argument for this choice. + + Required + description: Create a contract and exercise a choice on it in the same transaction. + com.daml.ledger.api.v2.CreateCommand: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template of contract the client wants to create. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + createArguments: + $ref: '#/definitions/com.daml.ledger.api.v2.Record' + description: |- + The arguments required for creating a contract from this template. + + Required + description: Create a new contract instance based on a template. + com.daml.ledger.api.v2.Created: + type: object + properties: + createdEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.CreatedEvent' + description: |- + The event as it appeared in the context of its original update (i.e. daml transaction or + reassignment) on this participant node. You can use its offset and node_id to find the + corresponding update and the node within it. + + Required + synchronizerId: + type: string + description: Required + title: The synchronizer which sequenced the creation of the contract + com.daml.ledger.api.v2.CreatedEvent: + type: object + properties: + offset: + type: string + format: int64 + description: Required + title: |- + The offset of origin, which has contextual meaning, please see description at messages that include a CreatedEvent. + Offsets are managed by the participant nodes. + Transactions can thus NOT be assumed to have the same offsets on different participant nodes. + It is a valid absolute offset (positive integer) + nodeId: + type: integer + format: int32 + description: Required + title: |- + The position of this event in the originating transaction or reassignment. + The origin has contextual meaning, please see description at messages that include a CreatedEvent. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of transactions. + Must be valid node ID (non-negative integer) + contractId: + type: string + description: |- + The ID of the created contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template of the created contract. + The identifier uses the package-id reference format. + + Required + contractKey: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The key of the created contract. + This will be set if and only if ``template_id`` defines a contract key. + + Optional + contractKeyHash: + type: string + format: byte + description: |- + The hash of contract_key. + This will be set if and only if ``template_id`` defines a contract key. + + Optional: can be empty + createArguments: + $ref: '#/definitions/com.daml.ledger.api.v2.Record' + description: |- + The arguments that have been used to create the contract. + + Required + createdEventBlob: + type: string + format: byte + description: |- + Opaque representation of contract create event payload intended for forwarding + to an API server as a contract disclosed as part of a command + submission. + + Optional: can be empty + interfaceViews: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.InterfaceView' + description: |- + - its party in the ``witness_parties`` of this event, + - and which is implemented by the template of this event, + - and which has ``include_interface_view`` set. + + Optional: can be empty + title: |- + Interface views specified in the transaction filter. + Includes an ``InterfaceView`` for each interface for which there is a ``InterfaceFilter`` with + witnessParties: + type: array + items: + type: string + description: |- + The parties that are notified of this event. When a ``CreatedEvent`` + is returned as part of a transaction tree or ledger-effects transaction, this will include all + the parties specified in the ``TransactionFilter`` that are witnesses of the event + (the stakeholders of the contract and all informees of all the ancestors + of this create action that this participant knows about). + If served as part of a ACS delta transaction those will + be limited to all parties specified in the ``TransactionFilter`` that + are stakeholders of the contract (i.e. either signatories or observers). + If the ``CreatedEvent`` is returned as part of an AssignedEvent, + ActiveContract or IncompleteUnassigned (so the event is related to + an assignment or unassignment): this will include all parties of the + ``TransactionFilter`` that are stakeholders of the contract. + + The behavior of reading create events visible to parties not hosted + on the participant node serving the Ledger API is undefined. Concretely, + there is neither a guarantee that the participant node will serve all their + create events on the ACS stream, nor is there a guarantee that matching archive + events are delivered for such create events. + + For most clients this is not a problem, as they only read events for parties + that are hosted on the participant node. If you need to read events + for parties that may not be hosted at all times on the participant node, + subscribe to the ``TopologyEvent``s for that party by setting a corresponding + ``UpdateFormat``. Using these events, query the ACS as-of an offset where the + party is hosted on the participant node, and ignore create events at offsets + where the party is not hosted on the participant node. + + Required: must be non-empty + signatories: + type: array + items: + type: string + description: |- + The signatories for this contract as specified by the template. + + Required: must be non-empty + observers: + type: array + items: + type: string + description: |- + The observers for this contract as specified explicitly by the template or implicitly as choice controllers. + This field never contains parties that are signatories. + + Optional: can be empty + createdAt: + type: string + format: date-time + description: |- + Ledger effective time of the transaction that created the contract. + + Required + packageName: + type: string + description: |- + The package name of the created contract. + + Required + acsDelta: + type: boolean + description: |- + Whether this event would be part of respective ACS_DELTA shaped stream, + and should therefore considered when tracking contract activeness on the client-side. + + Required + representativePackageId: + type: string + description: |- + A package-id present in the participant package store that typechecks the contract's argument. + This may differ from the package-id of the template used to create the contract. + For contracts created before Canton 3.4, this field matches the contract's creation package-id. + + NOTE: Experimental, server internal concept, not for client consumption. Subject to change without notice. + + Required + description: Records that a contract has been created, and choices may now be exercised on it. + com.daml.ledger.api.v2.CryptoKeyFormat: + type: string + enum: + - CRYPTO_KEY_FORMAT_UNSPECIFIED + - CRYPTO_KEY_FORMAT_DER + - CRYPTO_KEY_FORMAT_RAW + - CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO + default: CRYPTO_KEY_FORMAT_UNSPECIFIED + description: |- + - CRYPTO_KEY_FORMAT_DER: ASN.1 + DER encoding + Legacy format no longer used, except for migrations + - CRYPTO_KEY_FORMAT_RAW: Raw encoding of a key + - CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO: ASN.1 + DER-encoding of X.509 SubjectPublicKeyInfo structure: https://datatracker.ietf.org/doc/html/rfc5280#section-4.1 + title: Serialization format for crypto keys and signatures + com.daml.ledger.api.v2.CumulativeFilter: + type: object + properties: + wildcardFilter: + $ref: '#/definitions/com.daml.ledger.api.v2.WildcardFilter' + description: Optional + title: A wildcard filter that matches all templates + interfaceFilter: + $ref: '#/definitions/com.daml.ledger.api.v2.InterfaceFilter' + description: |- + Include an ``InterfaceView`` for every ``InterfaceFilter`` matching a contract. + The ``InterfaceFilter`` instances MUST each use a unique ``interface_id``. + + Optional + templateFilter: + $ref: '#/definitions/com.daml.ledger.api.v2.TemplateFilter' + description: |- + A template for which the data will be included in the + ``create_arguments`` of a matching ``CreatedEvent``. + If a contract is simultaneously selected by a template filter and one or more interface filters, + the corresponding ``include_created_event_blob`` are consolidated using an OR operation. + + Optional + description: |- + A filter that matches all contracts that are either an instance of one of + the ``template_filters`` or that match one of the ``interface_filters``. + com.daml.ledger.api.v2.DisclosedContract: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template id of the contract. + The identifier uses the package-id reference format. + + If provided, used to validate the template id of the contract serialized in the created_event_blob. + + Optional + contractId: + type: string + description: |- + If provided, used to validate the contract id of the contract serialized in the created_event_blob. + + Optional + title: The contract id + createdEventBlob: + type: string + format: byte + description: |- + Opaque byte string containing the complete payload required by the Daml engine + to reconstruct a contract not known to the receiving participant. + + Required: must be non-empty + synchronizerId: + type: string + description: Optional + title: The ID of the synchronizer where the contract is currently assigned + description: |- + An additional contract that is used to resolve + contract & contract key lookups. + com.daml.ledger.api.v2.Enum: + type: object + properties: + enumId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + Omitted from the transaction stream when verbose streaming is not enabled. + Optional when submitting commands. + constructor: + type: string + title: |- + Determines which of the Variant's alternatives is encoded in this message. + Must be a valid NameString. + Required + description: A value with finite set of alternative representations. + com.daml.ledger.api.v2.Event: + type: object + properties: + created: + $ref: '#/definitions/com.daml.ledger.api.v2.CreatedEvent' + description: |- + The event as it appeared in the context of its original daml transaction on this participant node. + In particular, the offset, node_id pair of the daml transaction are preserved. + archived: + $ref: '#/definitions/com.daml.ledger.api.v2.ArchivedEvent' + exercised: + $ref: '#/definitions/com.daml.ledger.api.v2.ExercisedEvent' + description: |- + - ACS delta: events can be CreatedEvent or ArchivedEvent + - ledger effects: events can be CreatedEvent or ExercisedEvent + + In the update service the events are restricted to the events + visible for the parties specified in the transaction filter. Each + event message type below contains a ``witness_parties`` field which + indicates the subset of the requested parties that can see the event + in question. + title: 'Events in transactions can have two primary shapes:' + com.daml.ledger.api.v2.EventFormat: + type: object + properties: + filtersByParty: + type: object + additionalProperties: + $ref: '#/definitions/com.daml.ledger.api.v2.Filters' + description: |- + 1. For **ledger-effects** create and exercise events are returned, for which the witnesses include at least one of + the listed parties and match the per-party filter. + 2. For **transaction and active-contract-set streams** create and archive events are returned for all contracts whose + stakeholders include at least one of the listed parties and match the per-party filter. + + Optional: can be empty + title: |- + Each key must be a valid PartyIdString (as described in ``value.proto``). + The interpretation of the filter depends on the transaction-shape being filtered: + filtersForAnyParty: + $ref: '#/definitions/com.daml.ledger.api.v2.Filters' + description: |- + Wildcard filters that apply to all the parties existing on the participant. The interpretation of the filters is the same + with the per-party filter as described above. + + Optional + verbose: + type: boolean + description: |- + 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 + description: |- + A format for events which defines both which events should be included + and what data should be computed and included for them. + + Note that some of the filtering behavior depends on the `TransactionShape`, + which is expected to be specified alongside usages of `EventFormat`. + com.daml.ledger.api.v2.ExerciseByKeyCommand: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template of contract the client wants to exercise. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + contractKey: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The key of the contract the client wants to exercise upon. + + Required + choice: + type: string + description: Required + title: |- + The name of the choice the client wants to exercise. + Must be a valid NameString (as described in ``value.proto``) + choiceArgument: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The argument for this choice. + + Required + description: Exercise a choice on an existing contract specified by its key. + com.daml.ledger.api.v2.ExerciseCommand: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template or interface of the contract the client wants to exercise. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + To exercise a choice on an interface, specify the interface identifier in the template_id field. + + Required + contractId: + type: string + description: |- + The ID of the contract the client wants to exercise upon. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + choice: + type: string + description: Required + title: |- + The name of the choice the client wants to exercise. + Must be a valid NameString (as described in ``value.proto``) + choiceArgument: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The argument for this choice. + + Required + description: Exercise a choice on an existing contract. + com.daml.ledger.api.v2.ExercisedEvent: + type: object + properties: + offset: + type: string + format: int64 + description: Required + title: |- + The offset of origin. + Offsets are managed by the participant nodes. + Transactions can thus NOT be assumed to have the same offsets on different participant nodes. + It is a valid absolute offset (positive integer) + nodeId: + type: integer + format: int32 + description: Required + title: |- + The position of this event in the originating transaction or reassignment. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of transactions. + Must be valid node ID (non-negative integer) + contractId: + type: string + description: |- + The ID of the target contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + Identifies the template that defines the executed choice. + This template's package-id may differ from the target contract's package-id + if the target contract has been upgraded or downgraded. + + The identifier uses the package-id reference format. + + Required + interfaceId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The interface where the choice is defined, if inherited. + If defined, the identifier uses the package-id reference format. + + Optional + choice: + type: string + description: |- + The choice that was exercised on the target contract. + Must be a valid NameString (as described in ``value.proto``). + + Required + choiceArgument: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The argument of the exercised choice. + + Required + actingParties: + type: array + items: + type: string + description: |- + The parties that exercised the choice. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + consuming: + type: boolean + description: |- + If true, the target contract may no longer be exercised. + + Required + witnessParties: + type: array + items: + type: string + description: |- + 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, + the actors and all informees of all the ancestors of this event this + participant knows about. + If not consuming, the witnesses are the union of the signatories, + the actors and all informees of all the ancestors of this event this + participant knows about. + In both cases the witnesses are limited to the querying parties, or not + limited in case anyParty filters are used. + Note that the actors might not necessarily be observers + and thus stakeholders. 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: must be non-empty + lastDescendantNodeId: + type: integer + format: int32 + description: |- + Specifies the upper boundary of the node ids of the events in the same transaction that appeared as a result of + this ``ExercisedEvent``. This allows unambiguous identification of all the members of the subtree rooted at this + node. A full subtree can be constructed when all descendant nodes are present in the stream. If nodes are heavily + filtered, it is only possible to determine if a node is in a consequent subtree or not. + + Required + exerciseResult: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The result of exercising the choice. + + Optional + packageName: + type: string + description: |- + The package name of the contract. + + Required + implementedInterfaces: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + If the event is consuming, the interfaces implemented by the target template that have been + matched from the interface filter query. + Populated only in case interface filters with include_interface_view set. + + The identifier uses the package-id reference format. + + Optional: can be empty + acsDelta: + type: boolean + description: |- + Whether this event would be part of respective ACS_DELTA shaped stream, + and should therefore considered when tracking contract activeness on the client-side. + + Required + description: Records that a choice has been exercised on a target contract. + com.daml.ledger.api.v2.ExperimentalCommandInspectionService: + type: object + properties: + supported: + type: boolean + title: Required + title: Whether the Ledger API supports command inspection service + com.daml.ledger.api.v2.ExperimentalFeatures: + type: object + properties: + staticTime: + $ref: '#/definitions/com.daml.ledger.api.v2.ExperimentalStaticTime' + title: Optional + commandInspectionService: + $ref: '#/definitions/com.daml.ledger.api.v2.ExperimentalCommandInspectionService' + title: Optional + description: See the feature message definitions for descriptions. + com.daml.ledger.api.v2.ExperimentalStaticTime: + type: object + properties: + supported: + type: boolean + title: Required + description: Ledger is in the static time mode and exposes a time service. + com.daml.ledger.api.v2.FeaturesDescriptor: + type: object + properties: + experimental: + $ref: '#/definitions/com.daml.ledger.api.v2.ExperimentalFeatures' + description: |- + Features under development or features that are used + for ledger implementation testing purposes only. + + Daml applications SHOULD not depend on these in production. + + Required + userManagement: + $ref: '#/definitions/com.daml.ledger.api.v2.UserManagementFeature' + description: |- + 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. + + Required + partyManagement: + $ref: '#/definitions/com.daml.ledger.api.v2.PartyManagementFeature' + description: |- + If set, then the Ledger API server supports party management configurability. + It is recommended that clients query this field to gracefully adjust their behavior to + maximum party page size. + + Required + offsetCheckpoint: + $ref: '#/definitions/com.daml.ledger.api.v2.OffsetCheckpointFeature' + description: Required + title: It contains the timeouts related to the periodic offset checkpoint emission + packageFeature: + $ref: '#/definitions/com.daml.ledger.api.v2.PackageFeature' + description: |- + If set, then the Ledger API server supports package listing + configurability. It is recommended that clients query this field to + gracefully adjust their behavior to maximum package listing page size. + + Required + com.daml.ledger.api.v2.Filters: + type: object + properties: + cumulative: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.CumulativeFilter' + description: |- + Every filter in the cumulative list expands the scope of the resulting stream. Each interface, + template or wildcard filter means additional events that will match the query. + The impact of include_interface_view and include_created_event_blob fields in the filters will + also be accumulated. + A template or an interface SHOULD NOT appear twice in the accumulative field. + A wildcard filter SHOULD NOT be defined more than once in the accumulative field. + If no ``CumulativeFilter`` defined, the default of a single ``WildcardFilter`` with + include_created_event_blob unset is used. + + Optional: can be empty + description: The union of a set of template filters, interface filters, or a wildcard. + com.daml.ledger.api.v2.GenMap: + type: object + properties: + entries: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.GenMap.Entry' + com.daml.ledger.api.v2.GenMap.Entry: + type: object + properties: + key: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + value: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + com.daml.ledger.api.v2.GetActiveContractsPageRequest: + type: object + properties: + activeAtOffset: + type: string + format: int64 + description: |- + The offset at which the snapshot of the active contracts will be computed. + Must be no greater than the current ledger end offset. + Must be greater than or equal to the last pruning offset. + Optional, if defined, it must be a valid absolute offset (positive integer) or ledger begin offset (zero). + If zero, the empty set will be returned. + If not defined, the current ledger end will be used and it will be populated in the response. + + Optional + eventFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.EventFormat' + description: |- + Format of the contract_entries in the result. In case of CreatedEvent the presentation will be of + TRANSACTION_SHAPE_ACS_DELTA. + + Required + maxPageSize: + type: integer + format: int32 + description: |- + The result page will contain at most max_page_size entries of the respective active contract snapshot. + The server might reject max_page_size breaching the server-specified limit. + Optional, if not defined, the default will be determined by the server. + + Optional + pageToken: + type: string + format: byte + description: |- + - are executed on the same participant, + - use the same active_at_offset and event_format, + - and the participant's store was not pruned to after the active_at_offset. + + If not specified, the first page of the active contracts snapshot will be returned. + + Optional: can be empty + title: |- + To get the next page of the active contracts snapshot, the ``page_token`` should be set to the + ``next_page_token`` of the last ``GetActiveContractsPageResponse``. + The page token only works if subsequent requests: + com.daml.ledger.api.v2.GetActiveContractsPageResponse: + type: object + properties: + activeContracts: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.GetActiveContractsResponse' + description: |- + The collection of active contracts for this page response. + + Required: must be non-empty + activeAtOffset: + type: string + format: int64 + description: |- + The active_at_offset which was specified in the request, or the calculated active_at_offset from the actual + ledger end from at the evaluation of the request. + + Required + nextPageToken: + type: string + format: byte + description: |- + If not present this is the last page. If present, this token must be used to get the next page. + + Optional: can be empty + com.daml.ledger.api.v2.GetActiveContractsRequest: + type: object + properties: + activeAtOffset: + type: string + format: int64 + description: |- + The offset at which the snapshot of the active contracts will be computed. + Must be no greater than the current ledger end offset. + Must be greater than or equal to the last pruning offset. + Must be a valid absolute offset (positive integer) or ledger begin offset (zero). + If zero, the empty set will be returned. + + Required + eventFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.EventFormat' + description: |- + Format of the contract_entries in the result. In case of CreatedEvent the presentation will be of + TRANSACTION_SHAPE_ACS_DELTA. + + Required + streamContinuationToken: + type: string + format: byte + description: |- + - subsequent request must be executed on the same participant with the same version of canton, + - subsequent request must have the same active_at_offset, + - subsequent request must have the same event_format + - and the participant must not have been pruned after the active_at_offset. + + If not specified, the whole active contracts snapshot will be returned. + + Optional: can be empty + title: |- + Opaque representation of a continuation token defining a position in the active contracts snapshot. + The prefix of the active contracts snapshot will be omitted up to and including the element from which + the continuation token was read. + To reuse the continuation token from a `GetActiveContractsPageResponse`: + description: |- + If the given offset is different than the ledger end, and there are (un)assignments in-flight at the given offset, + the snapshot may fail with "FAILED_PRECONDITION/PARTICIPANT_PRUNED_DATA_ACCESSED". + Note that it is ok to request acs snapshots for party migration with offsets other than ledger end, because party + migration is not concerned with incomplete (un)assignments. + com.daml.ledger.api.v2.GetActiveContractsResponse: + type: object + properties: + workflowId: + type: string + description: |- + The workflow ID used in command submission which corresponds to the contract_entry. Only set if + the ``workflow_id`` for the command was set. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + activeContract: + $ref: '#/definitions/com.daml.ledger.api.v2.ActiveContract' + description: |- + The contract is active on the assigned synchronizer, meaning: there was an activation event on the given synchronizer ( + created, assigned), which is not followed by a deactivation event (archived, unassigned) on the same + synchronizer, until the active_at_offset. + Since activeness is defined as a per synchronizer concept, it is possible, that a contract is active on one + synchronizer, but already archived on another. + There will be one such message for each synchronizer the contract is active on. + incompleteUnassigned: + $ref: '#/definitions/com.daml.ledger.api.v2.IncompleteUnassigned' + description: |- + Included iff the unassigned event was before or at the active_at_offset, but there was no corresponding + assigned event before or at the active_at_offset. + incompleteAssigned: + $ref: '#/definitions/com.daml.ledger.api.v2.IncompleteAssigned' + description: |- + Important: this message is not indicating that the contract is active on the target synchronizer! + Included iff the assigned event was before or at the active_at_offset, but there was no corresponding + unassigned event before or at the active_at_offset. + streamContinuationToken: + type: string + format: byte + description: |- + Opaque representation of a continuation token which can be used in the request to bypass the already processed part + of the active contracts snapshot. + Only populated for the streaming ``GetActiveContracts`` rpc call. + + Optional: can be empty + com.daml.ledger.api.v2.GetConnectedSynchronizersResponse: + type: object + properties: + connectedSynchronizers: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.GetConnectedSynchronizersResponse.ConnectedSynchronizer' + title: 'Optional: can be empty' + com.daml.ledger.api.v2.GetConnectedSynchronizersResponse.ConnectedSynchronizer: + type: object + properties: + synchronizerAlias: + type: string + description: Required + title: The alias of the synchronizer + synchronizerId: + type: string + description: Required + title: The ID of the synchronizer + permission: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantPermission' + description: |- + The permission on the synchronizer + Set if a party was used in the request, otherwise unspecified. + + Optional + com.daml.ledger.api.v2.GetContractRequest: + type: object + properties: + contractId: + type: string + description: |- + The ID of the contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + queryingParties: + type: array + items: + type: string + description: |- + The list of querying parties + The stakeholders of the referenced contract must have an intersection with any of these parties + to return the result. + If no querying_parties specified, all possible contracts could be returned. + + Optional: can be empty + com.daml.ledger.api.v2.GetContractResponse: + type: object + properties: + createdEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.CreatedEvent' + description: |- + - offset + - node_id + - created_event_blob + - interface_views + - acs_delta + + Required + title: |- + The representative_package_id will be always set to the contract package ID, therefore this endpoint should + not be used to lookup contract which entered the participant via party replication or repair service. + The witnesses field will contain only the querying_parties which are also stakeholders of the contract as well. + The following fields of the created event cannot be populated, so those should not be used / parsed: + com.daml.ledger.api.v2.GetEventsByContractIdRequest: + type: object + properties: + contractId: + type: string + description: |- + The contract id being queried. + + Required + eventFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.EventFormat' + description: |- + Format of the events in the result, the presentation will be of TRANSACTION_SHAPE_ACS_DELTA. + + Required + com.daml.ledger.api.v2.GetEventsByContractIdResponse: + type: object + properties: + created: + $ref: '#/definitions/com.daml.ledger.api.v2.Created' + description: |- + The create event for the contract with the ``contract_id`` given in the request + provided it exists and has not yet been pruned. + + Optional + archived: + $ref: '#/definitions/com.daml.ledger.api.v2.Archived' + description: |- + The archive event for the contract with the ``contract_id`` given in the request + provided such an archive event exists and it has not yet been pruned. + + Optional + com.daml.ledger.api.v2.GetLatestPrunedOffsetsResponse: + type: object + properties: + participantPrunedUpToInclusive: + type: string + format: int64 + description: |- + It will always be a non-negative integer. + If positive, the absolute offset up to which the ledger has been pruned, + disregarding the state of all divulged contracts pruning. + If zero, the ledger has not been pruned yet. + + Optional + allDivulgedContractsPrunedUpToInclusive: + type: string + format: int64 + description: |- + It will always be a non-negative integer. + If positive, the absolute offset up to which all divulged events have been pruned on the ledger. + It can be at or before the ``participant_pruned_up_to_inclusive`` offset. + For more details about all divulged events pruning, + see ``PruneRequest.prune_all_divulged_contracts`` in ``participant_pruning_service.proto``. + If zero, the divulged events have not been pruned yet. + + Optional + com.daml.ledger.api.v2.GetLedgerApiVersionResponse: + type: object + properties: + version: + type: string + description: |- + The version of the ledger API. + + Required + features: + $ref: '#/definitions/com.daml.ledger.api.v2.FeaturesDescriptor' + description: |- + 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. + + Required + com.daml.ledger.api.v2.GetLedgerEndResponse: + type: object + properties: + offset: + type: string + format: int64 + description: |- + It will always be a non-negative integer. + If zero, the participant view of the ledger is empty. + If positive, the absolute offset of the ledger as viewed by the participant. + + Optional + com.daml.ledger.api.v2.GetPackageResponse: + type: object + properties: + hashFunction: + $ref: '#/definitions/com.daml.ledger.api.v2.HashFunction' + description: |- + The hash function we use to calculate the hash. + + Required + archivePayload: + type: string + format: byte + description: |- + Contains a ``daml_lf`` ArchivePayload. See further details in ``daml_lf.proto``. + + Required: must be non-empty + hash: + type: string + description: |- + The hash of the archive payload, can also used as a ``package_id``. + Must be a valid PackageIdString (as described in ``value.proto``). + + Required + com.daml.ledger.api.v2.GetPackageStatusResponse: + type: object + properties: + packageStatus: + $ref: '#/definitions/com.daml.ledger.api.v2.PackageStatus' + description: |- + The status of the package. + + Required + com.daml.ledger.api.v2.GetUpdateByIdRequest: + type: object + properties: + updateId: + type: string + description: |- + The ID of a particular update. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + updateFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.UpdateFormat' + description: |- + The format for the update. + + Required + com.daml.ledger.api.v2.GetUpdateByOffsetRequest: + type: object + properties: + offset: + type: string + format: int64 + description: |- + The offset of the update being looked up. + Must be a valid absolute offset (positive integer). + + Required + updateFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.UpdateFormat' + description: |- + The format for the update. + + Required + com.daml.ledger.api.v2.GetUpdateResponse: + type: object + properties: + transaction: + $ref: '#/definitions/com.daml.ledger.api.v2.Transaction' + reassignment: + $ref: '#/definitions/com.daml.ledger.api.v2.Reassignment' + topologyTransaction: + $ref: '#/definitions/com.daml.ledger.api.v2.TopologyTransaction' + com.daml.ledger.api.v2.GetUpdatesPageRequest: + type: object + properties: + beginOffsetExclusive: + type: string + format: int64 + description: |- + Exclusive lower bound offset of the requested ledger section (non-negative integer). + The response page will only contain updates whose offset is strictly greater than this. + If set to zero or not defined, the lower bound is set to the actual pruning offset or to the beginning of the + ledger if the participant was not pruned yet. + If set to positive and the ledger has been pruned, this parameter must be greater or equal than the pruning offset. + + Optional + endOffsetInclusive: + type: string + format: int64 + description: |- + Inclusive upper bound offset of the requested ledger section. + If specified the response will only contain updates whose offset is less than or equal to this. + If not specified response will only contain updates whose offset is less than the current ledger-end. + + Optional + maxPageSize: + type: integer + format: int32 + description: |- + The result page will contain the first max_page_size Updates of all matching updates. + The server may reject queries with max_page_size above server specified limits. + If not specified, the default max_page_size is determined by the server. + + Optional + updateFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.UpdateFormat' + title: Required + descendingOrder: + type: boolean + description: |- + If set, the page will populate the elements in descending order starting from the end_offset_inclusive. + + Optional + pageToken: + type: string + format: byte + description: |- + - be executed on the same participant with the same version of canton, + - have the same begin_offset_exclusive, + - have the same end_offset_inclusive, + - have the same update_format and + - have the same descending_order. + + If not specified, the first page of updates will be returned. + + Optional: can be empty + title: |- + To get the next page of updates, the ``page_token`` should be set to the + ``next_page_token`` of the last ``GetUpdatesPageResponse``. + To achieve correct paging: subsequent requests must + com.daml.ledger.api.v2.GetUpdatesPageResponse: + type: object + properties: + updates: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.GetUpdateResponse' + description: |- + The first max_page_size updates that match the filter in the request. + In case descending_order was selected, the order of the updates is in reversed offset order. + + Optional: can be empty + lowestPageOffsetExclusive: + type: string + format: int64 + description: |- + Represents the lower bound of this page. + + Required + highestPageOffsetInclusive: + type: string + format: int64 + description: |- + Represents the upper bound of the page. + + Required + nextPageToken: + type: string + format: byte + description: |- + If the value is not populated, this is the last page. + If the value is populated, this token can be used to get the next page. + If the original ``GetFirstUpdatePageRequest`` end_offset_inclusive was not specified and the request uses + ascending order, then this token will always be populated, so you can use it to "tail" the ledger by + repeatedly polling with the new page token returned. + + Optional: can be empty + com.daml.ledger.api.v2.GetUpdatesRequest: + type: object + properties: + beginExclusive: + type: string + format: int64 + title: Required + endInclusive: + type: string + format: int64 + description: |- + - the descending_order must not be selected, + - the stream will not terminate. + + Optional + title: |- + Inclusive higher bound offset of the requested ledger section. + If specified the response will only contain transactions whose offset is less than or equal to this. + If not specified, + updateFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.UpdateFormat' + description: Required + title: The update format for this request + descendingOrder: + type: boolean + description: |- + If set, the stream will populate the elements in descending order. + + Optional + description: |- + Exclusive lower bound offset of the requested ledger section (non-negative integer). + The response will only contain transactions whose offset is strictly greater than this. + If set to zero, the lower bound is set to the beginning of the ledger. + If the participant has been pruned, this parameter must be greater or equal than the pruning offset. + com.daml.ledger.api.v2.GetUpdatesResponse: + type: object + properties: + transaction: + $ref: '#/definitions/com.daml.ledger.api.v2.Transaction' + reassignment: + $ref: '#/definitions/com.daml.ledger.api.v2.Reassignment' + offsetCheckpoint: + $ref: '#/definitions/com.daml.ledger.api.v2.OffsetCheckpoint' + topologyTransaction: + $ref: '#/definitions/com.daml.ledger.api.v2.TopologyTransaction' + com.daml.ledger.api.v2.HashFunction: + type: string + enum: + - HASH_FUNCTION_SHA256 + default: HASH_FUNCTION_SHA256 + com.daml.ledger.api.v2.Identifier: + type: object + properties: + packageId: + type: string + description: |- + Generally, the identifier of the Daml package that contains the entity. + When encoding a package-id, it must be a valid PackageIdString. + + The field is overloaded to also be able to contain the package-name of the Daml package. + This is supported if the entity referenced is either an interface or template. + When representing the Daml package-name, the encoding is of form `#` + where `#` (not a valid package-id character) + is used as a discriminator for signalling a package-name encoding. + + Required + moduleName: + type: string + title: |- + The dot-separated module name of the identifier. + Required + entityName: + type: string + title: |- + The dot-separated name of the entity (e.g. record, template, ...) within the module. + Required + description: |- + - if a Daml package-id is encoded in the package_id field, it is referred to as using a "package-id reference format" + - if a Daml package-name is encoded in the package_id field, it is referred to as using a "package-name reference format" + title: |- + Unique identifier of an entity. + Throughout this API, the following terminology is being used: + com.daml.ledger.api.v2.IncompleteAssigned: + type: object + properties: + assignedEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.AssignedEvent' + title: Required + com.daml.ledger.api.v2.IncompleteUnassigned: + type: object + properties: + createdEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.CreatedEvent' + description: |- + The event as it appeared in the context of its last activation update (i.e. daml transaction or + reassignment). In particular, the last activation offset, node_id pair is preserved. + The last activation update is the most recent update created or assigned this contract on synchronizer_id synchronizer before + the unassigned_event. + The offset of the CreatedEvent might point to an already pruned update, therefore it cannot necessarily be used + for lookups. + + Required + unassignedEvent: + $ref: '#/definitions/com.daml.ledger.api.v2.UnassignedEvent' + title: Required + com.daml.ledger.api.v2.InterfaceFilter: + type: object + properties: + interfaceId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The interface that a matching contract must implement. + The ``interface_id`` needs to be valid: corresponding interface should be defined in + one of the available packages at the time of the query. + Both package-name and package-id reference formats for the identifier are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + includeInterfaceView: + type: boolean + description: |- + Whether to include the interface view on the contract in the returned ``CreatedEvent``. + Use this to access contract data in a uniform manner in your API client. + + Optional + includeCreatedEventBlob: + type: boolean + description: |- + Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``. + Use this to access the contract create event payload in your API client + for submitting it as a disclosed contract with future commands. + + Optional + description: This filter matches contracts that implement a specific interface. + com.daml.ledger.api.v2.InterfaceView: + type: object + properties: + interfaceId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The interface implemented by the matched event. + The identifier uses the package-id reference format. + + Required + viewStatus: + $ref: '#/definitions/google.rpc.Status' + description: |- + Whether the view was successfully computed, and if not, + the reason for the error. The error is reported using the same rules + for error codes and messages as the errors returned for API requests. + + Required + viewValue: + $ref: '#/definitions/com.daml.ledger.api.v2.Record' + description: |- + The value of the interface's view method on this event. + Set if it was requested in the ``InterfaceFilter`` and it could be + successfully computed. + + Optional + implementationPackageId: + type: string + description: |- + The package defining the interface implementation used to compute the view. + Can be different from the package that was used to create the contract itself, + as the contract arguments can be upgraded or downgraded using smart-contract upgrading + as part of computing the interface view. + Populated if the view computation is successful, otherwise empty. + + Optional + description: View of a create event matched by an interface filter. + com.daml.ledger.api.v2.List: + type: object + properties: + elements: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: |- + The elements must all be of the same concrete value type. + Optional + description: A homogenous collection of values. + com.daml.ledger.api.v2.ListPackagesResponse: + type: object + properties: + packageIds: + type: array + items: + type: string + description: |- + The IDs of all Daml-LF packages supported by the server. + Each element must be a valid PackageIdString (as described in ``value.proto``). + + Required: must be non-empty + com.daml.ledger.api.v2.ListVettedPackagesRequest: + type: object + properties: + packageMetadataFilter: + $ref: '#/definitions/com.daml.ledger.api.v2.PackageMetadataFilter' + description: |- + The package metadata filter the returned vetted packages set must satisfy. + + Optional + topologyStateFilter: + $ref: '#/definitions/com.daml.ledger.api.v2.TopologyStateFilter' + description: |- + The topology filter the returned vetted packages set must satisfy. + + Optional + pageToken: + type: string + description: |- + Pagination token to determine the specific page to fetch. Using the token + guarantees that ``VettedPackages`` on a subsequent page are all greater + (``VettedPackages`` are sorted by synchronizer ID then participant ID) than + the last ``VettedPackages`` on a previous page. + + The server does not store intermediate results between calls chained by a + series of page tokens. As a consequence, if new vetted packages are being + added and a page is requested twice using the same token, more packages can + be returned on the second call. + + Leave unspecified (i.e. as empty string) to fetch the first page. + + Optional + pageSize: + type: integer + format: int64 + description: |- + Maximum number of ``VettedPackages`` results to return in a single page. + + If the page_size is unspecified (i.e. left as 0), the server will decide + the number of results to be returned. + + If the page_size exceeds the maximum supported by the server, an + error will be returned. + + To obtain the server's maximum consult the PackageService descriptor + available in the VersionService. + + Optional + com.daml.ledger.api.v2.ListVettedPackagesResponse: + type: object + properties: + vettedPackages: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.VettedPackages' + description: |- + All ``VettedPackages`` that contain at least one ``VettedPackage`` matching + both a ``PackageMetadataFilter`` and a ``TopologyStateFilter``. + Sorted by synchronizer_id then participant_id. + + Optional: can be empty + nextPageToken: + type: string + description: |- + Pagination token to retrieve the next page. + Empty string if there are no further results. + + Optional + com.daml.ledger.api.v2.OffsetCheckpoint: + type: object + properties: + offset: + type: string + format: int64 + description: |- + The participant's offset, the details of the offset field are described in ``community/ledger-api/README.md``. + Must be a valid absolute offset (positive integer). + + Required + synchronizerTimes: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.SynchronizerTime' + description: |- + The times associated with each synchronizer at this offset. + + Optional: can be empty + description: |- + - detect time out of commands. + - provide an offset which can be used to restart consumption. + title: 'OffsetCheckpoints may be used to:' + com.daml.ledger.api.v2.OffsetCheckpointFeature: + type: object + properties: + maxOffsetCheckpointEmissionDelay: + type: string + description: Required + title: The maximum delay to emmit a new OffsetCheckpoint if it exists + com.daml.ledger.api.v2.Optional: + type: object + properties: + value: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: optional + description: |- + 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. + com.daml.ledger.api.v2.PackageFeature: + type: object + properties: + maxVettedPackagesPageSize: + type: integer + format: int32 + description: |- + The maximum number of vetted packages the server can return in a single + response (page) when listing them. + + Required + com.daml.ledger.api.v2.PackageMetadataFilter: + type: object + properties: + packageIds: + type: array + items: + type: string + description: |- + If this list is non-empty, any vetted package with a package ID in this + list will match the filter. + + Optional: can be empty + packageNamePrefixes: + type: array + items: + type: string + description: |- + If this list is non-empty, any vetted package with a name matching at least + one prefix in this list will match the filter. + + Optional: can be empty + description: |- + Filter the VettedPackages by package metadata. + + A PackageMetadataFilter without package_ids and without package_name_prefixes + matches any vetted package. + + Non-empty fields specify candidate values of which at least one must match. + If both fields are set, then a candidate is returned if it matches one of the fields. + com.daml.ledger.api.v2.PackageReference: + type: object + properties: + packageId: + type: string + title: Required + packageName: + type: string + title: Required + packageVersion: + type: string + title: Required + com.daml.ledger.api.v2.PackageStatus: + type: string + enum: + - PACKAGE_STATUS_UNSPECIFIED + - PACKAGE_STATUS_REGISTERED + default: PACKAGE_STATUS_UNSPECIFIED + description: |2- + - PACKAGE_STATUS_UNSPECIFIED: The server is not aware of such a package. + - PACKAGE_STATUS_REGISTERED: The server is able to execute Daml commands operating on this package. + com.daml.ledger.api.v2.ParticipantAuthorizationAdded: + type: object + properties: + partyId: + type: string + title: Required + participantId: + type: string + title: Required + participantPermission: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantPermission' + title: Required + com.daml.ledger.api.v2.ParticipantAuthorizationChanged: + type: object + properties: + partyId: + type: string + title: Required + participantId: + type: string + title: Required + participantPermission: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantPermission' + title: Required + com.daml.ledger.api.v2.ParticipantAuthorizationOnboarding: + type: object + properties: + partyId: + type: string + title: Required + participantId: + type: string + title: Required + participantPermission: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantPermission' + title: Required + com.daml.ledger.api.v2.ParticipantAuthorizationRevoked: + type: object + properties: + partyId: + type: string + title: Required + participantId: + type: string + title: Required + com.daml.ledger.api.v2.ParticipantAuthorizationTopologyFormat: + type: object + properties: + parties: + type: array + items: + type: string + description: |- + List of parties for which the topology transactions should be sent. + Empty means: for all parties. + + Optional: can be empty + description: A format specifying which participant authorization topology transactions to include and how to render them. + com.daml.ledger.api.v2.ParticipantPermission: + type: string + enum: + - PARTICIPANT_PERMISSION_UNSPECIFIED + - PARTICIPANT_PERMISSION_SUBMISSION + - PARTICIPANT_PERMISSION_CONFIRMATION + - PARTICIPANT_PERMISSION_OBSERVATION + default: PARTICIPANT_PERMISSION_UNSPECIFIED + description: |- + Enum indicating the permission level that the participant has for the party + whose connected synchronizers are being listed. + + - PARTICIPANT_PERMISSION_CONFIRMATION: participant can only confirm transactions + - PARTICIPANT_PERMISSION_OBSERVATION: participant can only observe transactions + com.daml.ledger.api.v2.PartyManagementFeature: + type: object + properties: + maxPartiesPageSize: + type: integer + format: int32 + description: |- + The maximum number of parties the server can return in a single response (page). + + Required + com.daml.ledger.api.v2.PrefetchContractKey: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template of contract the client wants to prefetch. + Both package-name and package-id reference identifier formats for the template-id are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + contractKey: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + description: |- + The key of the contract the client wants to prefetch. + + Required + title: Preload contracts + com.daml.ledger.api.v2.PriorTopologySerial: + type: object + properties: + prior: + type: integer + format: int64 + description: Previous transaction's serial. + noPrior: + type: object + properties: {} + description: No previous transaction exists. + description: |- + The serial of last ``VettedPackages`` topology transaction on a given + participant and synchronizer. + com.daml.ledger.api.v2.Reassignment: + type: object + properties: + updateId: + type: string + description: |- + Assigned by the server. Useful for correlating logs. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + commandId: + type: string + description: |- + The ID of the command which resulted in this reassignment. Missing for everyone except the submitting party on the submitting participant. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + workflowId: + type: string + description: |- + The workflow ID used in reassignment command submission. Only set if the ``workflow_id`` for the command was set. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + offset: + type: string + format: int64 + description: |- + The participant's offset. The details of this field are described in ``community/ledger-api/README.md``. + Must be a valid absolute offset (positive integer). + + Required + events: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.ReassignmentEvent' + description: |- + The collection of reassignment events. + + Required: must be non-empty + traceContext: + $ref: '#/definitions/com.daml.ledger.api.v2.TraceContext' + description: |- + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + title: Ledger API trace context + recordTime: + type: string + format: date-time + description: |- + The time at which the reassignment was recorded. The record time refers to the source/target + synchronizer for an unassign/assign event respectively. + + Required + synchronizerId: + type: string + description: |- + A valid synchronizer id. + Identifies the synchronizer that synchronized this Reassignment. + + Required + paidTrafficCost: + type: string + format: int64 + description: |- + The traffic cost that this participant node paid for the corresponding (un)assignment request. + + Not set for transactions that were + - initiated by another participant + - initiated offline via the repair service + - processed before the participant started serving traffic cost on the Ledger API + - returned as part of a query filtering for a non submitting party + + Optional + description: Complete view of an on-ledger reassignment. + com.daml.ledger.api.v2.ReassignmentCommand: + type: object + properties: + unassignCommand: + $ref: '#/definitions/com.daml.ledger.api.v2.UnassignCommand' + assignCommand: + $ref: '#/definitions/com.daml.ledger.api.v2.AssignCommand' + com.daml.ledger.api.v2.ReassignmentCommands: + type: object + properties: + workflowId: + type: string + description: |- + Identifier of the on-ledger workflow that this command is a part of. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + userId: + type: string + description: |- + Uniquely identifies the participant user that issued the command. + Must be a valid UserIdString (as described in ``value.proto``). + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + commandId: + type: string + description: |- + Uniquely identifies the command. + The triple (user_id, submitter, command_id) constitutes the change ID for the intended ledger change. + The change ID can be used for matching the intended ledger changes with all their completions. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + submitter: + type: string + description: |- + Party on whose behalf the command should be executed. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to act on behalf of the given party. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required + submissionId: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + If omitted, the participant or the committer may set a value of their choice. + + Optional + commands: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.ReassignmentCommand' + description: |- + Individual elements of this reassignment. Must be non-empty. + + Required: must be non-empty + com.daml.ledger.api.v2.ReassignmentEvent: + type: object + properties: + unassigned: + $ref: '#/definitions/com.daml.ledger.api.v2.UnassignedEvent' + assigned: + $ref: '#/definitions/com.daml.ledger.api.v2.AssignedEvent' + com.daml.ledger.api.v2.Record: + type: object + properties: + recordId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + Omitted from the transaction stream when verbose streaming is not enabled. + Optional when submitting commands. + fields: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.RecordField' + title: |- + The nested values of the record. + Required + description: Contains nested values. + com.daml.ledger.api.v2.RecordField: + type: object + properties: + label: + type: string + description: |- + - 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 + title: |- + When reading a transaction stream, it's omitted if verbose streaming is not enabled. + When submitting a command, it's optional: + value: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: |- + A nested value of a record. + Required + description: A named nested value within a record. + com.daml.ledger.api.v2.Signature: + type: object + properties: + format: + $ref: '#/definitions/com.daml.ledger.api.v2.SignatureFormat' + title: Required + signature: + type: string + format: byte + title: 'Required: must be non-empty' + signedBy: + type: string + description: |- + The fingerprint/id of the keypair used to create this signature and needed to verify. + + Required + signingAlgorithmSpec: + $ref: '#/definitions/com.daml.ledger.api.v2.SigningAlgorithmSpec' + description: Required + title: The signing algorithm specification used to produce this signature + com.daml.ledger.api.v2.SignatureFormat: + type: string + enum: + - SIGNATURE_FORMAT_UNSPECIFIED + - SIGNATURE_FORMAT_RAW + - SIGNATURE_FORMAT_DER + - SIGNATURE_FORMAT_CONCAT + - SIGNATURE_FORMAT_SYMBOLIC + default: SIGNATURE_FORMAT_UNSPECIFIED + title: |- + - SIGNATURE_FORMAT_RAW: Signature scheme specific signature format + Legacy format no longer used, except for migrations + - SIGNATURE_FORMAT_DER: ASN.1 + DER-encoding of the `r` and `s` integers, as defined in https://datatracker.ietf.org/doc/html/rfc3279#section-2.2.3 + Used for ECDSA signatures + - SIGNATURE_FORMAT_CONCAT: Concatenation of the integers `r || s` in little-endian form, as defined in https://datatracker.ietf.org/doc/html/rfc8032#section-3.3 + Note that this is different from the format defined in IEEE P1363, which uses concatenation in big-endian form. + Used for EdDSA signatures + - SIGNATURE_FORMAT_SYMBOLIC: Symbolic crypto, must only be used for testing + com.daml.ledger.api.v2.SigningAlgorithmSpec: + type: string + enum: + - SIGNING_ALGORITHM_SPEC_UNSPECIFIED + - SIGNING_ALGORITHM_SPEC_ED25519 + - SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_256 + - SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_384 + default: SIGNING_ALGORITHM_SPEC_UNSPECIFIED + title: |- + - SIGNING_ALGORITHM_SPEC_ED25519: EdDSA Signature based on Curve25519 with SHA-512 + http://ed25519.cr.yp.to/ + - SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_256: Elliptic Curve Digital Signature Algorithm with SHA256 + - SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_384: Elliptic Curve Digital Signature Algorithm with SHA384 + com.daml.ledger.api.v2.SigningKeySpec: + type: string + enum: + - SIGNING_KEY_SPEC_UNSPECIFIED + - SIGNING_KEY_SPEC_EC_CURVE25519 + - SIGNING_KEY_SPEC_EC_P256 + - SIGNING_KEY_SPEC_EC_P384 + - SIGNING_KEY_SPEC_EC_SECP256K1 + default: SIGNING_KEY_SPEC_UNSPECIFIED + title: |- + - SIGNING_KEY_SPEC_EC_CURVE25519: Elliptic Curve Key from Curve25519 + as defined in http://ed25519.cr.yp.to/ + - SIGNING_KEY_SPEC_EC_P256: Elliptic Curve Key from the NIST P-256 curve (aka secp256r1) + as defined in https://doi.org/10.6028/NIST.FIPS.186-4 + - SIGNING_KEY_SPEC_EC_P384: Elliptic Curve Key from the NIST P-384 curve (aka secp384r1) + as defined in https://doi.org/10.6028/NIST.FIPS.186-4 + - SIGNING_KEY_SPEC_EC_SECP256K1: Elliptic Curve Key from SECG P256k1 curve (aka secp256k1) + commonly used in bitcoin and ethereum + as defined in https://www.secg.org/sec2-v2.pdf + com.daml.ledger.api.v2.SigningPublicKey: + type: object + properties: + format: + $ref: '#/definitions/com.daml.ledger.api.v2.CryptoKeyFormat' + description: Required + title: The serialization format of the public key + keyData: + type: string + format: byte + description: 'Required: must be non-empty' + title: Serialized public key in the format specified above + keySpec: + $ref: '#/definitions/com.daml.ledger.api.v2.SigningKeySpec' + description: Required + title: The key specification + com.daml.ledger.api.v2.SubmitAndWaitForReassignmentRequest: + type: object + properties: + reassignmentCommands: + $ref: '#/definitions/com.daml.ledger.api.v2.ReassignmentCommands' + description: |- + The reassignment commands to be submitted. + + Required + eventFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.EventFormat' + description: |- + If no event_format provided, the result will contain no events. + The events in the result, will take shape TRANSACTION_SHAPE_ACS_DELTA. + + Optional + description: This reassignment is executed as a single atomic update. + com.daml.ledger.api.v2.SubmitAndWaitForReassignmentResponse: + type: object + properties: + reassignment: + $ref: '#/definitions/com.daml.ledger.api.v2.Reassignment' + description: |- + The reassignment that resulted from the submitted reassignment command. + The reassignment might contain no events (request conditions result in filtering out all of them). + + Required + com.daml.ledger.api.v2.SubmitAndWaitForTransactionRequest: + type: object + properties: + commands: + $ref: '#/definitions/com.daml.ledger.api.v2.Commands' + description: |- + The commands to be submitted. + + Required + transactionFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.TransactionFormat' + description: |- + If no ``transaction_format`` is provided, a default will be used where ``transaction_shape`` is set to + TRANSACTION_SHAPE_ACS_DELTA, ``event_format`` is defined with ``filters_by_party`` containing wildcard-template + filter for all original ``act_as`` and ``read_as`` parties and the ``verbose`` flag is set. + + Optional + description: These commands are executed as a single atomic transaction. + com.daml.ledger.api.v2.SubmitAndWaitForTransactionResponse: + type: object + properties: + transaction: + $ref: '#/definitions/com.daml.ledger.api.v2.Transaction' + description: |- + The transaction that resulted from the submitted command. + The transaction might contain no events (request conditions result in filtering out all of them). + + Required + com.daml.ledger.api.v2.SubmitAndWaitResponse: + type: object + properties: + updateId: + type: string + description: |- + The id of the transaction that resulted from the submitted command. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + completionOffset: + type: string + format: int64 + description: |- + The details of the offset field are described in ``community/ledger-api/README.md``. + + Required + com.daml.ledger.api.v2.SubmitReassignmentRequest: + type: object + properties: + reassignmentCommands: + $ref: '#/definitions/com.daml.ledger.api.v2.ReassignmentCommands' + description: |- + The reassignment command to be submitted. + + Required + com.daml.ledger.api.v2.SubmitReassignmentResponse: + type: object + com.daml.ledger.api.v2.SubmitResponse: + type: object + com.daml.ledger.api.v2.SynchronizerTime: + type: object + properties: + synchronizerId: + type: string + description: |- + The id of the synchronizer. + + Required + recordTime: + type: string + format: date-time + description: |- + All commands with a maximum record time below this value MUST be considered lost if their completion has not arrived before this checkpoint. + + Required + com.daml.ledger.api.v2.TemplateFilter: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + A template for which the payload should be included in the response. + The ``template_id`` needs to be valid: corresponding template should be defined in + one of the available packages at the time of the query. + Both package-name and package-id reference formats for the identifier are supported. + Note: The package-id reference identifier format is deprecated. We plan to end support for this format in version 3.4. + + Required + includeCreatedEventBlob: + type: boolean + description: |- + Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``. + Use this to access the contract event payload in your API client + for submitting it as a disclosed contract with future commands. + + Optional + description: This filter matches contracts of a specific template. + com.daml.ledger.api.v2.TextMap: + type: object + properties: + entries: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.TextMap.Entry' + com.daml.ledger.api.v2.TextMap.Entry: + type: object + properties: + key: + type: string + value: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + com.daml.ledger.api.v2.TopologyEvent: + type: object + properties: + participantAuthorizationChanged: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantAuthorizationChanged' + participantAuthorizationRevoked: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantAuthorizationRevoked' + participantAuthorizationAdded: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantAuthorizationAdded' + participantAuthorizationOnboarding: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantAuthorizationOnboarding' + com.daml.ledger.api.v2.TopologyFormat: + type: object + properties: + includeParticipantAuthorizationEvents: + $ref: '#/definitions/com.daml.ledger.api.v2.ParticipantAuthorizationTopologyFormat' + description: |- + Include participant authorization topology events in streams. + If unset, no participant authorization topology events are emitted in the stream. + + Optional + description: A format specifying which topology transactions to include and how to render them. + com.daml.ledger.api.v2.TopologyStateFilter: + type: object + properties: + participantIds: + type: array + items: + type: string + description: |- + If this list is non-empty, only vetted packages hosted on participants + listed in this field match the filter. + Query the current Ledger API's participant's ID via the public + ``GetParticipantId`` command in ``PartyManagementService``. + + Optional: can be empty + synchronizerIds: + type: array + items: + type: string + description: |- + If this list is non-empty, only vetted packages from the topology state of + the synchronizers in this list match the filter. + + Optional: can be empty + description: |- + Filter the vetted packages by the participant and synchronizer that they are + hosted on. + + Empty fields are ignored, such that a ``TopologyStateFilter`` without + participant_ids and without synchronizer_ids matches a vetted package hosted + on any participant and synchronizer. + + Non-empty fields specify candidate values of which at least one must match. + If both fields are set then at least one candidate value must match from each + field. + com.daml.ledger.api.v2.TopologyTransaction: + type: object + properties: + updateId: + type: string + description: |- + Assigned by the server. Useful for correlating logs. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + offset: + type: string + format: int64 + description: |- + The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. + It is a valid absolute offset (positive integer). + + Required + synchronizerId: + type: string + description: |- + A valid synchronizer id. + Identifies the synchronizer that synchronized the topology transaction. + + Required + recordTime: + type: string + format: date-time + description: |- + The time at which the changes in the topology transaction become effective. There is a small delay between a + topology transaction being sequenced and the changes it contains becoming effective. Topology transactions appear + in order relative to a synchronizer based on their effective time rather than their sequencing time. + + Required + events: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.TopologyEvent' + description: |- + A non-empty list of topology events. + + Required: must be non-empty + traceContext: + $ref: '#/definitions/com.daml.ledger.api.v2.TraceContext' + description: |- + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + title: Ledger API trace context + com.daml.ledger.api.v2.TraceContext: + type: object + properties: + traceparent: + type: string + description: Optional + title: https://www.w3.org/TR/trace-context/ + tracestate: + type: string + title: Optional + com.daml.ledger.api.v2.Transaction: + type: object + properties: + updateId: + type: string + description: |- + Assigned by the server. Useful for correlating logs. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + commandId: + type: string + description: |- + 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 + workflowId: + type: string + description: |- + The workflow ID used in command submission. + Must be a valid LedgerString (as described in ``value.proto``). + + Optional + effectiveAt: + type: string + format: date-time + description: |- + Ledger effective time. + + Required + events: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Event' + description: |- + - ``CreatedEvent`` or ``ArchivedEvent`` in case of ACS_DELTA transaction shape + - ``CreatedEvent`` or ``ExercisedEvent`` in case of LEDGER_EFFECTS transaction shape + + Required: must be non-empty + title: |- + The collection of events. + Contains: + offset: + type: string + format: int64 + description: |- + The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. + It is a valid absolute offset (positive integer). + + Required + synchronizerId: + type: string + description: |- + A valid synchronizer id. + Identifies the synchronizer that synchronized the transaction. + + Required + traceContext: + $ref: '#/definitions/com.daml.ledger.api.v2.TraceContext' + description: |- + The trace context transported in this message corresponds to the trace context supplied + by the client application in a HTTP2 header of the original command submission. + We typically use a header to transfer this type of information. Here we use message + body, because it is used in gRPC streams which do not support per message headers. + This field will be populated with the trace context contained in the original submission. + If that was not provided, a unique ledger-api-server generated trace context will be used + instead. + + Optional + title: Ledger API trace context + recordTime: + type: string + format: date-time + description: |- + The time at which the transaction was recorded. The record time refers to the synchronizer + which synchronized the transaction. + + Required + externalTransactionHash: + type: string + format: byte + description: |- + For transaction externally signed, contains the external transaction hash + signed by the external party. Can be used to correlate an external submission with a committed transaction. + + Optional: can be empty + paidTrafficCost: + type: string + format: int64 + description: |- + The traffic cost that this participant node paid for the confirmation + request for this transaction. + + Not set for transactions that were + - initiated by another participant + - initiated offline via the repair service + - processed before the participant started serving traffic cost on the Ledger API + - returned as part of a query filtering for a non submitting party + + Optional + description: Filtered view of an on-ledger transaction's create and archive events. + com.daml.ledger.api.v2.TransactionFormat: + type: object + properties: + eventFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.EventFormat' + title: Required + transactionShape: + $ref: '#/definitions/com.daml.ledger.api.v2.TransactionShape' + description: |- + What transaction shape to use for interpreting the filters of the event format. + + Required + description: |- + A format that specifies what events to include in Daml transactions + and what data to compute and include for them. + com.daml.ledger.api.v2.TransactionShape: + type: string + enum: + - TRANSACTION_SHAPE_UNSPECIFIED + - TRANSACTION_SHAPE_ACS_DELTA + - TRANSACTION_SHAPE_LEDGER_EFFECTS + default: TRANSACTION_SHAPE_UNSPECIFIED + description: |- + Event shape for Transactions. + Shapes are exclusive and only one of them can be defined in queries. + + - TRANSACTION_SHAPE_UNSPECIFIED: Following official proto3 convention, not intended for actual use. + - TRANSACTION_SHAPE_ACS_DELTA: Transaction shape that is sufficient to maintain an accurate ACS view. + The field witness_parties in events are populated as stakeholders, transaction filter will apply accordingly. + This translates to create and archive events. + - TRANSACTION_SHAPE_LEDGER_EFFECTS: Transaction shape that allows maintaining an ACS and also conveys detailed information about + all exercises. + The field witness_parties in events are populated as cumulative informees, transaction filter will apply accordingly. + This translates to create, consuming exercise and non-consuming exercise. + com.daml.ledger.api.v2.UnassignCommand: + type: object + properties: + contractId: + type: string + description: |- + The ID of the contract the client wants to unassign. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + source: + type: string + description: Required + title: |- + The ID of the source synchronizer + Must be a valid synchronizer id + target: + type: string + description: Required + title: |- + The ID of the target synchronizer + Must be a valid synchronizer id + title: Unassign a contract + com.daml.ledger.api.v2.UnassignedEvent: + type: object + properties: + reassignmentId: + type: string + description: |- + The ID of the unassignment. This needs to be used as an input for a assign ReassignmentCommand. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + contractId: + type: string + description: |- + The ID of the reassigned contract. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The template of the reassigned contract. + The identifier uses the package-id reference format. + + Required + source: + type: string + description: Required + title: |- + The ID of the source synchronizer + Must be a valid synchronizer id + target: + type: string + description: Required + title: |- + The ID of the target synchronizer + Must be a valid synchronizer id + submitter: + type: string + description: |- + Party on whose behalf the unassign command was executed. + Empty if the unassignment happened offline via the repair service. + Must be a valid PartyIdString (as described in ``value.proto``). + + Optional + reassignmentCounter: + type: string + format: uint64 + description: |- + Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases + with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter + equals zero. + + Required + assignmentExclusivity: + type: string + format: date-time + description: |- + Assignment exclusivity + Before this time (measured on the target synchronizer), only the submitter of the unassignment can initiate the assignment + Defined for reassigning participants. + + Optional + witnessParties: + type: array + items: + type: string + description: |- + The parties that are notified of this event. + + Required: must be non-empty + packageName: + type: string + description: |- + The package name of the contract. + + Required + offset: + type: string + format: int64 + description: Required + title: |- + The offset of origin. + Offsets are managed by the participant nodes. + Reassignments can thus NOT be assumed to have the same offsets on different participant nodes. + Must be a valid absolute offset (positive integer) + nodeId: + type: integer + format: int32 + description: Required + title: |- + The position of this event in the originating reassignment. + Node IDs are not necessarily equal across participants, + as these may see different projections/parts of reassignments. + Must be valid node ID (non-negative integer) + title: Records that a contract has been unassigned, and it becomes unusable on the source synchronizer + com.daml.ledger.api.v2.UpdateFormat: + type: object + properties: + includeTransactions: + $ref: '#/definitions/com.daml.ledger.api.v2.TransactionFormat' + description: |- + Include Daml transactions in streams. + If unset, no transactions are emitted in the stream. + + Optional + includeReassignments: + $ref: '#/definitions/com.daml.ledger.api.v2.EventFormat' + description: |- + Include (un)assignments in the stream. + The events in the result take the shape TRANSACTION_SHAPE_ACS_DELTA. + If unset, no (un)assignments are emitted in the stream. + + Optional + includeTopologyEvents: + $ref: '#/definitions/com.daml.ledger.api.v2.TopologyFormat' + description: |- + Include topology events in streams. + If unset no topology events are emitted in the stream. + + Optional + description: A format specifying what updates to include and how to render them. + com.daml.ledger.api.v2.UserManagementFeature: + type: object + properties: + supported: + type: boolean + description: |- + Whether the Ledger API server provides the user management service. + + Required + maxRightsPerUser: + type: integer + format: int32 + description: |- + 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. + + Required + maxUsersPageSize: + type: integer + format: int32 + description: |- + 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. + + Required + com.daml.ledger.api.v2.Value: + type: object + properties: + unit: + type: object + properties: {} + description: This value is used for example for choices that don't take any arguments. + bool: + type: boolean + description: True or false. + int64: + type: string + format: int64 + date: + type: integer + format: int32 + title: |- + 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 + timestamp: + type: string + format: int64 + title: |- + 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 + numeric: + type: string + description: |- + .. code-block:: none + + [+-]?\d{1,38}(.\d{0,37})? + + and should be representable by a Numeric without loss of precision. + title: |- + 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 + party: + type: string + description: |- + An agent operating on the ledger. + Must be a valid PartyIdString. + text: + type: string + description: A string. + contractId: + type: string + description: |- + Identifier of an on-ledger contract. Commands which reference an unknown or already archived contract ID will fail. + Must be a valid LedgerString. + optional: + $ref: '#/definitions/com.daml.ledger.api.v2.Optional' + title: The Optional type, None or Some + list: + $ref: '#/definitions/com.daml.ledger.api.v2.List' + description: Represents a homogeneous list of values. + textMap: + $ref: '#/definitions/com.daml.ledger.api.v2.TextMap' + title: The TextMap type + genMap: + $ref: '#/definitions/com.daml.ledger.api.v2.GenMap' + title: The GenMap type + record: + $ref: '#/definitions/com.daml.ledger.api.v2.Record' + variant: + $ref: '#/definitions/com.daml.ledger.api.v2.Variant' + enum: + $ref: '#/definitions/com.daml.ledger.api.v2.Enum' + title: The Enum type + description: |- + Encodes values that the ledger accepts as command arguments and emits as contract arguments. + + The values encoding use different classes of non-empty strings as identifiers. Those classes are + defined as follows: + + - NameStrings are strings with length <= 1000 that match the regexp ``[A-Za-z\$_][A-Za-z0-9\$_]*``. + - PackageIdStrings are strings with length <= 64 that match the regexp ``[A-Za-z0-9\-_ ]+``. + - PartyIdStrings are strings with length <= 255 that match the regexp ``[A-Za-z0-9:\-_ ]+``. + - ParticipantIdStrings are strings with length <= 255 that match the regexp ``[A-Za-z0-9:\-_ ]+``. + - LedgerStrings are strings with length <= 255 that match the regexp ``[A-Za-z0-9#:\-_/ ]+``. + - UserIdStrings are strings with length <= 128 that match the regexp ``[a-zA-Z0-9@^$.!`\-#+'~_|:]+``. + com.daml.ledger.api.v2.Variant: + type: object + properties: + variantId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + Omitted from the transaction stream when verbose streaming is not enabled. + Optional when submitting commands. + constructor: + type: string + title: |- + Determines which of the Variant's alternatives is encoded in this message. + Must be a valid NameString. + Required + value: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: |- + The value encoded within the Variant. + Required + description: A value with alternative representations. + com.daml.ledger.api.v2.VettedPackage: + type: object + properties: + packageId: + type: string + description: Required + title: Package ID of this package + validFromInclusive: + type: string + format: date-time + description: |- + The time from which this package is vetted. Empty if vetting time has no + lower bound. + + Optional + validUntilExclusive: + type: string + format: date-time + description: |- + The time until which this package is vetted. Empty if vetting time has no + upper bound. + + Optional + packageName: + type: string + description: |- + Name of this package. + Only available if the package has been uploaded to the current participant. + + Optional + packageVersion: + type: string + description: |- + Version of this package. + Only available if the package has been uploaded to the current participant. + + Optional + description: |- + A package that is vetting on a given participant and synchronizer, + modelled after ``VettedPackage`` in `topology.proto `_, + enriched with the package name and version. + com.daml.ledger.api.v2.VettedPackages: + type: object + properties: + packages: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.VettedPackage' + description: |- + Sorted by package_name and package_version where known, and package_id as a + last resort. + + Required: must be non-empty + participantId: + type: string + description: |- + Participant on which these packages are vetted. + + Required + synchronizerId: + type: string + description: |- + Synchronizer on which these packages are vetted. + + Required + topologySerial: + type: integer + format: int64 + description: |- + Serial of last ``VettedPackages`` topology transaction of this participant + and on this synchronizer. + + Required + description: |- + The list of packages vetted on a given participant and synchronizer, modelled + after ``VettedPackages`` in `topology.proto `_. + The list only contains packages that matched a filter in the query that + originated it. + com.daml.ledger.api.v2.WildcardFilter: + type: object + properties: + includeCreatedEventBlob: + type: boolean + description: |- + Whether to include a ``created_event_blob`` in the returned ``CreatedEvent``. + Use this to access the contract create event payload in your API client + for submitting it as a disclosed contract with future commands. + + Optional + description: This filter matches all templates. + com.daml.ledger.api.v2.admin.AllocateExternalPartyRequest: + type: object + properties: + synchronizer: + type: string + description: Required + title: |- + TODO(#27670) support synchronizer aliases + Synchronizer ID on which to onboard the party + onboardingTransactions: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.AllocateExternalPartyRequest.SignedTransaction' + description: |- + TopologyTransactions to onboard the external party + Can contain: + - A namespace for the party. + This can be either a single NamespaceDelegation, + or DecentralizedNamespaceDefinition along with its authorized namespace owners in the form of NamespaceDelegations. + May be provided, if so it must be fully authorized by the signatures in this request combined with the existing topology state. + - A PartyToParticipant to register the hosting relationship of the party, and the party's signing keys and threshold. + Must be provided. + + Required: must be non-empty + multiHashSignatures: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Signature' + description: 'Optional: can be empty' + title: |- + Optional signatures of the combined hash of all onboarding_transactions + This may be used instead of providing signatures on each individual transaction + identityProviderId: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the party is managed by the default identity provider. + + Optional + waitForAllocation: + type: boolean + description: |- + When true, this RPC will attempt to wait for the party to be allocated on the synchronizer before returning. + When false, the allocation will happen asynchronously. + This is a best effort only as this synchronization is only possible for non decentralized parties (single hosting node). + For decentralized parties, this flag is ignored. + Defaults to true. + + Optional + userId: + type: string + description: |- + The user who will get the act_as rights to the newly allocated party. + If set to an empty string (the default), no user will get rights to the party. + + Optional + title: |- + Required authorization: + ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)`` + com.daml.ledger.api.v2.admin.AllocateExternalPartyRequest.SignedTransaction: + type: object + properties: + transaction: + type: string + format: byte + description: 'Required: must be non-empty' + title: The serialized TopologyTransaction + signatures: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Signature' + description: 'Optional: can be empty' + title: |- + Additional signatures for this transaction specifically + Use for transactions that require additional signatures beyond the namespace key signatures + e.g: PartyToParticipant must be signed by all registered keys + com.daml.ledger.api.v2.admin.AllocateExternalPartyResponse: + type: object + properties: + partyId: + type: string + description: Required + title: The allocated party id + com.daml.ledger.api.v2.admin.AllocatePartyRequest: + type: object + properties: + partyIdHint: + type: string + description: |- + A hint to the participant which party ID to allocate. It can be + ignored. + Must be a valid PartyIdString (as described in ``value.proto``). + + Optional + localMetadata: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ObjectMeta' + description: |- + Participant-local metadata to be stored in the ``PartyDetails`` of this newly allocated party. + + Optional + identityProviderId: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. + + Optional + synchronizerId: + type: string + description: |- + The synchronizer, on which the party should be allocated. + For backwards compatibility, this field may be omitted, if the participant is connected to only one synchronizer. + Otherwise a synchronizer must be specified. + + Optional + userId: + type: string + description: |- + The user who will get the act_as rights to the newly allocated party. + If set to an empty string (the default), no user will get rights to the party. + + Optional + title: |- + Required authorization: + ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)`` + com.daml.ledger.api.v2.admin.AllocatePartyResponse: + type: object + properties: + partyDetails: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.PartyDetails' + description: Required + title: The allocated party details + com.daml.ledger.api.v2.admin.CreateIdentityProviderConfigRequest: + type: object + properties: + identityProviderConfig: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.IdentityProviderConfig' + title: Required + com.daml.ledger.api.v2.admin.CreateIdentityProviderConfigResponse: + type: object + properties: + identityProviderConfig: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.IdentityProviderConfig' + title: Required + com.daml.ledger.api.v2.admin.CreateUserRequest: + type: object + properties: + user: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.User' + description: |- + The user to create. + + Required + rights: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right' + description: |- + The rights to be assigned to the user upon creation, + which SHOULD include appropriate rights for the ``user.primary_party``. + + Optional: can be empty + title: 'Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(user.identity_provider_id)``' + com.daml.ledger.api.v2.admin.CreateUserResponse: + type: object + properties: + user: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.User' + description: |- + Created user. + + Required + com.daml.ledger.api.v2.admin.DeleteIdentityProviderConfigResponse: + type: object + description: Does not (yet) contain any data. + com.daml.ledger.api.v2.admin.DeleteUserResponse: + type: object + description: Does not (yet) contain any data. + com.daml.ledger.api.v2.admin.GenerateExternalPartyTopologyRequest: + type: object + properties: + synchronizer: + type: string + description: Required + title: |- + Synchronizer-id for which we are building this request. + TODO(#27670) support synchronizer aliases + partyHint: + type: string + description: Required + title: The actual party id will be constructed from this hint and a fingerprint of the public key + publicKey: + $ref: '#/definitions/com.daml.ledger.api.v2.SigningPublicKey' + description: Required + title: Public key + localParticipantObservationOnly: + type: boolean + description: |- + If true, then the local participant will only be observing, not confirming. Default false. + + Optional + otherConfirmingParticipantUids: + type: array + items: + type: string + description: 'Optional: can be empty' + title: Other participant ids which should be confirming for this party + confirmationThreshold: + type: integer + format: int64 + description: |- + Confirmation threshold >= 1 for the party. Defaults to all available confirmers (or if set to 0). + + Optional + observingParticipantUids: + type: array + items: + type: string + description: 'Optional: can be empty' + title: Other observing participant ids for this party + com.daml.ledger.api.v2.admin.GenerateExternalPartyTopologyResponse: + type: object + properties: + partyId: + type: string + description: Required + title: The generated party id + publicKeyFingerprint: + type: string + description: Required + title: The fingerprint of the supplied public key + topologyTransactions: + type: array + items: + type: string + format: byte + description: |- + The serialized topology transactions which need to be signed and submitted as part of the allocate party process + Note that the serialization includes the versioning information. Therefore, the transaction here is serialized + as an `UntypedVersionedMessage` which in turn contains the serialized `TopologyTransaction` in the version + supported by the synchronizer. + + Required: must be non-empty + multiHash: + type: string + format: byte + description: 'Required: must be non-empty' + title: the multi-hash which may be signed instead of each individual transaction + description: Response message with topology transactions and the multi-hash to be signed. + com.daml.ledger.api.v2.admin.GetIdentityProviderConfigResponse: + type: object + properties: + identityProviderConfig: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.IdentityProviderConfig' + title: Required + com.daml.ledger.api.v2.admin.GetParticipantIdResponse: + type: object + properties: + participantId: + type: string + description: |- + Identifier of the participant, which SHOULD be globally unique. + Must be a valid ParticipantIdStrings (as describe in ``value.proto``). + + Required + com.daml.ledger.api.v2.admin.GetPartiesResponse: + type: object + properties: + partyDetails: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.PartyDetails' + description: |- + 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: must be non-empty + com.daml.ledger.api.v2.admin.GetUserResponse: + type: object + properties: + user: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.User' + description: |- + Retrieved user. + + Required + com.daml.ledger.api.v2.admin.GrantUserRightsResponse: + type: object + properties: + newlyGrantedRights: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right' + description: |- + The rights that were newly granted by the request. + + Optional: can be empty + com.daml.ledger.api.v2.admin.IdentityProviderConfig: + type: object + properties: + identityProviderId: + type: string + description: |- + The identity provider identifier + Must be a valid LedgerString (as describe in ``value.proto``). + + Required + isDeactivated: + type: boolean + description: Optional + title: |- + When set, the callers using JWT tokens issued by this identity provider are denied all access + to the Ledger API. + Modifiable + issuer: + type: string + description: |- + Can be left empty when used in `UpdateIdentityProviderConfigRequest` if the issuer is not being updated. + + Required + title: |- + Specifies the issuer of the JWT token. + The issuer value is a case sensitive URL using the https scheme that contains scheme, host, + and optionally, port number and path components and no query or fragment components. + Modifiable + jwksUrl: + type: string + description: Required + title: |- + The JWKS (JSON Web Key Set) URL. + The Ledger API uses JWKs (JSON Web Keys) from the provided URL to verify that the JWT has been + signed with the loaded JWK. Only RS256 (RSA Signature with SHA-256) signing algorithm is supported. + Modifiable + audience: + type: string + description: Optional + title: |- + Specifies the audience of the JWT token. + When set, the callers using JWT tokens issued by this identity provider are allowed to get an access + only if the "aud" claim includes the string specified here + Modifiable + com.daml.ledger.api.v2.admin.IdentityProviderConfigService.UpdateIdentityProviderConfigBody: + type: object + properties: + identityProviderConfig: + type: object + properties: + isDeactivated: + type: boolean + description: Optional + title: |- + When set, the callers using JWT tokens issued by this identity provider are denied all access + to the Ledger API. + Modifiable + issuer: + type: string + description: |- + Can be left empty when used in `UpdateIdentityProviderConfigRequest` if the issuer is not being updated. + + Required + title: |- + Specifies the issuer of the JWT token. + The issuer value is a case sensitive URL using the https scheme that contains scheme, host, + and optionally, port number and path components and no query or fragment components. + Modifiable + jwksUrl: + type: string + description: Required + title: |- + The JWKS (JSON Web Key Set) URL. + The Ledger API uses JWKs (JSON Web Keys) from the provided URL to verify that the JWT has been + signed with the loaded JWK. Only RS256 (RSA Signature with SHA-256) signing algorithm is supported. + Modifiable + audience: + type: string + description: Optional + title: |- + Specifies the audience of the JWT token. + When set, the callers using JWT tokens issued by this identity provider are allowed to get an access + only if the "aud" claim includes the string specified here + Modifiable + description: |- + The identity provider config to update. + Modifiable + + Required + title: |- + The identity provider config to update. + Modifiable + updateMask: + type: string + description: |- + 1. contain at least one update path, + 2. contain only valid update paths. + + Fields that can be updated are marked as ``Modifiable``. + For additional information see the documentation for standard protobuf3's ``google.protobuf.FieldMask``. + + Required + title: |- + An update mask specifies how and which properties of the ``IdentityProviderConfig`` message are to be updated. + An update mask consists of a set of update paths. + A valid update path points to a field or a subfield relative to the ``IdentityProviderConfig`` message. + A valid update mask must: + com.daml.ledger.api.v2.admin.ListIdentityProviderConfigsResponse: + type: object + properties: + identityProviderConfigs: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.IdentityProviderConfig' + description: 'Required: must be non-empty' + title: The list of identity provider configs + com.daml.ledger.api.v2.admin.ListKnownPartiesResponse: + type: object + properties: + partyDetails: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.PartyDetails' + description: |- + The details of all Daml parties known by the participant. + + Required: must be non-empty + nextPageToken: + type: string + description: |- + Pagination token to retrieve the next page. + Empty, if there are no further results. + + Optional + com.daml.ledger.api.v2.admin.ListUserRightsResponse: + type: object + properties: + rights: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right' + description: |- + All rights of the user. + + Optional: can be empty + com.daml.ledger.api.v2.admin.ListUsersResponse: + type: object + properties: + users: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.User' + description: 'Optional: can be empty' + title: |- + A subset of users of the participant node that fit into this page. + Can be empty if no more users + nextPageToken: + type: string + description: |- + Pagination token to retrieve the next page. + Empty, if there are no further results. + + Optional + com.daml.ledger.api.v2.admin.ObjectMeta: + type: object + properties: + resourceVersion: + type: string + description: |- + An opaque, non-empty value, populated by a participant server which represents the internal version of the resource + this ``ObjectMeta`` message is attached to. The participant server will change it to a unique value each time the corresponding resource is updated. + You must not rely on the format of resource version. The participant server might change it without notice. + You can obtain the newest resource version value by issuing a read request. + You may use it for concurrent change detection by passing it back unmodified in an update request. + The participant server will then compare the passed value with the value maintained by the system to determine + if any other updates took place since you had read the resource version. + Upon a successful update you are guaranteed that no other update took place during your read-modify-write sequence. + However, if another update took place during your read-modify-write sequence then your update will fail with an appropriate error. + Concurrent change control is optional. It will be applied only if you include a resource version in an update request. + When creating a new instance of a resource you must leave the resource version empty. + Its value will be populated by the participant server upon successful resource creation. + + Optional + annotations: + type: object + additionalProperties: + type: string + description: |- + 1. The total size over all keys and values cannot exceed 256kb in UTF-8 encoding. + 2. Keys are composed of an optional prefix segment and a required name segment such that: + + - key prefix, when present, must be a valid DNS subdomain with at most 253 characters, followed by a '/' (forward slash) character, + - name segment must have at most 63 characters that are either alphanumeric ([a-z0-9A-Z]), or a '.' (dot), '-' (dash) or '_' (underscore); + and it must start and end with an alphanumeric character. + + 3. Values can be any non-empty strings. + + Keys with empty prefix are reserved for end-users. + Properties set by external tools or internally by the participant server must use non-empty key prefixes. + Duplicate keys are disallowed by the semantics of the protobuf3 maps. + See: https://developers.google.com/protocol-buffers/docs/proto3#maps + Annotations may be a part of a modifiable resource. + Use the resource's update RPC to update its annotations. + In order to add a new annotation or update an existing one using an update RPC, provide the desired annotation in the update request. + In order to remove an annotation using an update RPC, provide the target annotation's key but set its value to the empty string in the update request. + Modifiable + + Optional: can be empty + title: |- + A set of modifiable key-value pairs that can be used to represent arbitrary, client-specific metadata. + Constraints: + description: |- + Represents metadata corresponding to a participant resource (e.g. a participant user or participant local information about a party). + + Based on ``ObjectMeta`` meta used in Kubernetes API. + See https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/generated.proto#L640 + com.daml.ledger.api.v2.admin.PartyDetails: + type: object + properties: + party: + type: string + description: |- + The stable unique identifier of a Daml party. + Must be a valid PartyIdString (as described in ``value.proto``). + + Required + isLocal: + type: boolean + description: |- + true if party is hosted by the participant and the party shares the same identity provider as the user issuing the request. + + Optional + localMetadata: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ObjectMeta' + description: Optional + title: |- + Participant-local metadata of this party. + Modifiable + identityProviderId: + type: string + description: |- + 1. the party is managed by the default identity provider. + 2. party is not hosted by the participant. + 3. party is hosted by the participant, but is outside of the user's identity provider. + + Optional + title: |- + The id of the ``Identity Provider`` + Optional, if not set, there could be 3 options: + com.daml.ledger.api.v2.admin.PartyManagementService.UpdatePartyDetailsBody: + type: object + properties: + partyDetails: + type: object + properties: + isLocal: + type: boolean + description: |- + true if party is hosted by the participant and the party shares the same identity provider as the user issuing the request. + + Optional + localMetadata: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ObjectMeta' + description: Optional + title: |- + Participant-local metadata of this party. + Modifiable + identityProviderId: + type: string + description: |- + 1. the party is managed by the default identity provider. + 2. party is not hosted by the participant. + 3. party is hosted by the participant, but is outside of the user's identity provider. + + Optional + title: |- + The id of the ``Identity Provider`` + Optional, if not set, there could be 3 options: + description: |- + Party to be updated + Modifiable + + Required + title: |- + Party to be updated + Modifiable + updateMask: + type: string + description: |- + 1. contain at least one update path, + 2. contain only valid update paths. + + Fields that can be updated are marked as ``Modifiable``. + An update path can also point to non-``Modifiable`` fields such as 'party' and 'local_metadata.resource_version' + because they are used: + + 1. to identify the party details resource subject to the update, + 2. for concurrent change control. + + An update path can also point to non-``Modifiable`` fields such as 'is_local' + as long as the values provided in the update request match the server values. + Examples of update paths: 'local_metadata.annotations', 'local_metadata'. + For additional information see the documentation for standard protobuf3's ``google.protobuf.FieldMask``. + For similar Ledger API see ``com.daml.ledger.api.v2.admin.UpdateUserRequest``. + + Required + title: |- + An update mask specifies how and which properties of the ``PartyDetails`` message are to be updated. + An update mask consists of a set of update paths. + A valid update path points to a field or a subfield relative to the ``PartyDetails`` message. + A valid update mask must: + title: 'Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(party_details.identity_provider_id)``' + com.daml.ledger.api.v2.admin.RevokeUserRightsResponse: + type: object + properties: + newlyRevokedRights: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right' + description: |- + The rights that were actually revoked by the request. + + Optional: can be empty + com.daml.ledger.api.v2.admin.Right: + type: object + properties: + participantAdmin: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.ParticipantAdmin' + description: The user can administer the participant node. + canActAs: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.CanActAs' + description: The user can act as a specific party. + canReadAs: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.CanReadAs' + description: The user can read ledger data visible to a specific party. + identityProviderAdmin: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.IdentityProviderAdmin' + description: The user can administer users and parties assigned to the same identity provider as the one of the user. + canReadAsAnyParty: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.CanReadAsAnyParty' + title: The user can read as any party on a participant + canExecuteAs: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.CanExecuteAs' + description: The user can prepare and execute submissions as a specific party. + canExecuteAsAnyParty: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right.CanExecuteAsAnyParty' + description: The user can prepare and execute submissions as any party on a participant. + description: A right granted to a user. + com.daml.ledger.api.v2.admin.Right.CanActAs: + type: object + properties: + party: + type: string + description: |- + The right to authorize commands for this party. + + Required + com.daml.ledger.api.v2.admin.Right.CanExecuteAs: + type: object + properties: + party: + type: string + description: |- + The right to prepare and execute submissions as this party. + This right does not entitle the user to perform any reads. + If reading is required, a separate ReadAs right must be added. + Right to execute as a party is also implicitly contained in the CanActAs right. + + Required + com.daml.ledger.api.v2.admin.Right.CanExecuteAsAnyParty: + type: object + description: |- + The rights of a user to prepare and execute transactions as any party. + Its utility is predominantly for users that perform interactive submissions + on behalf of many parties. + com.daml.ledger.api.v2.admin.Right.CanReadAs: + type: object + properties: + party: + type: string + description: |- + The right to read ledger data visible to this party. + + Required + com.daml.ledger.api.v2.admin.Right.CanReadAsAnyParty: + type: object + description: |- + The rights of a participant's super reader. Its utility is predominantly for + feeding external tools, such as PQS, continually without the need to change subscriptions + as new parties pop in and out of existence. + com.daml.ledger.api.v2.admin.Right.IdentityProviderAdmin: + type: object + description: |- + The right to administer the identity provider that the user is assigned to. + It means, being able to manage users and parties that are also assigned + to the same identity provider. + com.daml.ledger.api.v2.admin.Right.ParticipantAdmin: + type: object + description: The right to administer the participant node. + com.daml.ledger.api.v2.admin.UpdateIdentityProviderConfigResponse: + type: object + properties: + identityProviderConfig: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.IdentityProviderConfig' + description: Required + title: Updated identity provider config + com.daml.ledger.api.v2.admin.UpdatePartyDetailsResponse: + type: object + properties: + partyDetails: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.PartyDetails' + description: Required + title: Updated party details + com.daml.ledger.api.v2.admin.UpdateUserIdentityProviderIdResponse: + type: object + com.daml.ledger.api.v2.admin.UpdateUserResponse: + type: object + properties: + user: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.User' + description: Required + title: Updated user + com.daml.ledger.api.v2.admin.UpdateVettedPackagesForceFlag: + type: string + enum: + - UPDATE_VETTED_PACKAGES_FORCE_FLAG_UNSPECIFIED + - UPDATE_VETTED_PACKAGES_FORCE_FLAG_ALLOW_VET_INCOMPATIBLE_UPGRADES + - UPDATE_VETTED_PACKAGES_FORCE_FLAG_ALLOW_UNVETTED_DEPENDENCIES + default: UPDATE_VETTED_PACKAGES_FORCE_FLAG_UNSPECIFIED + title: |- + - UPDATE_VETTED_PACKAGES_FORCE_FLAG_UNSPECIFIED: Force flag left unspecified, defaults to no force flag used in the backend. + - UPDATE_VETTED_PACKAGES_FORCE_FLAG_ALLOW_VET_INCOMPATIBLE_UPGRADES: * Allow vetting a package that is upgrade-incompatible with other vetted packages + - UPDATE_VETTED_PACKAGES_FORCE_FLAG_ALLOW_UNVETTED_DEPENDENCIES: * Allow vetting a package without vetting one or more of its dependencies + com.daml.ledger.api.v2.admin.UpdateVettedPackagesRequest: + type: object + properties: + changes: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.VettedPackagesChange' + description: |- + Changes to apply to the current vetting state of the participant on the + specified synchronizer. The changes are applied in order. + Any package not changed will keep their previous vetting state. + + Required: must be non-empty + dryRun: + type: boolean + description: |- + If dry_run is true, then the changes are only prepared, but not applied. If + a request would trigger an error when run (e.g. TOPOLOGY_DEPENDENCIES_NOT_VETTED), + it will also trigger an error when dry_run. + + Use this flag to preview a change before applying it. + Defaults to false. + + Optional + synchronizerId: + type: string + description: |- + If set, the requested changes will take place on the specified + synchronizer. If synchronizer_id is unset and the participant is only + connected to a single synchronizer, that synchronizer will be used by + default. If synchronizer_id is unset and the participant is connected to + multiple synchronizers, the request will error out with + PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER. + + Optional + expectedTopologySerial: + $ref: '#/definitions/com.daml.ledger.api.v2.PriorTopologySerial' + description: |- + The serial of the last ``VettedPackages`` topology transaction of this + participant and on this synchronizer. + + Execution of the request fails if this is not correct. Use this to guard + against concurrent changes. + + If left unspecified, no validation is done against the last transaction's + serial. + + Optional + updateVettedPackagesForceFlags: + type: array + items: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UpdateVettedPackagesForceFlag' + description: |- + Controls whether potentially unsafe vetting updates are allowed. + + Optional: can be empty + com.daml.ledger.api.v2.admin.UpdateVettedPackagesResponse: + type: object + properties: + pastVettedPackages: + $ref: '#/definitions/com.daml.ledger.api.v2.VettedPackages' + description: |- + All vetted packages on this participant and synchronizer, before the + specified changes. Empty if no vetting state existed beforehand. + + Not populated if no vetted topology state exists prior to the update. + + Optional + newVettedPackages: + $ref: '#/definitions/com.daml.ledger.api.v2.VettedPackages' + description: |- + All vetted packages on this participant and synchronizer, after the specified changes. + + Required + com.daml.ledger.api.v2.admin.UploadDarFileRequest: + type: object + properties: + darFile: + type: string + format: byte + description: |- + 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: must be non-empty + submissionId: + type: string + description: |- + Unique submission identifier. + If not populated, a random identifier will be generated. + + Optional + vettingChange: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.UploadDarFileRequest.VettingChange' + description: Optional + title: How to vet packages in the DAR being uploaded + synchronizerId: + type: string + description: |- + Only used if VettingChange is set to VETTING_CHANGE_VET_ALL_PACKAGES, in + order to specify which synchronizer to vet on. + + If synchronizer_id is set, the synchronizer with this ID will be used. If + synchronizer_id is unset and the participant is only connected to a single + synchronizer, that synchronizer will be used by default. If synchronizer_id + is unset and the participant is connected to multiple synchronizers, the + request will error out with PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER. + + Optional + com.daml.ledger.api.v2.admin.UploadDarFileRequest.VettingChange: + type: string + enum: + - VETTING_CHANGE_UNSPECIFIED + - VETTING_CHANGE_VET_ALL_PACKAGES + - VETTING_CHANGE_DONT_VET_ANY_PACKAGES + default: VETTING_CHANGE_UNSPECIFIED + description: |2- + - VETTING_CHANGE_UNSPECIFIED: Vetting change field left unspecified, defaults to vetting all the + packages in the DAR. + - VETTING_CHANGE_VET_ALL_PACKAGES: Vet all the packages in the DAR. + - VETTING_CHANGE_DONT_VET_ANY_PACKAGES: Do not vet any packages in the DAR. + com.daml.ledger.api.v2.admin.UploadDarFileResponse: + type: object + description: A message that is received when the upload operation succeeded. + com.daml.ledger.api.v2.admin.User: + type: object + properties: + id: + type: string + description: |- + The user identifier, which must be a non-empty string of at most 128 + characters that are either alphanumeric ASCII characters or one of the symbols "@^$.!`-#+'~_|:()". + + Required + primaryParty: + type: string + description: Optional + title: |- + 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. + Modifiable + isDeactivated: + type: boolean + description: Optional + title: |- + When set, then the user is denied all access to the Ledger API. + Otherwise, the user has access to the Ledger API as per the user's rights. + Modifiable + metadata: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ObjectMeta' + description: Optional + title: |- + The metadata of this user. + Note that the ``metadata.resource_version`` tracks changes to the properties described by the ``User`` message and not the user's rights. + Modifiable + identityProviderId: + type: string + description: |- + The ID of the identity provider configured by ``Identity Provider Config`` + If not set, assume the user is managed by the default identity provider. + + Optional + primaryPartyAuthentication: + type: boolean + description: Optional + title: |- + If set to true, the user may authenticate against the Ledger API by signing + a Party JWT using the primary party's signing key. + Modifiable + description: |- + Users are used to dynamically manage the rights given to Daml applications. + They are stored and managed per participant node. + com.daml.ledger.api.v2.admin.UserManagementService.GrantUserRightsBody: + type: object + properties: + rights: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right' + description: |- + The rights to grant. + + Optional: can be empty + identityProviderId: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + description: |- + Add the rights to the set of rights granted to the user. + + Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)`` + com.daml.ledger.api.v2.admin.UserManagementService.RevokeUserRightsBody: + type: object + properties: + rights: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.Right' + description: |- + The rights to revoke. + + Optional: can be empty + identityProviderId: + type: string + description: |- + The id of the ``Identity Provider`` + If not set, assume the user is managed by the default identity provider. + + Optional + description: |- + Remove the rights from the set of rights granted to the user. + + Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id)`` + com.daml.ledger.api.v2.admin.UserManagementService.UpdateUserBody: + type: object + properties: + user: + type: object + properties: + primaryParty: + type: string + description: Optional + title: |- + 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. + Modifiable + isDeactivated: + type: boolean + description: Optional + title: |- + When set, then the user is denied all access to the Ledger API. + Otherwise, the user has access to the Ledger API as per the user's rights. + Modifiable + metadata: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.ObjectMeta' + description: Optional + title: |- + The metadata of this user. + Note that the ``metadata.resource_version`` tracks changes to the properties described by the ``User`` message and not the user's rights. + Modifiable + identityProviderId: + type: string + description: |- + The ID of the identity provider configured by ``Identity Provider Config`` + If not set, assume the user is managed by the default identity provider. + + Optional + primaryPartyAuthentication: + type: boolean + description: Optional + title: |- + If set to true, the user may authenticate against the Ledger API by signing + a Party JWT using the primary party's signing key. + Modifiable + description: |- + The user to update. + Modifiable + + Required + title: |- + The user to update. + Modifiable + updateMask: + type: string + description: |- + 1. contain at least one update path, + 2. contain only valid update paths. + + Fields that can be updated are marked as ``Modifiable``. + An update path can also point to a non-``Modifiable`` fields such as 'id' and 'metadata.resource_version' + because they are used: + + 1. to identify the user resource subject to the update, + 2. for concurrent change control. + + Examples of valid update paths: 'primary_party', 'metadata', 'metadata.annotations'. + For additional information see the documentation for standard protobuf3's ``google.protobuf.FieldMask``. + For similar Ledger API see ``com.daml.ledger.api.v2.admin.UpdatePartyDetailsRequest``. + + Required + title: |- + An update mask specifies how and which properties of the ``User`` message are to be updated. + An update mask consists of a set of update paths. + A valid update path points to a field or a subfield relative to the ``User`` message. + A valid update mask must: + title: 'Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(user.identity_provider_id)``' + com.daml.ledger.api.v2.admin.UserManagementService.UpdateUserIdentityProviderIdBody: + type: object + properties: + sourceIdentityProviderId: + type: string + description: Optional + title: |- + Current identity provider ID of the user + If omitted, the default IDP is assumed + targetIdentityProviderId: + type: string + description: Optional + title: |- + Target identity provider ID of the user + If omitted, the default IDP is assumed + title: 'Required authorization: ``HasRight(ParticipantAdmin)``' + com.daml.ledger.api.v2.admin.ValidateDarFileRequest: + type: object + properties: + darFile: + type: string + format: byte + description: |- + 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: must be non-empty + submissionId: + type: string + description: |- + Unique submission identifier. If not defined, defaults to a random identifier. + + Optional + synchronizerId: + type: string + description: |- + If synchronizer_id is set, the synchronizer with this ID will be used. If + synchronizer_id is unset and the participant is only connected to a single + synchronizer, that synchronizer will be used by default. If synchronizer_id + is unset and the participant is connected to multiple synchronizers, the + request will error out with PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER. + + Optional + description: |- + Performs the same checks that UploadDarFileRequest would perform, but doesn't + upload the DAR. + com.daml.ledger.api.v2.admin.ValidateDarFileResponse: + type: object + com.daml.ledger.api.v2.admin.VettedPackagesChange: + type: object + properties: + vet: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.VettedPackagesChange.Vet' + description: Add packages to or update packages in the set of vetted packages. + unvet: + $ref: '#/definitions/com.daml.ledger.api.v2.admin.VettedPackagesChange.Unvet' + description: Remove packages from the set of vetted packages. + description: A change to the set of vetted packages. + com.daml.ledger.api.v2.admin.VettedPackagesChange.Unvet: + type: object + properties: + packages: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.VettedPackagesRef' + description: |- + Packages to be unvetted. + + If a reference in this list matches multiple packages, they are all + unvetted. + + Required: must be non-empty + title: Remove packages from the set of vetted packages + com.daml.ledger.api.v2.admin.VettedPackagesChange.Vet: + type: object + properties: + packages: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.admin.VettedPackagesRef' + description: |- + Packages to be vetted. + + If a reference in this list matches more than one package, the change is + considered ambiguous and the entire update request is rejected. In other + words, every reference must match exactly one package. + + Required: must be non-empty + newValidFromInclusive: + type: string + format: date-time + title: |- + The time from which these packages should be vetted, prior lower bounds + are overwritten. + Optional + newValidUntilExclusive: + type: string + format: date-time + title: |- + The time until which these packages should be vetted, prior upper bounds + are overwritten. + Optional + description: |- + Set vetting bounds of a list of packages. Packages that were not previously + vetted have their bounds added, previous vetting bounds are overwritten. + com.daml.ledger.api.v2.admin.VettedPackagesRef: + type: object + properties: + packageId: + type: string + description: |- + Package's package id must be the same as this field. + + Optional + packageName: + type: string + description: |- + Package's name must be the same as this field. + + Optional + packageVersion: + type: string + description: |- + Package's version must be the same as this field. + + Optional + description: |- + A reference to identify one or more packages. + + A reference matches a package if its ``package_id`` matches the package's ID, + its ``package_name`` matches the package's name, and its ``package_version`` + matches the package's version. If an attribute in the reference is left + unspecified (i.e. as an empty string), that attribute is treated as a + wildcard. At a minimum, ``package_id`` or the ``package_name`` must be + specified. + + If a reference does not match any package, the reference is considered + unresolved and the entire update request is rejected. + com.daml.ledger.api.v2.interactive.CostEstimation: + type: object + properties: + estimationTimestamp: + type: string + format: date-time + description: Required + title: Timestamp at which the estimation was made + confirmationRequestTrafficCostEstimation: + type: string + format: uint64 + description: Required + title: Estimated traffic cost of the confirmation request associated with the transaction + confirmationResponseTrafficCostEstimation: + type: string + format: uint64 + description: Required + title: |- + Estimated traffic cost of the confirmation response associated with the transaction + This field can also be used as an indication of the cost that other potential confirming nodes + of the party will incur to approve or reject the transaction + totalTrafficCostEstimation: + type: string + format: uint64 + description: Required + title: Sum of the fields above + description: |- + Estimation of the cost of submitting the prepared transaction + The estimation is done against the synchronizer chosen during preparation of the transaction + (or the one explicitly requested). + The cost of re-assigning contracts to another synchronizer when necessary is not included in the estimation. + com.daml.ledger.api.v2.interactive.CostEstimationHints: + type: object + properties: + disabled: + type: boolean + description: Optional + title: |- + Disable cost estimation + Default (not set) is false + expectedSignatures: + type: array + items: + $ref: '#/definitions/com.daml.ledger.api.v2.SigningAlgorithmSpec' + description: 'Optional: can be empty' + title: |- + Details on the keys that will be used to sign the transaction (how many and of which type). + Signature size impacts the cost of the transaction. + If empty, the signature sizes will be approximated with threshold-many signatures (where threshold is defined + in the PartyToParticipant of the external party), using keys in the order they are registered. + Empty list is equivalent to not providing this field + title: Hints to improve cost estimation precision of a prepared transaction + com.daml.ledger.api.v2.interactive.DamlTransaction: + type: object + properties: + version: + type: string + description: Required + title: serialization version, will be >= max(nodes version) + roots: + type: array + items: + type: string + description: 'Required: must be non-empty' + title: Root nodes of the transaction + nodes: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.DamlTransaction.Node' + description: 'Required: must be non-empty' + title: List of nodes in the transaction + nodeSeeds: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.DamlTransaction.NodeSeed' + description: 'Required: must be non-empty' + title: Node seeds are values associated with certain nodes used for generating cryptographic salts + description: |- + Daml Transaction. + This represents the effect on the ledger if this transaction is successfully committed. + com.daml.ledger.api.v2.interactive.DamlTransaction.Node: + type: object + properties: + nodeId: + type: string + title: Required + v1: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.transaction.v1.Node' + description: Required + title: |- + Start at 1000 so we can add more fields before if necessary + When new versions will be added, they will show here + title: |- + A transaction may contain nodes with different versions. + Each node must be hashed using the hashing algorithm corresponding to its specific version. + [docs-entry-start: DamlTransaction.Node] + com.daml.ledger.api.v2.interactive.DamlTransaction.NodeSeed: + type: object + properties: + nodeId: + type: integer + format: int32 + title: Required + seed: + type: string + format: byte + title: 'Required: must be non-empty' + com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitForTransactionRequest: + type: object + properties: + preparedTransaction: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PreparedTransaction' + description: |- + the prepared transaction + Typically this is the value of the `prepared_transaction` field in `PrepareSubmissionResponse` + obtained from calling `prepareSubmission`. + + Required + partySignatures: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PartySignatures' + description: |- + The party(ies) signatures that authorize the prepared submission to be executed by this node. + Each party can provide one or more signatures.. + and one or more parties can sign. + Note that currently, only single party submissions are supported. + + Required + deduplicationDuration: + type: string + description: |- + 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. + deduplicationOffset: + type: string + format: int64 + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer). + submissionId: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + userId: + type: string + description: Optional + title: See [PrepareSubmissionRequest.user_id] + hashingSchemeVersion: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.HashingSchemeVersion' + description: Required + title: The hashing scheme version used when building the hash + minLedgerTime: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.MinLedgerTime' + description: |- + If set will influence the chosen ledger effective time but will not result in a submission delay so any override + should be scheduled to executed within the window allowed by synchronizer. + + Optional + transactionFormat: + $ref: '#/definitions/com.daml.ledger.api.v2.TransactionFormat' + description: |- + If no ``transaction_format`` is provided, a default will be used where ``transaction_shape`` is set to + TRANSACTION_SHAPE_ACS_DELTA, ``event_format`` is defined with ``filters_by_party`` containing wildcard-template + filter for all original ``act_as`` and ``read_as`` parties and the ``verbose`` flag is set. + When the ``transaction_shape`` TRANSACTION_SHAPE_ACS_DELTA shape is used (explicitly or is defaulted to as explained above), + events will only be returned if the submitting party is hosted on this node. + + Optional + com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitForTransactionResponse: + type: object + properties: + transaction: + $ref: '#/definitions/com.daml.ledger.api.v2.Transaction' + description: |- + The transaction that resulted from the submitted command. + The transaction might contain no events (request conditions result in filtering out all of them). + + Required + com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitRequest: + type: object + properties: + preparedTransaction: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PreparedTransaction' + description: |- + the prepared transaction + Typically this is the value of the `prepared_transaction` field in `PrepareSubmissionResponse` + obtained from calling `prepareSubmission`. + + Required + partySignatures: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PartySignatures' + description: |- + The party(ies) signatures that authorize the prepared submission to be executed by this node. + Each party can provide one or more signatures.. + and one or more parties can sign. + Note that currently, only single party submissions are supported. + + Required + deduplicationDuration: + type: string + description: |- + 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. + deduplicationOffset: + type: string + format: int64 + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer). + submissionId: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + userId: + type: string + description: Optional + title: See [PrepareSubmissionRequest.user_id] + hashingSchemeVersion: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.HashingSchemeVersion' + description: Required + title: The hashing scheme version used when building the hash + minLedgerTime: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.MinLedgerTime' + description: |- + If set will influence the chosen ledger effective time but will not result in a submission delay so any override + should be scheduled to executed within the window allowed by synchronizer. + + Optional + com.daml.ledger.api.v2.interactive.ExecuteSubmissionAndWaitResponse: + type: object + properties: + updateId: + type: string + description: |- + The id of the transaction that resulted from the submitted command. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + completionOffset: + type: string + format: int64 + description: |- + The details of the offset field are described in ``community/ledger-api/README.md``. + + Required + com.daml.ledger.api.v2.interactive.ExecuteSubmissionRequest: + type: object + properties: + preparedTransaction: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PreparedTransaction' + description: |- + the prepared transaction + Typically this is the value of the `prepared_transaction` field in `PrepareSubmissionResponse` + obtained from calling `prepareSubmission`. + + Required + partySignatures: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PartySignatures' + description: |- + The party(ies) signatures that authorize the prepared submission to be executed by this node. + Each party can provide one or more signatures.. + and one or more parties can sign. + Note that currently, only single party submissions are supported. + + Required + deduplicationDuration: + type: string + description: |- + 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. + deduplicationOffset: + type: string + format: int64 + description: |- + Specifies the start of the deduplication period by a completion stream offset (exclusive). + Must be a valid absolute offset (positive integer). + submissionId: + type: string + description: |- + A unique identifier to distinguish completions for different submissions with the same change ID. + Typically a random UUID. Applications are expected to use a different UUID for each retry of a submission + with the same change ID. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + userId: + type: string + description: Optional + title: See [PrepareSubmissionRequest.user_id] + hashingSchemeVersion: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.HashingSchemeVersion' + description: Required + title: The hashing scheme version used when building the hash + minLedgerTime: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.MinLedgerTime' + description: |- + If set will influence the chosen ledger effective time but will not result in a submission delay so any override + should be scheduled to executed within the window allowed by synchronizer. + + Optional + com.daml.ledger.api.v2.interactive.ExecuteSubmissionResponse: + type: object + com.daml.ledger.api.v2.interactive.GetPreferredPackageVersionResponse: + type: object + properties: + packagePreference: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PackagePreference' + description: Optional + title: Not populated when no preferred package is found + com.daml.ledger.api.v2.interactive.GetPreferredPackagesRequest: + type: object + properties: + packageVettingRequirements: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PackageVettingRequirement' + description: |- + The package-name vetting requirements for which the preferred packages should be resolved. + + Generally it is enough to provide the requirements for the intended command's root package-names. + Additional package-name requirements can be provided when additional Daml transaction informees need to use + package dependencies of the command's root packages. + + Required: must be non-empty + synchronizerId: + type: string + description: |- + The synchronizer whose vetting state should be used for resolving this query. + If not specified, the vetting states of all synchronizers to which the participant is connected are used. + + Optional + vettingValidAt: + type: string + format: date-time + description: |- + The timestamp at which the package vetting validity should be computed + on the latest topology snapshot as seen by the participant. + If not provided, the participant's current clock time is used. + + Optional + com.daml.ledger.api.v2.interactive.GetPreferredPackagesResponse: + type: object + properties: + packageReferences: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.PackageReference' + description: |- + The package references of the preferred packages. + Must contain one package reference for each requested package-name. + + If you build command submissions whose content depends on the returned + preferred packages, then we recommend submitting the preferred package-ids + in the ``package_id_selection_preference`` of the command submission to + avoid race conditions with concurrent changes of the on-ledger package vetting state. + + Required: must be non-empty + synchronizerId: + type: string + description: |- + The synchronizer for which the package preferences are computed. + If the synchronizer_id was specified in the request, then it matches the request synchronizer_id. + + Required + com.daml.ledger.api.v2.interactive.GlobalKey: + type: object + properties: + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + packageName: + type: string + title: Required + key: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: Required + hash: + type: string + format: byte + title: 'Required: must be non-empty' + com.daml.ledger.api.v2.interactive.HashingSchemeVersion: + type: string + enum: + - HASHING_SCHEME_VERSION_UNSPECIFIED + - HASHING_SCHEME_VERSION_V2 + - HASHING_SCHEME_VERSION_V3 + default: HASHING_SCHEME_VERSION_UNSPECIFIED + title: |- + [docs-entry-start: HashingSchemeVersion] + The hashing scheme version used when building the hash of the PreparedTransaction + com.daml.ledger.api.v2.interactive.Metadata: + type: object + properties: + submitterInfo: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.Metadata.SubmitterInfo' + title: Required + synchronizerId: + type: string + title: Required + mediatorGroup: + type: integer + format: int64 + title: Required + transactionUuid: + type: string + title: Required + preparationTime: + type: string + format: uint64 + title: Required + inputContracts: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.Metadata.InputContract' + description: 'Optional: can be empty' + title: Not populated if the transaction has no input contracts + minLedgerEffectiveTime: + type: string + format: uint64 + title: Optional + maxLedgerEffectiveTime: + type: string + format: uint64 + title: Optional + globalKeyMapping: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.Metadata.GlobalKeyMappingEntry' + description: 'Optional: can be empty' + title: |- + Contextual information needed to process the transaction but not signed, either because it's already indirectly + signed by signing the transaction, or because it doesn't impact the ledger state + maxRecordTime: + type: string + format: uint64 + description: Optional + title: |- + Maximum timestamp at which the transaction can be recorded onto the ledger via the synchronizer `synchronizer_id`. + If submitted after it will be rejected even if otherwise valid, in which case it needs to be prepared and signed again + with a new valid max_record_time. + Unsigned in 3.3 to avoid a breaking protocol change + Will be signed in 3.4+ + Set max_record_time in the PreparedTransactionRequest to get this field set accordingly + description: |- + Transaction Metadata + Refer to the hashing documentation for information on how it should be hashed. + com.daml.ledger.api.v2.interactive.Metadata.GlobalKeyMappingEntry: + type: object + properties: + key: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.GlobalKey' + title: Required + value: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: Optional + com.daml.ledger.api.v2.interactive.Metadata.InputContract: + type: object + properties: + v1: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.transaction.v1.Create' + title: When new versions will be added, they will show here + createdAt: + type: string + format: uint64 + title: Required + eventBlob: + type: string + format: byte + title: 'Required: must be non-empty' + com.daml.ledger.api.v2.interactive.Metadata.SubmitterInfo: + type: object + properties: + actAs: + type: array + items: + type: string + title: 'Required: must be non-empty' + commandId: + type: string + title: Required + com.daml.ledger.api.v2.interactive.MinLedgerTime: + type: object + properties: + minLedgerTimeAbs: + type: string + format: date-time + title: |- + Lower bound for the ledger time assigned to the resulting transaction. + The ledger time of a transaction is assigned as part of command interpretation. + Important note: for interactive submissions, if the transaction depends on time, it **must** be signed + and submitted within a time window around the ledger time assigned to the transaction during the prepare method. + The time delta around that ledger time is a configuration of the ledger, usually short, around 1 minute. + If however the transaction does not depend on time, the available time window to sign and submit the transaction is bound + by the preparation time, which is also assigned in the "prepare" step (this request), + but can be configured with a much larger skew, allowing for more time to sign the request (in the order of hours). + Must not be set at the same time as min_ledger_time_rel. + Optional + minLedgerTimeRel: + type: string + title: |- + Same as min_ledger_time_abs, but specified as a duration, starting from the time this request is received by the server. + Must not be set at the same time as min_ledger_time_abs. + Optional + com.daml.ledger.api.v2.interactive.PackagePreference: + type: object + properties: + packageReference: + $ref: '#/definitions/com.daml.ledger.api.v2.PackageReference' + description: |- + The package reference of the preferred package. + + Required + synchronizerId: + type: string + description: |- + The synchronizer for which the preferred package was computed. + If the synchronizer_id was specified in the request, then it matches the request synchronizer_id. + + Required + com.daml.ledger.api.v2.interactive.PackageVettingRequirement: + type: object + properties: + parties: + type: array + items: + type: string + description: |- + The parties whose participants' vetting state should be considered when resolving the preferred package. + + Required: must be non-empty + packageName: + type: string + description: |- + The package-name for which the preferred package should be resolved. + + Required + description: Defines a package-name for which the commonly vetted package with the highest version must be found. + com.daml.ledger.api.v2.interactive.PartySignatures: + type: object + properties: + signatures: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.SinglePartySignatures' + description: 'Required: must be non-empty' + title: Additional signatures provided by all individual parties + title: Additional signatures provided by the submitting parties + com.daml.ledger.api.v2.interactive.PrepareSubmissionRequest: + type: object + properties: + userId: + type: string + description: |- + Uniquely identifies the participant user that prepares the transaction. + Must be a valid UserIdString (as described in ``value.proto``). + Required unless authentication is used with a user token. + In that case, the token's user-id will be used for the request's user_id. + + Optional + commandId: + type: string + description: |- + Uniquely identifies the command. + The triple (user_id, act_as, command_id) constitutes the change ID for the intended ledger change, + where act_as is interpreted as a set of party names. + The change ID can be used for matching the intended ledger changes with all their completions. + Must be a valid LedgerString (as described in ``value.proto``). + + Required + commands: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Command' + description: |- + Individual elements of this atomic command. Must be non-empty. + Limitation: Only single command transaction are currently supported by the API. + The field is marked as repeated in preparation for future support of multiple commands. + + Required: must be non-empty + minLedgerTime: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.MinLedgerTime' + title: Optional + maxRecordTime: + type: string + format: date-time + description: |- + Maximum timestamp at which the transaction can be recorded onto the ledger via the synchronizer specified in the `PrepareSubmissionResponse`. + If submitted after it will be rejected even if otherwise valid, in which case it needs to be prepared and signed again + with a new valid max_record_time. + Use this to limit the time-to-life of a prepared transaction, + which is useful to know when it can definitely not be accepted + anymore and resorting to preparing another transaction for the same + intent is safe again. + + Optional + actAs: + type: array + items: + type: string + description: |- + Set of parties on whose behalf the command should be executed, if submitted. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to **read** (not act) on behalf of each of the given parties. This is because this RPC merely prepares a transaction + and does not execute it. Therefore read authorization is sufficient even for actAs parties. + Note: This may change, and more specific authorization scope may be introduced in the future. + Each element must be a valid PartyIdString (as described in ``value.proto``). + + Required: must be non-empty + readAs: + type: array + items: + type: string + description: |- + Set of parties on whose behalf (in addition to all parties listed in ``act_as``) contracts can be retrieved. + This affects Daml operations such as ``fetch``, ``fetchByKey``, ``lookupByKey``, ``exercise``, and ``exerciseByKey``. + Note: A command can only use contracts that are visible to at least + one of the parties in ``act_as`` or ``read_as``. This visibility check is independent from the Daml authorization + rules for fetch operations. + If ledger API authorization is enabled, then the authorization metadata must authorize the sender of the request + to read contract data on behalf of each of the given parties. + + Optional: can be empty + disclosedContracts: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.DisclosedContract' + description: |- + Additional contracts used to resolve contract & contract key lookups. + + Optional: can be empty + synchronizerId: + type: string + description: Optional + title: |- + Must be a valid synchronizer id + If not set, a suitable synchronizer that this node is connected to will be chosen + packageIdSelectionPreference: + type: array + items: + type: string + description: 'Optional: can be empty' + title: |- + The package-id selection preference of the client for resolving + package names and interface instances in command submission and interpretation + verboseHashing: + type: boolean + description: Optional + title: |- + When true, the response will contain additional details on how the transaction was encoded and hashed + This can be useful for troubleshooting of hash mismatches. Should only be used for debugging. + Defaults to false + prefetchContractKeys: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.PrefetchContractKey' + description: |- + Fetches the contract keys into the caches to speed up the command processing. + Should only contain contract keys that are expected to be resolved during interpretation of the commands. + Keys of disclosed contracts do not need prefetching. + + Optional: can be empty + estimateTrafficCost: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.CostEstimationHints' + description: |- + Hints to improve the accuracy of traffic cost estimation. + The estimation logic assumes that this node will be used for the execution of the transaction + If another node is used instead, the estimation may be less precise. + Request amplification is not accounted for in the estimation: each amplified request will + result in the cost of the confirmation request to be charged additionally. + + Traffic cost estimation is enabled by default if this field is not set + To turn off cost estimation, set the CostEstimationHints#disabled field to true + + Optional + hashingSchemeVersion: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.HashingSchemeVersion' + description: |- + The hashing scheme version to be used when building the hash. + Defaults to HASHING_SCHEME_VERSION_V2. + + Optional + tapsMaxPasses: + type: integer + format: int64 + description: |- + The maximum number of passes for the Topology-Aware Package Selection (TAPS). + Higher values can increase the chance of successful package selection for routing of interpreted transactions. + If unset, this defaults to the value defined in the participant configuration. + The provided value must not exceed the limit specified in the participant configuration. + + Optional + com.daml.ledger.api.v2.interactive.PrepareSubmissionResponse: + type: object + properties: + preparedTransaction: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.PreparedTransaction' + description: |- + The interpreted transaction, it represents the ledger changes necessary to execute the commands specified in the request. + Clients MUST display the content of the transaction to the user for them to validate before signing the hash if the preparing participant is not trusted. + + Required + preparedTransactionHash: + type: string + format: byte + description: 'Required: must be non-empty' + title: |- + Hash of the transaction, this is what needs to be signed by the party to authorize the transaction. + Only provided for convenience, clients MUST recompute the hash from the raw transaction if the preparing participant is not trusted. + May be removed in future versions + hashingSchemeVersion: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.HashingSchemeVersion' + description: Required + title: The hashing scheme version used when building the hash + hashingDetails: + type: string + description: |- + Optional additional details on how the transaction was encoded and hashed. Only set if verbose_hashing = true in the request + Note that there are no guarantees on the stability of the format or content of this field. + Its content should NOT be parsed and should only be used for troubleshooting purposes. + + Optional + costEstimation: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.CostEstimation' + description: Optional + title: Traffic cost estimation of the prepared transaction + com.daml.ledger.api.v2.interactive.PreparedTransaction: + type: object + properties: + transaction: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.DamlTransaction' + description: Required + title: Daml Transaction representing the ledger effect if executed. See below + metadata: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.Metadata' + description: Required + title: Metadata context necessary to execute the transaction + title: |- + * + Prepared Transaction Message + com.daml.ledger.api.v2.interactive.SinglePartySignatures: + type: object + properties: + party: + type: string + description: Required + title: Submitting party + signatures: + type: array + items: + type: object + $ref: '#/definitions/com.daml.ledger.api.v2.Signature' + description: 'Required: must be non-empty' + title: Signatures + title: Signatures provided by a single party + com.daml.ledger.api.v2.interactive.transaction.v1.Create: + type: object + properties: + lfVersion: + type: string + description: Required + title: Specific LF version of the node + contractId: + type: string + title: Required + packageName: + type: string + title: Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + argument: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: Required + signatories: + type: array + items: + type: string + title: 'Required: must be non-empty' + stakeholders: + type: array + items: + type: string + title: 'Required: must be non-empty' + title: Create Node + com.daml.ledger.api.v2.interactive.transaction.v1.Exercise: + type: object + properties: + lfVersion: + type: string + description: Required + title: Specific LF version of the node + contractId: + type: string + title: Required + packageName: + type: string + title: Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + signatories: + type: array + items: + type: string + title: 'Required: must be non-empty' + stakeholders: + type: array + items: + type: string + title: 'Required: must be non-empty' + actingParties: + type: array + items: + type: string + title: 'Required: must be non-empty' + interfaceId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The identifier uses the package-id reference format. + + Optional + choiceId: + type: string + title: Required + chosenValue: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: Required + consuming: + type: boolean + title: Required + children: + type: array + items: + type: string + title: 'Optional: can be empty' + exerciseResult: + $ref: '#/definitions/com.daml.ledger.api.v2.Value' + title: Optional + choiceObservers: + type: array + items: + type: string + title: 'Optional: can be empty' + title: Exercise node + com.daml.ledger.api.v2.interactive.transaction.v1.Fetch: + type: object + properties: + lfVersion: + type: string + description: Required + title: Specific LF version of the node + contractId: + type: string + title: Required + packageName: + type: string + title: Required + templateId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + description: |- + The identifier uses the package-id reference format. + + Required + signatories: + type: array + items: + type: string + title: 'Required: must be non-empty' + stakeholders: + type: array + items: + type: string + title: 'Required: must be non-empty' + actingParties: + type: array + items: + type: string + title: 'Required: must be non-empty' + interfaceId: + $ref: '#/definitions/com.daml.ledger.api.v2.Identifier' + title: Optional + title: Fetch node + com.daml.ledger.api.v2.interactive.transaction.v1.Node: + type: object + properties: + create: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.transaction.v1.Create' + fetch: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.transaction.v1.Fetch' + exercise: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.transaction.v1.Exercise' + rollback: + $ref: '#/definitions/com.daml.ledger.api.v2.interactive.transaction.v1.Rollback' + com.daml.ledger.api.v2.interactive.transaction.v1.Rollback: + type: object + properties: + children: + type: array + items: + type: string + title: 'Required: must be non-empty' + title: Rollback Node + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: |- + A URL/resource name that uniquely identifies the type of the serialized + protocol buffer message. This string must contain at least + one "/" character. The last segment of the URL's path must represent + the fully qualified name of the type (as in + `path/google.protobuf.Duration`). The name should be in a canonical form + (e.g., leading "." is not accepted). + + In practice, teams usually precompile into the binary all types that they + expect it to use in the context of Any. However, for URLs which use the + scheme `http`, `https`, or no scheme, one can optionally set up a type + server that maps type URLs to message definitions as follows: + + * If no scheme is provided, `https` is assumed. + * An HTTP GET on the URL must yield a [google.protobuf.Type][] + value in binary format, or produce an error. + * Applications are allowed to cache lookup results based on the + URL, or have them precompiled into a binary to avoid any + lookup. Therefore, binary compatibility needs to be preserved + on changes to types. (Use versioned type names to manage + breaking changes.) + + Note: this functionality is not currently available in the official + protobuf release, and it is not used for type URLs beginning with + type.googleapis.com. As of May 2023, there are no widely used type server + implementations and no plans to implement one. + + Schemes other than `http`, `https` (or the empty scheme) might be + used with implementation specific semantics. + additionalProperties: {} + description: |- + `Any` contains an arbitrary serialized protocol buffer message along with a + URL that describes the type of the serialized message. + + Protobuf library provides support to pack/unpack Any values in the form + of utility functions or additional generated methods of the Any type. + + Example 1: Pack and unpack a message in C++. + + Foo foo = ...; + Any any; + any.PackFrom(foo); + ... + if (any.UnpackTo(&foo)) { + ... + } + + Example 2: Pack and unpack a message in Java. + + Foo foo = ...; + Any any = Any.pack(foo); + ... + if (any.is(Foo.class)) { + foo = any.unpack(Foo.class); + } + // or ... + if (any.isSameTypeAs(Foo.getDefaultInstance())) { + foo = any.unpack(Foo.getDefaultInstance()); + } + + Example 3: Pack and unpack a message in Python. + + foo = Foo(...) + any = Any() + any.Pack(foo) + ... + if any.Is(Foo.DESCRIPTOR): + any.Unpack(foo) + ... + + Example 4: Pack and unpack a message in Go + + foo := &pb.Foo{...} + any, err := anypb.New(foo) + if err != nil { + ... + } + ... + foo := &pb.Foo{} + if err := any.UnmarshalTo(foo); err != nil { + ... + } + + The pack methods provided by protobuf library will by default use + 'type.googleapis.com/full.type.name' as the type URL and the unpack + methods only use the fully qualified type name after the last '/' + in the type URL, for example "foo.bar.com/x/y.z" will yield type + name "y.z". + + JSON + ==== + The JSON representation of an `Any` value uses the regular + representation of the deserialized, embedded message, with an + additional field `@type` which contains the type URL. Example: + + package google.profile; + message Person { + string first_name = 1; + string last_name = 2; + } + + { + "@type": "type.googleapis.com/google.profile.Person", + "firstName": , + "lastName": + } + + If the embedded message type is well-known and has a custom JSON + representation, that representation will be embedded adding a field + `value` which holds the custom JSON in addition to the `@type` + field. Example (for message [google.protobuf.Duration][]): + + { + "@type": "type.googleapis.com/google.protobuf.Duration", + "value": "1.212s" + } + google.rpc.Status: + type: object + properties: + code: + type: integer + format: int32 + description: |- + The status code, which should be an enum value of + [google.rpc.Code][google.rpc.Code]. + message: + type: string + description: |- + A developer-facing error message, which should be in English. Any + user-facing error message should be localized and sent in the + [google.rpc.Status.details][google.rpc.Status.details] field, or localized + by the client. + details: + type: array + items: + type: object + $ref: '#/definitions/google.protobuf.Any' + description: |- + A list of messages that carry the error details. There is a common set of + message types for APIs to use. + description: |- + The `Status` type defines a logical error model that is suitable for + different programming environments, including REST APIs and RPC APIs. It is + used by [gRPC](https://github.com/grpc). Each `Status` message contains + three pieces of data: error code, error message, and error details. + + You can find out more about this error model and how to work with it in the + [API Design Guide](https://cloud.google.com/apis/design/errors).