TODO(#16601) Make this method private once PerformUnlessClosing doesn't need it any more

Adds a new synchronizer to the sync service's configuration.

NOTE: Does not automatically connect the sync service to the new synchronizer.

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.Update.PartyAddedToParticipant message. See the comments on com.digitalasset.canton.ledger.participant.state.Update for further details.

Blocks until all earlier tasks have completed and then prevents further tasks from being run.

Computes the highest ranked synchronizer from the given admissible synchronizers without performing topology checks.

This method is used internally in command processing to pre-select a synchronizer for determining the package preference set used in command interpretation.

For the definitive synchronizer selection to be used for routing of a submitted transaction, use selectRoutingSynchronizer.

Connect the sync service to the given synchronizer. This method makes sure there can only be one connection in progress at a time.

Reports the current health of the object. This should always return immediately.

Constructs and fetches the current synchronizer state, to be used throughout command execution

Get the offsets of the incomplete assigned/unassigned events for a set of stakeholders.

Check whether we're closing. Susceptible to race conditions; unless you're using this as a flag to the retry lib or you really know what you're doing, prefer performUnlessClosing and friends.

Set this to true to get detailed information about all futures that did not complete during shutdown.

Lookup a time tracker for the given synchronizerId. A time tracker will only be returned if the synchronizer is registered and connected.

How often to poll to check that all tasks have completed.

Migrates contracts from a source synchronizer to target synchronizer by re-associating them in the participant's persistent store. Prune some of the synchronizer stores after the migration.

The migration only starts when certain preconditions are fulfilled:

• the participant is disconnected from the source and target synchronizer
• there are neither in-flight submissions nor dirty requests

You can force the migration in case of in-flight transactions but it may lead to a ledger fork. Consider:

• Transaction involving participants P1 and P2 that create a contract c
• P1 migrates (D1 -> D2) when processing is done, P2 when it is in-flight
• Final state:
  • P1 has the contract on D2 (it was created and migrated)
  • P2 does have the contract because it will not process the mediator verdict

Instead of forcing a migration when there are in-flight transactions reconnect all participants to the source synchronizer, halt activity and let the in-flight transactions complete or time out.

Using the force flag should be a last resort, that is for disaster recovery when the source synchronizer is unrecoverable.

Use this method to create a PromiseUnlessShutdown that will automatically be cancelled when the close context is closed. This allows proper clean up of stray promises when the node is transitioning to a passive state.

Note: you should *not* invoke success on the returned promise but rather use trySuccess. The reason is that the call to success may fail in case of shutdown.

Modifies the settings of the synchronizer connection

NOTE: This does not automatically reconnect to the synchronizer.

Blocks until all earlier tasks have completed and then prevents further tasks from being run.

Computes a SynchronizerId -> PartyId -> PackageId relation that describes:

• for each synchronizer that hosts all the provided submitters that can submit. The provided submitters can be empty (for externally signed transactions), in which case synchronizers are not restricted by parties with submission rights on the local participant
• which package-ids can be accepted (i.e. they are vetting-valid) in a transaction by each of the informees provided
• if the prescribed synchronizer is provided, only that one is considered

Performs the task given by f unless a shutdown has been initiated. The shutdown will only begin after f completes, but other tasks may execute concurrently with f, if started using this function, or one of the other variants (performUnlessClosingF and performUnlessClosingEitherT). The tasks are assumed to take less than closingTimeout to complete.

DO NOT CALL this.close as part of f, because it will result in a deadlock. DO NOT PUT retries, especially indefinite ones, inside f.

Performs the EitherT[Future] given by etf unless a shutdown has been initiated, in which case the provided error is returned instead. Both etf and the error are lazy; etf is only evaluated if there is no shutdown, the error only if we're shutting down. The shutdown will only begin after etf completes, but other tasks may execute concurrently with etf, if started using this function, or one of the other variants (performUnlessClosing and performUnlessClosingF). The tasks are assumed to take less than closingTimeout to complete.

DO NOT CALL this.close as part of etf, because it will result in a deadlock. DO NOT PUT retries, especially indefinite ones, inside f.

Use this method if closing/shutdown of the object should wait for asynchronous computation to finish too.

Performs the Future given by f unless a shutdown has been initiated. The future is lazy and not evaluated during shutdown. The shutdown will only begin after f completes, but other tasks may execute concurrently with f, if started using this function, or one of the other variants (performUnlessClosing and performUnlessClosingEitherT). The tasks are assumed to take less than closingTimeout to complete.

DO NOT CALL this.close as part of f, because it will result in a deadlock. DO NOT PUT retries, especially indefinite ones, inside f.

Use this method if closing/shutdown of the object should wait for asynchronous computation to finish too.

Return the protocol version for a synchronizer ID if the node is connected to it.

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.

Reconnect configured synchronizers

TODO(#16601) Make this method private once PerformUnlessClosing doesn't need it any more

Schedules the given task to be run upon closing.

Register a task to run when closing is initiated, or run it immediately if closing is already ongoing. Unlike runOnClose, this method does not guarantee that this task will have run by the time the LifeCycleManager's closeAsync method completes or AutoCloseable's close returns. This is because the task is run immediately if the component has already been closed.

Variant of runOnOrAfterClose that does not return a com.digitalasset.canton.lifecycle.LifeCycleRegistrationHandle.

Computes the best synchronizer for a submitted transaction by checking the submitted transaction against the topology of the connected synchronizers and ranking the admissible ones using the synchronizer ranking (by priority, minimum number of reassignments and synchronizer-id).

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.ReassignmentCommand.Assign command must include the unassign ID which can be observed in the accepted event marking the corresponding successful unassign command.

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 sequence of com.digitalasset.canton.ledger.participant.state.Update implementation backed by the same participant state as this com.digitalasset.canton.ledger.participant.state.SyncService. Successful transaction acceptance is communicated using a com.digitalasset.canton.ledger.participant.state.Update.TransactionAccepted message. Failed transaction acceptance is communicated when possible via a com.digitalasset.canton.ledger.participant.state.Update.CommandRejected message referencing the same submitterInfo as 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.Update.CommandRejected is generated. See the comments on com.digitalasset.canton.ledger.participant.state.Update for further details.

A note on ledger time and record time: transactions are submitted together with a ledgerTime provided as part of the transactionMeta information. The ledger time is used by the Daml Engine to resolve calls to the getTime :: Update Time function. 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 of getTime quite surprising. We've chosen the following solution to provide useful guarantees for contracts relying on getTime.

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.SyncService is responsible for deduplicating commands with the same com.digitalasset.canton.ledger.participant.state.SubmitterInfo.changeId within the com.digitalasset.canton.ledger.participant.state.SubmitterInfo.deduplicationPeriod.

Runs the computation fa unless isClosing returns true.

This method does not delay the closing while fa is running, unlike the methods in HasSynchronizeWithClosing. Accordingly, this method is useful for intermittent checks whether the result of the computation is still relevant.

Upload a DAR to the ledger.

This method must be thread-safe, not throw, and not block on IO. It is though allowed to perform significant computation.