trait WriteService extends WritePackagesService with WritePartyService with WriteConfigService with WriteParticipantPruningService with ReportsHealth
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
- Alphabetic
- By Inheritance
- WriteService
- ReportsHealth
- WriteParticipantPruningService
- WriteConfigService
- WritePartyService
- WritePackagesService
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Abstract Value Members
- abstract def allocateParty(hint: Option[Party], displayName: Option[String], submissionId: SubmissionId)(implicit traceContext: TraceContext): CompletionStage[SubmissionResult]
Adds a new party to the set managed by the ledger.
Adds a new party to the set managed by the ledger.
Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific.
In particular, a ledger may: - Disregard the given hint and choose a completely new party identifier - Construct a new unique identifier from the given hint, e.g., by appending a UUID - Use the given hint as is, and reject the call if such a party already exists
Successful party allocations will result in a com.digitalasset.canton.ledger.participant.state.v2.Update.PartyAddedToParticipant message. See the comments on com.digitalasset.canton.ledger.participant.state.v2.ReadService.stateUpdates and com.digitalasset.canton.ledger.participant.state.v2.Update for further details.
- hint
A party identifier suggestion
- displayName
A human readable name of the new party
- submissionId
Client picked submission identifier for matching the responses with the request.
- returns
an async result of a SubmissionResult
- Definition Classes
- WritePartyService
- abstract def currentHealth(): HealthStatus
Reports the current health of the object.
Reports the current health of the object. This should always return immediately.
- Definition Classes
- ReportsHealth
- abstract def prune(pruneUpToInclusive: Offset, submissionId: SubmissionId, pruneAllDivulgedContracts: Boolean): CompletionStage[PruningResult]
Prune the participant ledger specifying the offset up to which participant ledger events can be removed.
Prune the participant ledger specifying the offset up to which participant ledger events can be removed.
As this interface applies only to the local participant unlike other administrator services, returns a (completion stage of a) PruningResult rather than a SubmissionResult.
Ledgers that do not elect to support participant pruning, return NotPruned(Status.UNIMPLEMENTED). Returning an error also keeps the ledger api server from pruning its index.
Ledgers whose participants hold no participant-local state, but want the ledger api server to prune, return ParticipantPruned.
For pruning implementations to be fault tolerant, the following aspects are important: - Consider failing a prune request before embarking on destructive operations for example if certain safety conditions are not met (such as being low on resources). This helps minimize the chances of partially performed prune operations. If the system cannot prune up to the specified offset, the call should not alter the system and return NotPruned rather than prune partially. - Implement pruning either atomically (performing all operations or none), or break down pruning steps into idempotent pieces that pick up after retries or system recovery in case of a mid-pruning crash. - To the last point, be aware that pruning of the ledger api server index happens in such an idempotent follow-up step upon successful completion of each prune call. To reach eventual consistency upon failures, be sure to return ParticipantPruned even if the specified offset has already been pruned to allow ledger api server index pruning to proceed in case of an earlier failure.
- pruneUpToInclusive
The offset up to which contracts should be pruned.
- submissionId
The submission id.
- pruneAllDivulgedContracts
If set, instruct the ledger to prune all immediately and retroactively divulged contracts created before
pruneUpToInclusiveindependent of whether they were archived beforepruneUpToInclusive.- returns
The pruning result.
- Definition Classes
- WriteParticipantPruningService
- abstract def submitConfiguration(maxRecordTime: Timestamp, submissionId: SubmissionId, config: Configuration)(implicit traceContext: TraceContext): CompletionStage[SubmissionResult]
Submit a new configuration to the ledger.
Submit a new configuration to the ledger. If the configuration is accepted a com.digitalasset.canton.ledger.participant.state.v2.Update.ConfigurationChanged event will be emitted to all participants. In case of rejection a com.digitalasset.canton.ledger.participant.state.v2.Update.ConfigurationChangeRejected will be emitted.
The com.digitalasset.canton.ledger.configuration.Configuration contains the identity of the participant that is allowed to further change the configuration. The initial configuration can be submitted by any participant.
If configuration changes are not supported by the implementation then the com.digitalasset.canton.ledger.participant.state.v2.SubmissionResult.SynchronousError should be returned. *
- returns
an async result of a SubmissionResult
- Definition Classes
- WriteConfigService
- abstract def submitReassignment(submitter: Party, applicationId: daml.lf.data.Ref.ApplicationId, commandId: daml.lf.data.Ref.CommandId, submissionId: Option[SubmissionId], workflowId: Option[daml.lf.data.Ref.WorkflowId], reassignmentCommand: ReassignmentCommand)(implicit traceContext: TraceContext): CompletionStage[SubmissionResult]
Submit a reassignment command for acceptance to the ledger.
Submit a reassignment command for acceptance to the ledger.
To complete a reassignment, first a submission of an unassign command followed by an assign command is required. The com.digitalasset.canton.ledger.participant.state.v2.ReassignmentCommand.Assign command must include the unassign ID which can be observed in the accepted event marking the corresponding successful unassign command.
- submitter
The submitter of the reassignment.
- 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.
- submissionId
An identifier for the submission that allows an application to correlate completions to its submissions.
- workflowId
A submitter-provided identifier used for monitoring and to traffic-shape the work handled by Daml applications communicating over the ledger.
- reassignmentCommand
The command specifying this reassignment further.
- abstract def submitTransaction(submitterInfo: SubmitterInfo, transactionMeta: TransactionMeta, transaction: SubmittedTransaction, estimatedInterpretationCost: Long, globalKeyMapping: Map[GlobalKey, Option[ContractId]], processedDisclosedContracts: ImmArray[ProcessedDisclosedContract])(implicit traceContext: TraceContext): CompletionStage[SubmissionResult]
Submit a transaction for acceptance to the ledger.
Submit a transaction for acceptance to the ledger.
This method must be thread-safe.
The result of the transaction submission is communicated asynchronously via a com.digitalasset.canton.ledger.participant.state.v2.ReadService implementation backed by the same participant state as this com.digitalasset.canton.ledger.participant.state.v2.WriteService. Successful transaction acceptance is communicated using a com.digitalasset.canton.ledger.participant.state.v2.Update.TransactionAccepted message. Failed transaction acceptance is communicated when possible via a com.digitalasset.canton.ledger.participant.state.v2.Update.CommandRejected message referencing the same
submitterInfoas provided in the submission. There can be failure modes where a transaction submission is lost in transit, and no com.digitalasset.canton.ledger.participant.state.v2.Update.CommandRejected is generated. See the comments on com.digitalasset.canton.ledger.participant.state.v2.ReadService.stateUpdates for further details.A note on ledger time and record time: transactions are submitted together with a
ledgerTimeprovided as part of thetransactionMetainformation. The ledger time is used by the Daml Engine to resolve calls to thegetTime :: Update Timefunction. Letting the submitter freely choose the ledger time is though a problem for the other stakeholders in the contracts affected by the submitted transaction. The submitter can in principle choose to submit transactions that are effective far in the past or future relative to the wall-clock time of the other participants. This gives the submitter an unfair advantage and make the semantics ofgetTimequite surprising. We've chosen the following solution to provide useful guarantees for contracts relying ongetTime.The ledger is charged with (1) associating record-time stamps to accepted transactions and (2) to provide a guarantee on the maximal skew between the ledger effective time and the record time stamp associated to an accepted transaction. The ledger is also expected to provide guarantees on the distribution of the maximal skew between record time stamps on accepted transactions and the wall-clock time at delivery of accepted transactions to a ledger participant. Thereby providing ledger participants with a guarantee on the maximal skew between the ledger effective time of an accepted transaction and the wall-clock time at delivery to these participants.
Concretely, we typically expect the allowed skew between record time and ledger time to be in the minute range. Thereby leaving ample time for submitting and validating large transactions before they are timestamped with their record time.
The com.digitalasset.canton.ledger.participant.state.v2.WriteService is responsible for deduplicating commands with the same com.digitalasset.canton.ledger.participant.state.v2.SubmitterInfo.changeId within the com.digitalasset.canton.ledger.participant.state.v2.SubmitterInfo.deduplicationPeriod.
- submitterInfo
the information provided by the submitter for correlating this submission with its acceptance or rejection on the associated com.digitalasset.canton.ledger.participant.state.v2.ReadService.
- transactionMeta
the meta-data accessible to all consumers of the transaction. See com.digitalasset.canton.ledger.participant.state.v2.TransactionMeta for more information.
- transaction
the submitted transaction. This transaction can contain local contract-ids that need suffixing. The participant state may have to suffix those contract-ids in order to guaranteed their global uniqueness. See the Contract Id specification for more detail daml-lf/spec/contract-id.rst.
- estimatedInterpretationCost
Estimated cost of interpretation that may be used for handling submitted transactions differently.
- globalKeyMapping
Input key mapping inferred by interpretation. The map should contain all contract keys that were used during interpretation. A value of None means no contract was found with this contract key.
- processedDisclosedContracts
Explicitly disclosed contracts used during interpretation.
- abstract def uploadPackages(submissionId: SubmissionId, archives: List[Archive], sourceDescription: Option[String])(implicit traceContext: TraceContext): CompletionStage[SubmissionResult]
Upload a collection of Daml-LF packages to the ledger.
Upload a collection of Daml-LF packages to the ledger.
This method must be thread-safe, not throw, and not block on IO. It is though allowed to perform significant computation.
Successful archives upload will result in a com.digitalasset.canton.ledger.participant.state.v2.Update.PublicPackageUpload message. See the comments on com.digitalasset.canton.ledger.participant.state.v2.ReadService.stateUpdates and com.digitalasset.canton.ledger.participant.state.v2.Update for further details.
Note: we accept com.daml.daml_lf_dev.DamlLf.Archives rather than parsed packages, because we want to be able to get the byte size of each individual ArchivePayload, which is information that the read / index service need to provide. Moreover this information should be consistent with the payload that the com.daml.ledger.api.v1.package_service.GetPackageResponse contains. If we were to consume packages we'd have to re-encode them to provide the size, and the size might potentially be different from the original size, which would be quite confusing.
- submissionId
Submitter chosen submission identifier.
- archives
Daml-LF archives to be uploaded to the ledger. All archives must be valid, i.e., they must successfully decode and pass Daml engine validation.
- sourceDescription
Description provided by the backing participant describing where it got the package from, e.g., when, where, or by whom the packages were uploaded.
- returns
an async result of a com.digitalasset.canton.ledger.participant.state.v2.SubmissionResult
- Definition Classes
- WritePackagesService
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native() @HotSpotIntrinsicCandidate()
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])