trait ActiveContractStore extends ActiveContractSnapshot with ConflictDetectionStore[LfContractId, Status]
The active contract store (ACS) stores for every contract ID whether it is inexistent, ActiveContractStore.Active, ActiveContractStore.Archived, or ActiveContractStore.TransferredAway, along with the timestamp of the latest change. Every change is associated with the timestamp and request counter of the request that triggered the change. The changes are ordered first by timestamp, then by request counter, and finally by change type (activations before deactivations). Implementations must be thread-safe. Updates must be idempotent.
Creations, transfers, and archivals can be mixed arbitrarily. A contract may be transferred-in and -out several times during its lifetime. It becomes active with every transfer-in and transferred away with every transfer-out. If the ACS detects irregularities, the change method reports them.
These methods are supposed to be called by the ConflictDetector
only,
which coordinates the request journal updates and the updates to the ACS.
Updates may be written asynchronously. Every implementation determines an order over all the changes and queries to the ACS. Each individual change must be applied atomically and the result is determined with respect to this order. This order need not be consistent with the order of the calls, though. However, the following is guaranteed: If the future returned by a call completes and observing the completion happens before another call, then all changes of the former call must be ordered before all changes of the later call.
Bulk methods like ActiveContractStore.markContractsCreated and ActiveContractStore.archiveContracts generate one individual change for each contract. So their changes may be interleaved with other calls.
- See also
ActiveContractSnapshot for the ACS snapshot interface
- Alphabetic
- By Inheritance
- ActiveContractStore
- ConflictDetectionStore
- PrunableByTime
- ActiveContractSnapshot
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Abstract Value Members
- abstract def advancePruningTimestamp(phase: PruningPhase, timestamp: CantonTimestamp)(implicit traceContext: TraceContext): Future[Unit]
- Attributes
- protected[canton]
- Definition Classes
- PrunableByTime
- Annotations
- @VisibleForTesting()
- abstract def changesBetween(fromExclusive: TimeOfChange, toInclusive: TimeOfChange)(implicit traceContext: TraceContext): Future[LazyList[(TimeOfChange, ActiveContractIdsChange)]]
- Definition Classes
- ActiveContractSnapshot
- abstract def contractSnapshot(contractIds: Set[LfContractId], timestamp: CantonTimestamp)(implicit traceContext: TraceContext): Future[Map[LfContractId, CantonTimestamp]]
Returns a map to the timestamp when the contract became active for the last time before or at the given timestamp.
Returns a map to the timestamp when the contract became active for the last time before or at the given timestamp. Omits contracts that not active right after the given timestamp.
- timestamp
The timestamp at which the activeness of the contracts shall be determined. Must be before the timestamp that corresponds to the head cursor in the com.digitalasset.canton.participant.protocol.RequestJournal for the state com.digitalasset.canton.participant.protocol.RequestJournal.RequestState.Clean. If this precondition is violated, the returned snapshot may be inconsistent, i.e., it may omit some contracts that were ActiveContractStore.Active at the given time and it may include contracts that were actually ActiveContractStore.Archived or ActiveContractStore.TransferredAway.
- Definition Classes
- ActiveContractSnapshot
- abstract def deleteSince(criterion: RequestCounter)(implicit traceContext: TraceContext): Future[Unit]
Deletes all activeness changes from requests whose request counter is at least the given one.
Deletes all activeness changes from requests whose request counter is at least the given one. This method must not be called concurrently with creating, archiving, or transferring contracts.
Therefore, this method need not be linearizable w.r.t. creating, archiving, or transferring contracts. For example, if a request
rc1
creates a contractc
and another requestrc2
archives it while deleteSince is running for somerc <= rc1, rc2
, then there are no guarantees which of the effects ofrc1
andrc2
remain. For example,c
could end up being inexistent, active, or archived but never created, even if the writes forrc1
andrc2
are successful. - abstract def doPrune(beforeAndIncluding: CantonTimestamp, lastPruning: Option[CantonTimestamp])(implicit traceContext: TraceContext): Future[Int]
Deletes all entries about archived contracts whose status hasn't changed after the timestamp.
Deletes all entries about archived contracts whose status hasn't changed after the timestamp.
The caller must ensure that the given timestamp is at most the one of the clean cursor in the com.digitalasset.canton.participant.protocol.RequestJournal
- returns
the approximate number of pruned rows, used to adjust the pruning windows to reach optimal batch sizes
- Attributes
- protected[canton]
- Definition Classes
- ActiveContractStore → PrunableByTime
- implicit abstract val ec: ExecutionContext
- Attributes
- protected
- Definition Classes
- PrunableByTime
- abstract def fetchStates(contractIds: Iterable[LfContractId])(implicit traceContext: TraceContext): Future[Map[LfContractId, ContractState]]
Returns the latest com.digitalasset.canton.participant.store.ActiveContractStore.Status for the given contract IDs along with its com.digitalasset.canton.participant.util.TimeOfChange.
Returns the latest com.digitalasset.canton.participant.store.ActiveContractStore.Status for the given contract IDs along with its com.digitalasset.canton.participant.util.TimeOfChange.
This method is used by the protocol processors for conflict detection. In-flight transactions may have changesets not yet written to the ACS datastore. Since only the
ConflictDetector
tracks in-flight changesets, this method cannot be used as a source of valid data to other components.If a contract is created or transferred-in and archived or transferred-out at the same com.digitalasset.canton.participant.util.TimeOfChange, the contract is ActiveContractStore.Archived or ActiveContractStore.TransferredAway. A contract cannot be archived and transferred out at the same timestamp.
- returns
The map from contracts in
contractIds
in the store to their latest state. Nonexistent contracts are excluded from the map.
- Definition Classes
- ActiveContractStore → ConflictDetectionStore
- See also
ActiveContractSnapshot!.snapshot
- abstract def markContractsCreatedOrAdded(contracts: Seq[LfContractId], toc: TimeOfChange, isCreation: Boolean)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
- Attributes
- protected
- abstract def packageUsage(pkg: PackageId, contractStore: ContractStore)(implicit traceContext: TraceContext): Future[Option[LfContractId]]
Returns Some(contractId) if an active contract belonging to package
pkg
exists, otherwise returns None.Returns Some(contractId) if an active contract belonging to package
pkg
exists, otherwise returns None. The returned contractId may be any active contract from packagepkg
. The most recent contract state is used.- Definition Classes
- ActiveContractSnapshot
- abstract def pruningStatus(implicit traceContext: TraceContext): Future[Option[PruningStatus]]
Returns the latest timestamp at which pruning was started or completed.
Returns the latest timestamp at which pruning was started or completed. For com.digitalasset.canton.pruning.PruningPhase.Started, it is guaranteed that no pruning has been run on the store after the returned timestamp. For com.digitalasset.canton.pruning.PruningPhase.Completed, it is guaranteed that the store is pruned at least up to the returned timestamp (inclusive). That is, another pruning with the returned timestamp (or earlier) has no effect on the store. Returns scala.None$ if no pruning has ever been started on the store.
- Definition Classes
- PrunableByTime
- abstract def purgeOrArchiveContracts(contractIds: Seq[LfContractId], toc: TimeOfChange, isArchival: Boolean)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Depending on the
isArchival
, will archive (effect of a Daml transaction) or purge (repair service)Depending on the
isArchival
, will archive (effect of a Daml transaction) or purge (repair service)- Attributes
- protected
- abstract def snapshot(rc: RequestCounter)(implicit traceContext: TraceContext): Future[SortedMap[LfContractId, RequestCounter]]
Returns all contracts that were active right after the given request counter, and when the contract became active for the last time before or at the given request counter.
Returns all contracts that were active right after the given request counter, and when the contract became active for the last time before or at the given request counter.
- rc
The request counter at which the snapshot shall be taken. Must be before the request counter that corresponds to the head cursor in the com.digitalasset.canton.participant.protocol.RequestJournal for the state com.digitalasset.canton.participant.protocol.RequestJournal.RequestState.Clean. If this precondition is violated, the returned snapshot may be inconsistent, i.e., it may omit some contracts that were ActiveContractStore.Active at the given counter and it may include contracts that were actually ActiveContractStore.Archived or ActiveContractStore.TransferredAway.
- returns
A map from contracts to the latest request counter (no later than the given
rc
) when they became active again. It contains exactly those contracts that were active right after the given request counter. If a contract is created or transferred-in and archived or transferred-out at the same request counter, it does not show up in any snapshot. The map is sorted by cats.kernel.Order[
com.digitalasset.canton.protocol.LfContractId]
.
- Definition Classes
- ActiveContractSnapshot
- abstract def snapshot(timestamp: CantonTimestamp)(implicit traceContext: TraceContext): Future[SortedMap[LfContractId, CantonTimestamp]]
Returns all contracts that were active right after the given timestamp, and when the contract became active for the last time before or at the given timestamp.
Returns all contracts that were active right after the given timestamp, and when the contract became active for the last time before or at the given timestamp.
- timestamp
The timestamp at which the snapshot shall be taken. Must be before the timestamp that corresponds to the head cursor in the com.digitalasset.canton.participant.protocol.RequestJournal for the state com.digitalasset.canton.participant.protocol.RequestJournal.RequestState.Clean. If this precondition is violated, the returned snapshot may be inconsistent, i.e., it may omit some contracts that were ActiveContractStore.Active at the given time and it may include contracts that were actually ActiveContractStore.Archived or ActiveContractStore.TransferredAway.
- returns
A map from contracts to the latest timestamp (no later than the given
timestamp
) when they became active again. It contains exactly those contracts that were active right after the given timestamp. If a contract is created or transferred-in and archived or transferred-out at the same timestamp, it does not show up in any snapshot. The map is sorted by cats.kernel.Order[
com.digitalasset.canton.protocol.LfContractId]
.
- Definition Classes
- ActiveContractSnapshot
- abstract def transferInContracts(transferIns: Seq[(LfContractId, SourceDomainId, TimeOfChange)])(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Marks the given contracts as transferred in from
toc
's timestamp (inclusive) onwards.Marks the given contracts as transferred in from
toc
's timestamp (inclusive) onwards.- transferIns
The contract IDs to transfer-in, each with its source domain and time of change.
- returns
The future completes when the contract states have been updated. The following irregularities are reported:
- ActiveContractStore.SimultaneousActivation if a transfer-in from another domain or a creation has been added with the same timestamp.
- ActiveContractStore.ChangeAfterArchival if this timestamp is after the earliest archival of the contract.
- ActiveContractStore.ChangeBeforeCreation if this timestamp is before the latest creation of the contract.
- abstract def transferOutContracts(transferOuts: Seq[(LfContractId, TargetDomainId, TimeOfChange)])(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Marks the given contracts as ActiveContractStore.TransferredAway from
toc
's timestamp (inclusive) onwards.Marks the given contracts as ActiveContractStore.TransferredAway from
toc
's timestamp (inclusive) onwards.- transferOuts
The contract IDs to transfer out, each with its target domain and time of change.
- returns
The future completes when the contract state has been updated. The following irregularities are reported:
- ActiveContractStore.SimultaneousDeactivation if a transfer-out to another domain or a creation has been added with the same timestamp.
- ActiveContractStore.ChangeAfterArchival if this timestamp is after the earliest archival of the contract.
- ActiveContractStore.ChangeBeforeCreation if this timestamp is before the latest creation of the contract.
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
- def archiveContract(cid: LfContractId, toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Shorthand for
archiveContracts(Seq(cid), toc)
- def archiveContracts(contractIds: Seq[LfContractId], toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Marks the given contracts as archived from
toc
's timestamp (inclusive) onwards.Marks the given contracts as archived from
toc
's timestamp (inclusive) onwards.- contractIds
The contract IDs of the contracts to be archived
- toc
The time of change consisting of
- The request counter of the confirmation request that archives the contracts.
- The timestamp on the confirmation request that archives the contracts.
- returns
The future completes when all contract states have been updated. The following irregularities are reported for each contract:
- ActiveContractStore.DoubleContractArchival if the contract is archived a second time.
- ActiveContractStore.SimultaneousDeactivation if the contract is transferred out at the same time or has been archived by a different request at the same time.
- ActiveContractStore.ChangeAfterArchival for every change that occurs after the archival timestamp. This is reported only if no ActiveContractStore.DoubleContractArchival is reported.
- ActiveContractStore.ChangeBeforeCreation if this archival is earlier than the latest creation of the contract.
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def batchingParameters: Option[PrunableByTimeParameters]
Parameters to control prune batching
Parameters to control prune batching
If defined, then the pruning window will be computed such that it targets the ideal target batch size in order to optimize the load on the database.
This is currently used with the journal stores. Normal pruning of other stores already does batching on its own.
- Attributes
- protected
- Definition Classes
- PrunableByTime
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native() @IntrinsicCandidate()
- def domainIdFromIdx(idx: Int)(implicit ec: ExecutionContext, loggingContext: ErrorLoggingContext): Future[DomainId]
- Attributes
- protected
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def fetchState(id: LfContractId)(implicit traceContext: TraceContext): Future[Option[StateChange[Status]]]
Short-hand for fetchStates for a single identifier
Short-hand for fetchStates for a single identifier
- Definition Classes
- ConflictDetectionStore
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @IntrinsicCandidate()
- def getDomainIndices(domains: Seq[DomainId]): CheckedT[Future, AcsError, AcsWarning, Map[DomainId, IndexedDomain]]
- Attributes
- protected
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @IntrinsicCandidate()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- def kind: String
- Attributes
- protected
- Definition Classes
- ActiveContractStore → PrunableByTime
- def markContractAdded(contract: LfContractId, toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Shorthand for
markContractAdded(Seq(contract), toc)
- def markContractCreated(contract: LfContractId, toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Shorthand for
markContractsCreated(Seq(contract), toc)
- def markContractsAdded(contracts: Seq[LfContractId], toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Marks the given contracts as active from
timestamp
(inclusive) onwards.Marks the given contracts as active from
timestamp
(inclusive) onwards.Unlike creation, add can be done several times in the life of a contract. It is intended to use from the repair service.
- def markContractsCreated(contracts: Seq[LfContractId], toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Marks the given contracts as active from
timestamp
(inclusive) onwards.Marks the given contracts as active from
timestamp
(inclusive) onwards.- contracts
The contracts represented as a tuple of contract id and reassignment counter
- toc
The time of change consisting of
- The request counter of the confirmation request that created the contracts
- The timestamp of the confirmation request that created the contracts.
- returns
The future completes when all contract states have been updated. The following irregularities are reported for each contract:
- ActiveContractStore.DoubleContractCreation if the contract is created a second time.
- ActiveContractStore.SimultaneousActivation if the contract is transferred in at the same time or has been created by a different request at the same time.
- ActiveContractStore.ChangeBeforeCreation for every change that occurs before the creation timestamp. This is reported only if no ActiveContractStore.DoubleContractCreation is reported.
- ActiveContractStore.ChangeAfterArchival if this creation is later than the earliest archival of the contract.
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @IntrinsicCandidate()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @IntrinsicCandidate()
- final def prune(limit: CantonTimestamp)(implicit errorLoggingContext: ErrorLoggingContext, closeContext: CloseContext): Future[Unit]
Prune all unnecessary data relating to events before the given timestamp.
Prune all unnecessary data relating to events before the given timestamp.
The meaning of "unnecessary", and whether the limit is inclusive or exclusive both depend on the particular store. The store must implement the actual pruning logic in the doPrune method.
- Definition Classes
- PrunableByTime
- def purgeContract(cid: LfContractId, toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Shorthand for
purgeContracts(Seq(cid), toc)
- def purgeContracts(contractIds: Seq[LfContractId], toc: TimeOfChange)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
Marks the given contracts as inactive from
timestamp
(inclusive) onwards.Marks the given contracts as inactive from
timestamp
(inclusive) onwards.Unlike archival, purge can be done several times in the life of a contract. It is intended to use from the repair service.
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- def transferInContract(contractId: LfContractId, toc: TimeOfChange, sourceDomain: SourceDomainId)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
- def transferOutContract(contractId: LfContractId, toc: TimeOfChange, targetDomain: TargetDomainId)(implicit traceContext: TraceContext): CheckedT[Future, AcsError, AcsWarning, Unit]
- 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])