Skip to content
CCPEDIAby Unity Nodes
Documentation/Canton Network Docs/Ledger APIOpenAPIView on Canton Network Docs

POST /v2/updates

POST
/
v2
/
updates
Try it
cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
  --url 'http://localhost:7575/v2/updates' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}'
import json
import requests

url = "http://localhost:7575/v2/updates"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}''')
response = requests.request(
    "POST", url, headers=headers, json=payload
)

print(response.text)
const response = await fetch('http://localhost:7575/v2/updates', {
  method: 'POST',
  headers: {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}),
});

console.log(await response.text());
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'http://localhost:7575/v2/updates',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}
JSON,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <token>",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
echo $response;
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:7575/v2/updates", bytes.NewBufferString(`{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}`))
  req.Header.Set("Authorization", "Bearer <token>")
  req.Header.Set("Content-Type", "application/json")
  response, _ := http.DefaultClient.Do(req)
  defer response.Body.Close()
  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:7575/v2/updates"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}
"""))
    .build();
var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'

uri = URI('http://localhost:7575/v2/updates')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(request)
end
puts response.body
200
400
default
[
  {
    "update": {
      "OffsetCheckpoint": {
        "value": {
          "offset": 123,
          "synchronizerTimes": [
            "<object>"
          ]
        }
      }
    }
  }
]
<string>
{
  "code": "<string>",
  "cause": "<string>",
  "correlationId": "<string>",
  "traceId": "<string>",
  "context": {},
  "resources": [
    [
      "<string>"
    ]
  ],
  "errorCategory": 123,
  "grpcCodeValue": 123,
  "retryInfo": "<string>",
  "definiteAnswer": false
}

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.

cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
  --url 'http://localhost:7575/v2/updates' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}'
import json
import requests

url = "http://localhost:7575/v2/updates"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}''')
response = requests.request(
    "POST", url, headers=headers, json=payload
)

print(response.text)
const response = await fetch('http://localhost:7575/v2/updates', {
  method: 'POST',
  headers: {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}),
});

console.log(await response.text());
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'http://localhost:7575/v2/updates',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}
JSON,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <token>",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
echo $response;
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:7575/v2/updates", bytes.NewBufferString(`{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}`))
  req.Header.Set("Authorization", "Bearer <token>")
  req.Header.Set("Content-Type", "application/json")
  response, _ := http.DefaultClient.Do(req)
  defer response.Body.Close()
  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:7575/v2/updates"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}
"""))
    .build();
var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'

uri = URI('http://localhost:7575/v2/updates')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
  "beginExclusive": 123,
  "endInclusive": 123,
  "filter": {
    "filtersByParty": {},
    "filtersForAnyParty": {
      "cumulative": [
        {
          "identifierFilter": {
            "Empty": "<object>"
          }
        }
      ]
    }
  },
  "verbose": false,
  "updateFormat": {
    "includeTransactions": {
      "eventFormat": {
        "filtersByParty": {},
        "filtersForAnyParty": {
          "cumulative": [
            "<object>"
          ]
        },
        "verbose": false
      },
      "transactionShape": "TRANSACTION_SHAPE_UNSPECIFIED"
    },
    "includeReassignments": {
      "filtersByParty": {},
      "filtersForAnyParty": {
        "cumulative": [
          {
            "identifierFilter": "<object>"
          }
        ]
      },
      "verbose": false
    },
    "includeTopologyEvents": {
      "includeParticipantAuthorizationEvents": {
        "parties": [
          "<string>"
        ]
      }
    }
  },
  "descendingOrder": false
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(request)
end
puts response.body
200
400
default
[
  {
    "update": {
      "OffsetCheckpoint": {
        "value": {
          "offset": 123,
          "synchronizerTimes": [
            "<object>"
          ]
        }
      }
    }
  }
]
<string>
{
  "code": "<string>",
  "cause": "<string>",
  "correlationId": "<string>",
  "traceId": "<string>",
  "context": {},
  "resources": [
    [
      "<string>"
    ]
  ],
  "errorCategory": 123,
  "grpcCodeValue": 123,
  "retryInfo": "<string>",
  "definiteAnswer": false
}

Authorizations

httpAuth

Authorization
string
required
HTTP bearer authentication. Send the token as Authorization: Bearer &lt;token&gt;. Ledger API standard JWT token

apiKeyAuth

Sec-WebSocket-Protocol
string
required
API key authentication in the header. Ledger API standard JWT token (websocket)

Query parameters

limit
number
OpenAPI type: integer (int64).maximum number of elements to return, this param is ignored if is bigger than server setting
stream_idle_timeout_ms
number
OpenAPI type: integer (int64).timeout to complete and send result if no new elements are received (for open ended streams)

Body

application/json
beginExclusive
number
required
OpenAPI type: integer (int64).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. Required
endInclusive
number
OpenAPI type: integer (int64).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
filter
object
OpenAPI type: TransactionFilter.Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. Used both for filtering create and archive events as well as for filtering transaction trees.

Show child attributes

filtersByParty
object
OpenAPI type: Map_Filters.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 transaction trees (used in GetUpdateTreesResponse for backwards compatibility) all party keys used as wildcard filters, and all subtrees whose root has one of the listed parties as an informee are returned. If there are CumulativeFilters, those will control returned CreatedEvent fields where applicable, but will not be used for template/interface filtering. 2. 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. 3. 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.
filtersForAnyParty
object
OpenAPI type: Filters.The union of a set of template filters, interface filters, or a wildcard.

Show child attributes

cumulative
object[]
OpenAPI type: 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

Show child attributes

identifierFilter
object
OpenAPI type: IdentifierFilter.Required

Show child attributes

Variant 1
object

Show child attributes

Empty
object
required
OpenAPI type: Empty1.
Variant 2
object

Show child attributes

InterfaceFilter
object
required
OpenAPI type: InterfaceFilter.This filter matches contracts that implement a specific interface.

Show child attributes

value
object
required
OpenAPI type: InterfaceFilter1.This filter matches contracts that implement a specific interface.

Show child attributes

interfaceId
string
required
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
boolean
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
boolean
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
Variant 3
object

Show child attributes

TemplateFilter
object
required
OpenAPI type: TemplateFilter.This filter matches contracts of a specific template.

Show child attributes

value
object
required
OpenAPI type: TemplateFilter1.This filter matches contracts of a specific template.

Show child attributes

templateId
string
required
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
boolean
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
Variant 4
object

Show child attributes

WildcardFilter
object
required
OpenAPI type: WildcardFilter.This filter matches all templates.

Show child attributes

value
object
required
OpenAPI type: WildcardFilter1.This filter matches all templates.

Show child attributes

includeCreatedEventBlob
boolean
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
verbose
boolean
Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. 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, record and variant type ids for record fields. Optional for backwards compatibility, if defined update_format must be unset
updateFormat
object
OpenAPI type: UpdateFormat.A format specifying what updates to include and how to render them.

Show child attributes

includeTransactions
object
OpenAPI type: TransactionFormat.A format that specifies what events to include in Daml transactions and what data to compute and include for them.

Show child attributes

eventFormat
object
required
OpenAPI type: EventFormat.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.

Show child attributes

filtersByParty
object
OpenAPI type: Map_Filters.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
filtersForAnyParty
object
OpenAPI type: Filters.The union of a set of template filters, interface filters, or a wildcard.

Show child attributes

cumulative
object[]
OpenAPI type: 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

Show child attributes

identifierFilter
object
OpenAPI type: IdentifierFilter.Required

Show child attributes

Variant 1
object

Show child attributes

Empty
object
required
OpenAPI type: Empty1.
Variant 2
object

Show child attributes

InterfaceFilter
object
required
OpenAPI type: InterfaceFilter.This filter matches contracts that implement a specific interface.

Show child attributes

value
object
required
OpenAPI type: InterfaceFilter1.This filter matches contracts that implement a specific interface.

Show child attributes

interfaceId
string
required
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
boolean
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
boolean
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
Variant 3
object

Show child attributes

TemplateFilter
object
required
OpenAPI type: TemplateFilter.This filter matches contracts of a specific template.

Show child attributes

value
object
required
OpenAPI type: TemplateFilter1.This filter matches contracts of a specific template.

Show child attributes

templateId
string
required
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
boolean
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
Variant 4
object

Show child attributes

WildcardFilter
object
required
OpenAPI type: WildcardFilter.This filter matches all templates.

Show child attributes

value
object
required
OpenAPI type: WildcardFilter1.This filter matches all templates.

Show child attributes

includeCreatedEventBlob
boolean
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
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
string
required
What transaction shape to use for interpreting the filters of the event format. RequiredAllowed values: TRANSACTION_SHAPE_UNSPECIFIED, TRANSACTION_SHAPE_ACS_DELTA, TRANSACTION_SHAPE_LEDGER_EFFECTS.
includeReassignments
object
OpenAPI type: EventFormat.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.

Show child attributes

filtersByParty
object
OpenAPI type: Map_Filters.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
filtersForAnyParty
object
OpenAPI type: Filters.The union of a set of template filters, interface filters, or a wildcard.

Show child attributes

cumulative
object[]
OpenAPI type: 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

Show child attributes

identifierFilter
object
OpenAPI type: IdentifierFilter.Required

Show child attributes

Variant 1
object

Show child attributes

Empty
object
required
OpenAPI type: Empty1.
Variant 2
object

Show child attributes

InterfaceFilter
object
required
OpenAPI type: InterfaceFilter.This filter matches contracts that implement a specific interface.

Show child attributes

value
object
required
OpenAPI type: InterfaceFilter1.This filter matches contracts that implement a specific interface.

Show child attributes

interfaceId
string
required
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
boolean
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
boolean
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
Variant 3
object

Show child attributes

TemplateFilter
object
required
OpenAPI type: TemplateFilter.This filter matches contracts of a specific template.

Show child attributes

value
object
required
OpenAPI type: TemplateFilter1.This filter matches contracts of a specific template.

Show child attributes

templateId
string
required
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
boolean
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
Variant 4
object

Show child attributes

WildcardFilter
object
required
OpenAPI type: WildcardFilter.This filter matches all templates.

Show child attributes

value
object
required
OpenAPI type: WildcardFilter1.This filter matches all templates.

Show child attributes

includeCreatedEventBlob
boolean
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
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
includeTopologyEvents
object
OpenAPI type: TopologyFormat.A format specifying which topology transactions to include and how to render them.

Show child attributes

includeParticipantAuthorizationEvents
object
OpenAPI type: ParticipantAuthorizationTopologyFormat.A format specifying which participant authorization topology transactions to include and how to render them.

Show child attributes

parties
string[]
List of parties for which the topology transactions should be sent. Empty means: for all parties. Optional: can be empty
descendingOrder
boolean
If set, the stream will populate the elements in descending order. Optional

Responses

200

application/json
value
JsGetUpdatesResponse[]
required

Show child attributes

update
Update

Show child attributes

Variant 1
object

Show child attributes

OffsetCheckpoint
OffsetCheckpoint2
required
OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption.

Show child attributes

value
OffsetCheckpoint1
required
OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption.

Show child attributes

offset
integer (int64)
required
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
SynchronizerTime[]
The times associated with each synchronizer at this offset. Optional: can be empty

Show child attributes

synchronizerId
string
required
The id of the synchronizer. Required
recordTime
string
required
All commands with a maximum record time below this value MUST be considered lost if their completion has not arrived before this checkpoint. Required
Variant 2
object

Show child attributes

Reassignment
Reassignment
required
Complete view of an on-ledger reassignment.

Show child attributes

value
JsReassignment
required
Complete view of an on-ledger reassignment.

Show child attributes

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 reassignment. Missing for everyone except the submitting party on the submitting participant. Must be a valid LedgerString (as described in value.proto). Optional
workflowId
string
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
integer (int64)
required
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
JsReassignmentEvent[]
required
The collection of reassignment events. Required: must be non-empty

Show child attributes

Variant 1
object

Show child attributes

JsAssignmentEvent
JsAssignmentEvent
required

Show child attributes

source
string
required
target
string
required
reassignmentId
string
required
submitter
string
required
reassignmentCounter
integer (int64)
required
createdEvent
CreatedEvent
required
Records that a contract has been created, and choices may now be exercised on it.

Show child attributes

offset
integer (int64)
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 (int32)
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
object
The key of the created contract. This will be set if and only if template_id defines a contract key. Optional
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
object
required
The arguments that have been used to create the contract. 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

Show child attributes

interfaceId
string
required
The interface implemented by the matched event. The identifier uses the package-id reference format. Required
viewStatus
JsStatus
required
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

Show child attributes

code
integer (int32)
required
message
string
required
details
ProtoAny[]
viewValue
object
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
string
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
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 TopologyEvents 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
Variant 2
object

Show child attributes

JsUnassignedEvent
JsUnassignedEvent
required
Records that a contract has been unassigned, and it becomes unusable on the source synchronizer

Show child attributes

value
UnassignedEvent
required
Records that a contract has been unassigned, and it becomes unusable on the source synchronizer

Show child attributes

reassignmentId
string
required
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
string
required
The ID of the reassigned contract. Must be a valid LedgerString (as described in value.proto). Required
templateId
string
required
The template of the reassigned contract. The identifier uses the package-id reference format. Required
source
string
required
The ID of the source synchronizer Must be a valid synchronizer id Required
target
string
required
The ID of the target synchronizer Must be a valid synchronizer id Required
submitter
string
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
integer (int64)
required
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
string
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
string[]
required
The parties that are notified of this event. Required: must be non-empty
packageName
string
required
The package name of the contract. Required
offset
integer (int64)
required
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
nodeId
integer (int32)
required
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
traceContext
TraceContext
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

Show child attributes

traceparent
string
tracestate
string
Optional
recordTime
string
required
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
string
required
A valid synchronizer id. Identifies the synchronizer that synchronized this Reassignment. Required
paidTrafficCost
integer (int64)
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
Variant 3
object

Show child attributes

TopologyTransaction
TopologyTransaction
required

Show child attributes

value
JsTopologyTransaction
required

Show child attributes

updateId
string
required
Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in value.proto). Required
offset
integer (int64)
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 topology transaction. Required
recordTime
string
required
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
TopologyEvent[]
required
A non-empty list of topology events. Required: must be non-empty

Show child attributes

event
TopologyEventEvent

Show child attributes

Variant 1
object

Show child attributes

Empty
Empty7
required
Variant 2
object

Show child attributes

ParticipantAuthorizationAdded
ParticipantAuthorizationAdded
required

Show child attributes

value
ParticipantAuthorizationAdded1
required

Show child attributes

partyId
string
required
Required
participantId
string
required
Required
participantPermission
string
required
RequiredAllowed values: PARTICIPANT_PERMISSION_UNSPECIFIED, PARTICIPANT_PERMISSION_SUBMISSION, PARTICIPANT_PERMISSION_CONFIRMATION, PARTICIPANT_PERMISSION_OBSERVATION.
Variant 3
object

Show child attributes

ParticipantAuthorizationChanged
ParticipantAuthorizationChanged
required

Show child attributes

value
ParticipantAuthorizationChanged1
required

Show child attributes

partyId
string
required
Required
participantId
string
required
Required
participantPermission
string
required
RequiredAllowed values: PARTICIPANT_PERMISSION_UNSPECIFIED, PARTICIPANT_PERMISSION_SUBMISSION, PARTICIPANT_PERMISSION_CONFIRMATION, PARTICIPANT_PERMISSION_OBSERVATION.
Variant 4
object

Show child attributes

ParticipantAuthorizationOnboarding
ParticipantAuthorizationOnboarding
required

Show child attributes

value
ParticipantAuthorizationOnboarding1
required

Show child attributes

partyId
string
required
Required
participantId
string
required
Required
participantPermission
string
required
RequiredAllowed values: PARTICIPANT_PERMISSION_UNSPECIFIED, PARTICIPANT_PERMISSION_SUBMISSION, PARTICIPANT_PERMISSION_CONFIRMATION, PARTICIPANT_PERMISSION_OBSERVATION.
Variant 5
object

Show child attributes

ParticipantAuthorizationRevoked
ParticipantAuthorizationRevoked
required

Show child attributes

value
ParticipantAuthorizationRevoked1
required

Show child attributes

partyId
string
required
Required
participantId
string
required
Required
traceContext
TraceContext
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

Show child attributes

traceparent
string
tracestate
string
Optional
Variant 4
object

Show child attributes

Transaction
Transaction
required
Filtered view of an on-ledger transaction’s create and archive events.

Show child attributes

value
JsTransaction
required
Filtered view of an on-ledger transaction’s create and archive events.

Show child attributes

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

Show child attributes

Variant 1
object

Show child attributes

ArchivedEvent
ArchivedEvent
required
Records that a contract has been archived, and choices may no longer be exercised on it.

Show child attributes

offset
integer (int64)
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 (int32)
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
Variant 2
object

Show child attributes

CreatedEvent
CreatedEvent
required
Records that a contract has been created, and choices may now be exercised on it.

Show child attributes

offset
integer (int64)
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 (int32)
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
object
The key of the created contract. This will be set if and only if template_id defines a contract key. Optional
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
object
required
The arguments that have been used to create the contract. 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

Show child attributes

interfaceId
string
required
The interface implemented by the matched event. The identifier uses the package-id reference format. Required
viewStatus
JsStatus
required
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

Show child attributes

code
integer (int32)
required
message
string
required
details
ProtoAny[]

Show child attributes

typeUrl
string
required
value
string
required
unknownFields
UnknownFieldSet
required
valueDecoded
string
viewValue
object
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
string
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
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 TopologyEvents 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
Variant 3
object

Show child attributes

ExercisedEvent
ExercisedEvent
required
Records that a choice has been exercised on a target contract.

Show child attributes

offset
integer (int64)
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 (int32)
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
object
required
The argument of the exercised choice. 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 (int32)
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
object
The result of exercising the choice. Optional
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 (int64)
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
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

Show child attributes

traceparent
string
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 (int64)
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

400

Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms
text/plain
value
string
required

default

application/json
code
string
required
cause
string
required
correlationId
string
traceId
string
context
Map_String
required
resources
Tuple2_String_String[]
errorCategory
integer (int32)
required
grpcCodeValue
integer (int32)
retryInfo
string
definiteAnswer
boolean

History

Updated3.5

The POST /v2/updates operation changed in this snapshot.