/v2/contracts/contract-by-id
Documentation Index
Fetch the complete documentation index at: https://docs.canton.network/llms.txt Use this file to discover all available pages before exploring further.
/v2/contracts/contract-by-id
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.
OpenAPI
openapi: 3.0.3
info:
title: JSON Ledger API HTTP endpoints
version: 3.5.0-SNAPSHOT
description: >-
This specification version fixes the API inconsistencies where certain
fields marked as required in the spec are in fact optional.
If you use code generation tool based on this file, you might need to adjust
the existing application code to handle those fields as optional.
If you do not want to change your client code, continue using the OpenAPI
specification for the latest Canton 3.4 patch release.
MINIMUM_CANTON_VERSION=3.5.0
servers: []
security: []
paths:
/v2/contracts/contract-by-id:
post:
summary: /v2/contracts/contract-by-id
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.
operationId: postV2ContractsContract-by-id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetContractRequest'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetContractResponse'
'400':
description: 'Invalid value, Invalid value for: body'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/JsCantonError'
security:
- httpAuth: []
- apiKeyAuth: []
components:
schemas:
GetContractRequest:
title: GetContractRequest
type: object
required:
- contractId
properties:
contractId:
description: |-
The ID of the contract.
Must be a valid LedgerString (as described in ``value.proto``).
Required
type: string
queryingParties:
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
type: array
items:
type: string
GetContractResponse:
title: GetContractResponse
type: object
required:
- createdEvent
properties:
createdEvent:
$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
JsCantonError:
title: JsCantonError
type: object
required:
- code
- cause
- context
- errorCategory
properties:
code:
type: string
cause:
type: string
correlationId:
type: string
traceId:
type: string
context:
$ref: '#/components/schemas/Map_String'
resources:
type: array
items:
$ref: '#/components/schemas/Tuple2_String_String'
errorCategory:
type: integer
format: int32
grpcCodeValue:
type: integer
format: int32
retryInfo:
type: string
definiteAnswer:
type: boolean
CreatedEvent:
title: CreatedEvent
description: >-
Records that a contract has been created, and choices may now be
exercised on it.
type: object
required:
- offset
- nodeId
- contractId
- templateId
- createdAt
- packageName
- representativePackageId
- acsDelta
- createArgument
- witnessParties
- signatories
properties:
offset:
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
type: integer
format: int64
nodeId:
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
type: integer
format: int32
contractId:
description: |-
The ID of the created contract.
Must be a valid LedgerString (as described in ``value.proto``).
Required
type: string
templateId:
description: |-
The template of the created contract.
The identifier uses the package-id reference format.
Required
type: string
contractKey:
description: >-
The key of the created contract.
This will be set if and only if ``template_id`` defines a contract
key.
Optional
contractKeyHash:
description: >-
The hash of contract_key.
This will be set if and only if ``template_id`` defines a contract
key.
Optional: can be empty
type: string
createArgument:
description: |-
The arguments that have been used to create the contract.
Required
createdEventBlob:
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
type: string
interfaceViews:
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
type: array
items:
$ref: '#/components/schemas/JsInterfaceView'
witnessParties:
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
type: array
items:
type: string
signatories:
description: |-
The signatories for this contract as specified by the template.
Required: must be non-empty
type: array
items:
type: string
observers:
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
type: array
items:
type: string
createdAt:
description: |-
Ledger effective time of the transaction that created the contract.
Required
type: string
packageName:
description: |-
The package name of the created contract.
Required
type: string
representativePackageId:
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
type: string
acsDelta:
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
type: boolean
Map_String:
title: Map_String
type: object
additionalProperties:
type: string
Tuple2_String_String:
title: Tuple2_String_String
type: array
maxItems: 2
minItems: 2
items:
type: string
JsInterfaceView:
title: JsInterfaceView
description: View of a create event matched by an interface filter.
type: object
required:
- interfaceId
- viewStatus
properties:
interfaceId:
description: |-
The interface implemented by the matched event.
The identifier uses the package-id reference format.
Required
type: string
viewStatus:
$ref: '#/components/schemas/JsStatus'
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:
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:
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
type: string
JsStatus:
title: JsStatus
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/ProtoAny'
ProtoAny:
title: ProtoAny
type: object
required:
- typeUrl
- value
- unknownFields
properties:
typeUrl:
type: string
value:
type: string
unknownFields:
$ref: '#/components/schemas/UnknownFieldSet'
valueDecoded:
type: string
UnknownFieldSet:
title: UnknownFieldSet
type: object
required:
- fields
properties:
fields:
$ref: '#/components/schemas/Map_Int_Field'
Map_Int_Field:
title: Map_Int_Field
type: object
additionalProperties:
$ref: '#/components/schemas/Field'
Field:
title: Field
type: object
properties:
varint:
type: array
items:
type: integer
format: int64
fixed64:
type: array
items:
type: integer
format: int64
fixed32:
type: array
items:
type: integer
format: int32
lengthDelimited:
type: array
items:
type: string
securitySchemes:
httpAuth:
type: http
description: Ledger API standard JWT token
scheme: bearer
apiKeyAuth:
type: apiKey
description: Ledger API standard JWT token (websocket)
name: Sec-WebSocket-Protocol
in: header
Mirrored from Canton Network official documentation (CC-BY-4.0) by CC Privacy Club for learning purposes.