package v2
Interfaces to read from and write to an (abstract) participant state.
A Daml ledger participant is code that allows to actively participate in the evolution of a shared Daml ledger. Each such participant maintains a particular view onto the state of the Daml ledger. We call this view the participant state.
Actual implementations of a Daml ledger participant will likely maintain more state than what is exposed through the interfaces in this package, which is why we talk about an abstract participant state. It abstracts over the different implementations of Daml ledger participants.
The interfaces are optimized for easy implementation. The v2.WriteService interface contains the methods for changing the participant state (and potentially the state of the Daml ledger), which all ledger participants must support. These methods are for example exposed via the Daml Ledger API. Actual ledger participant implementations likely support more implementation-specific methods. They are however not exposed via the Daml Ledger API. The v2.ReadService interface contains the one method v2.ReadService.stateUpdates to read the state of a ledger participant. It represents the participant state as a stream of v2.Updates to an initial participant state. The typical consumer of this method is a class that subscribes to this stream of v2.Updates and reconstructs (a view of) the actual participant state. See the comments on v2.Update and v2.ReadService.stateUpdates for details about the kind of updates and the guarantees given to consumers of the stream of v2.Updates.
We do expect the interfaces provided in com.daml.ledger.participant.state to evolve, which is why we provide them all in the com.daml.ledger.participant.state.v2 package. Where possible we will evolve them in a backwards compatible fashion, so that a simple recompile suffices to upgrade to a new version. Where that is not possible, we plan to introduce new version of this API in a separate package and maintain it side-by-side with the existing version if possible. There can therefore potentially be multiple versions of participant state APIs at the same time. We plan to deprecate and drop old versions on separate and appropriate timelines.
- Alphabetic
- By Inheritance
- v2
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Type Members
- final case class ChangeId(applicationId: ApplicationId, commandId: CommandId, actAs: Set[Party]) extends Product with Serializable
Identifier for ledger changes used by command deduplication.
Identifier for ledger changes used by command deduplication. Equality is defined in terms of the cryptographic hash.
- See also
ReadService.stateUpdates for the command deduplication guarantee
- case class CompletionInfo(actAs: List[Party], applicationId: ApplicationId, commandId: CommandId, optDeduplicationPeriod: Option[DeduplicationPeriod], submissionId: Option[SubmissionId], statistics: Option[TransactionNodeStatistics]) extends Product with Serializable
Information about a completion for a submission.
Information about a completion for a submission.
- actAs
the non-empty set of parties that submitted the change.
- applicationId
an identifier for the Daml application that submitted the command.
- commandId
a submitter-provided identifier to identify an intended ledger change within all the submissions by the same parties and application.
- optDeduplicationPeriod
The deduplication period that the WriteService actually uses for the command submission. It may differ from the suggested deduplication period given to WriteService.submitTransaction. For example, the suggested deduplication period may have been converted into a different kind or extended. The particular choice depends on the particular implementation. This allows auditing the deduplication guarantee described in the ReadService.stateUpdates. Optional as some implementations may not be able to provide this deduplication information. If an implementation does not provide this deduplication information, it MUST adhere to the deduplication guarantee under a sensible interpretation of the corresponding CompletionInfo.optDeduplicationPeriod.
- submissionId
An identifier for the submission that allows an application to correlate completions to its submissions. Optional as entries created by the participant.state.v1 API do not have this filled. Only set for participant.state.v2 created entries
- statistics
The statistics that will be used by participant metering.
- final case class DivulgedContract(contractId: ContractId, contractInst: VersionedContractInstance) extends Product with Serializable
A divulged contract, that is, a contract that has been revealed to a non-stakeholder after its creation.
A divulged contract, that is, a contract that has been revealed to a non-stakeholder after its creation. For more information on divulgence, see: https://docs.daml.com/concepts/ledger-model/ledger-privacy.html#divulgence-when-non-stakeholders-see-contracts
- sealed trait PruningResult extends Product with Serializable
- trait ReadService extends ReportsHealth
An interface for reading the state of a ledger participant.
An interface for reading the state of a ledger participant. Please note that this interface is unstable and may significantly change.
The state of a ledger participant is communicated as a stream of state Updates. That stream is accessible via ReadService!.stateUpdates. Commonly that stream is processed by a single consumer that keeps track of the current state and creates indexes to satisfy read requests against that state.
See com.daml.ledger.participant.state.v2 for further architectural information. See Update for a description of the state updates communicated by ReadService!.stateUpdates.
- sealed abstract class SubmissionResult extends Product with Serializable
- final case class SubmitterInfo(actAs: List[Party], readAs: List[Party], applicationId: ApplicationId, commandId: CommandId, deduplicationPeriod: DeduplicationPeriod, submissionId: Option[SubmissionId], ledgerConfiguration: Configuration) extends Product with Serializable
Collects context information for a submission.
Collects context information for a submission.
Note that this is used for party-originating changes only. They are usually issued via the Ledger API.
- actAs
the non-empty set of parties that submitted the change.
- readAs
the parties on whose behalf (in addition to all parties listed in actAs) contracts can be retrieved.
- applicationId
an identifier for the Daml application that submitted the command. This is used for monitoring, command deduplication, and to allow Daml applications subscribe to their own submissions only.
- commandId
a submitter-provided identifier to identify an intended ledger change within all the submissions by the same parties and application.
- deduplicationPeriod
The deduplication period for the command submission. Used for the deduplication guarantee described in the ReadService.stateUpdates.
- submissionId
An identifier for the submission that allows an application to correlate completions to its submissions.
- ledgerConfiguration
The ledger configuration used during interpretation.
- final case class TransactionMeta(ledgerEffectiveTime: Timestamp, workflowId: Option[WorkflowId], submissionTime: Timestamp, submissionSeed: Hash, optUsedPackages: Option[Set[PackageId]], optNodeSeeds: Option[ImmArray[(NodeId, Hash)]], optByKeyNodes: Option[ImmArray[NodeId]]) extends Product with Serializable
Meta-data of a transaction visible to all parties that can see a part of the transaction.
- sealed trait Update extends Product with Serializable
An update to the (abstract) participant state.
An update to the (abstract) participant state.
Update's are used in ReadService.stateUpdates to communicate changes to abstract participant state to consumers.
We describe the possible updates in the comments of each of the case classes implementing Update.
- trait WriteConfigService extends AnyRef
- trait WritePackagesService extends AnyRef
An interface for uploading packages via a participant.
- trait WriteParticipantPruningService extends AnyRef
An interface to prune participant ledger updates to manage participant ledger space and enable GDPR-style right-to-be-forgotten support.
- trait WritePartyService extends AnyRef
An interface for on-boarding parties via a participant.
- trait WriteService extends WritePackagesService with WritePartyService with WriteConfigService with WriteParticipantPruningService with ReportsHealth
An interface to change a ledger via a participant.
An interface to change a ledger via a participant. Please note that this interface is unstable and may significantly change.
The methods in this interface are all methods that are supported *uniformly* across all ledger participant implementations. Methods for uploading packages, on-boarding parties, and changing ledger-wide configuration are specific to a ledger and therefore to a participant implementation. Moreover, these methods usually require admin-level privileges, whose granting is also specific to a ledger.
If a ledger is run for testing only, there is the option for quite freely allowing the on-boarding of parties and uploading of packages. There are plans to make this functionality uniformly available: see the roadmap for progress information https://github.com/digital-asset/daml/issues/121.
The following methods are currently available for changing the state of a Daml ledger: - submitting a transaction using WriteService!.submitTransaction - allocating a new party using WritePartyService!.allocateParty - uploading a new package using WritePackagesService!.uploadPackages - pruning a participant ledger using WriteParticipantPruningService!.prune
Value Members
- object CompletionInfo extends Serializable
- object PruningResult extends Serializable
- object SubmissionResult extends Serializable
- object SubmitterInfo extends Serializable
- object Update extends Serializable