--- title: "POST /v2/updates/transaction-by-id" method: POST path: "/v2/updates/transaction-by-id" deprecated: true --- # POST /v2/updates/transaction-by-id `POST /v2/updates/transaction-by-id` > **Deprecated.** Get transaction by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. ## Request body - GetTransactionByIdRequest — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. - `updateId` string, required — The ID of a particular transaction. Must be a valid LedgerString (as described in ``value.proto``). Required - `requestingParties` string[] — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. The parties whose events the client expects to see. Events that are not visible for the parties in this collection will not be present in the response. Each element must be a valid PartyIdString (as described in ``value.proto``). Optional for backwards compatibility for GetTransactionById request: if defined transaction_format must be unset (falling back to defaults). - `transactionFormat` TransactionFormat — A format that specifies what events to include in Daml transactions and what data to compute and include for them. - `eventFormat` EventFormat, required — 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`. - `filtersByParty` MapFilters - `filtersForAnyParty` Filters — The union of a set of template filters, interface filters, or a wildcard. - `cumulative` CumulativeFilter[] — 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 - `identifierFilter` union — Required - object - … - object - … - object - … - object - … - `verbose` boolean — 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 - `transactionShape` 'TRANSACTION_SHAPE_UNSPECIFIED' | 'TRANSACTION_SHAPE_ACS_DELTA' | 'TRANSACTION_SHAPE_LEDGER_EFFECTS', required — What transaction shape to use for interpreting the filters of the event format. Required ## Response `200` - JsGetTransactionResponse — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. - `transaction` JsTransaction, required — Filtered view of an on-ledger transaction's create and archive events. - `updateId` string, required — Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in ``value.proto``). Required - `commandId` string — The ID of the command which resulted in this transaction. Missing for everyone except the submitting party. Must be a valid LedgerString (as described in ``value.proto``). Optional - `workflowId` string — The workflow ID used in command submission. Must be a valid LedgerString (as described in ``value.proto``). Optional - `effectiveAt` string, required — Ledger effective time. Required - `events` Event[], required — 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 - union — 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. - object - `ArchivedEvent` ArchivedEvent, required — Records that a contract has been archived, and choices may no longer be exercised on it. - `offset` integer, required — 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 - `nodeId` integer, required — 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 - `contractId` string, required — The ID of the archived contract. Must be a valid LedgerString (as described in ``value.proto``). Required - `templateId` string, required — 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` string[], required — 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` string, required — The package name of the contract. Required - `implementedInterfaces` string[] — 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 - object - `CreatedEvent` CreatedEvent, required — Records that a contract has been created, and choices may now be exercised on it. - `offset` integer, required — 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 - `nodeId` integer, required — 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 - `contractId` string, required — The ID of the created contract. Must be a valid LedgerString (as described in ``value.proto``). Required - `templateId` string, required — The template of the created contract. The identifier uses the package-id reference format. Required - `contractKey` unknown - `contractKeyHash` string — The hash of contract_key. This will be set if and only if ``template_id`` defines a contract key. Optional: can be empty - `createArgument` unknown, required - `createdEventBlob` string — 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` JsInterfaceView[] — 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 - … - `witnessParties` string[], required — 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` string[], required — The signatories for this contract as specified by the template. Required: must be non-empty - `observers` string[] — 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` string, required — Ledger effective time of the transaction that created the contract. Required - `packageName` string, required — The package name of the created contract. Required - `representativePackageId` string, required — 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 - `acsDelta` boolean, required — 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 - object - `ExercisedEvent` ExercisedEvent, required — Records that a choice has been exercised on a target contract. - `offset` integer, required — 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 - `nodeId` integer, required — 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 - `contractId` string, required — The ID of the target contract. Must be a valid LedgerString (as described in ``value.proto``). Required - `templateId` string, required — 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` string — The interface where the choice is defined, if inherited. If defined, the identifier uses the package-id reference format. Optional - `choice` string, required — The choice that was exercised on the target contract. Must be a valid NameString (as described in ``value.proto``). Required - `choiceArgument` unknown, required - `actingParties` string[], required — The parties that exercised the choice. Each element must be a valid PartyIdString (as described in ``value.proto``). Required: must be non-empty - `consuming` boolean, required — If true, the target contract may no longer be exercised. Required - `witnessParties` string[], required — 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` integer, required — 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` unknown - `packageName` string, required — The package name of the contract. Required - `implementedInterfaces` string[] — 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` boolean, required — 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 - `offset` integer, required — 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` string, required — A valid synchronizer id. Identifies the synchronizer that synchronized the transaction. Required - `traceContext` TraceContext - `traceparent` string — https://www.w3.org/TR/trace-context/ Optional - `tracestate` string — Optional - `recordTime` string, required — The time at which the transaction was recorded. The record time refers to the synchronizer which synchronized the transaction. Required - `externalTransactionHash` string — 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` integer — 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 ## Other responses - `400` — Invalid value, Invalid value for: body - `default` --- [API](https://skmtc.dev/canton/apis/json-ledger-api-http-endpoints.md) · [All operations](https://skmtc.dev/canton/apis/json-ledger-api-http-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/canton/json-ledger-api-http-endpoints/revisions/296292e8b8f1/schema)