Packages

package protocol

Provides shorthands for general purpose types.

Most notably, it provides a facade for Daml-LF transactions and nodes. By default, code should access Daml-LF transaction and nodes types through this facade.

Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. protocol
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Package Members

  1. package messages

    This package contains data structures used in the transaction protocol.

    This package contains data structures used in the transaction protocol. However, generic data structures, e.g. com.digitalasset.canton.data.MerkleTree etc. are kept in com.digitalasset.canton.data package.

  2. package v0
  3. package v1
  4. package v2
  5. package v3

Type Members

  1. final case class AgreementText(v: String) extends AnyVal with Product with Serializable
  2. sealed trait CantonContractIdVersion extends Serializable with Product
  3. sealed trait ConfirmationPolicy extends Product with Serializable with PrettyPrinting
  4. final case class ContractMetadata extends HasVersionedWrapper[ContractMetadata] with PrettyPrinting with Product with Serializable

    Metadata for a contract.

    Metadata for a contract.

    Exceptions thrown

    ContractMetadata.InvalidContractMetadata if some maintainers are not signatories or some signatories are not stakeholders.

  5. final case class ContractSalt(unwrap: Salt) extends AnyVal with Product with Serializable

    A blinded cryptographic hash of the information that ensures uniqueness of Unicums in Canton.

    A blinded cryptographic hash of the information that ensures uniqueness of Unicums in Canton. The hash can be used to unblind the Unicum's cryptographic commitment to the contract data.

    See also

    UnicumGenerator for the construction details

  6. final case class CreatedContract extends PrettyPrinting with Product with Serializable

  7. final case class CreatedContractInView(contract: SerializableContract, consumedInView: Boolean, rolledBack: Boolean) extends Product with Serializable

    consumedInView

    Whether the contract is consumed in the view. com.digitalasset.canton.protocol.WellFormedTransaction checks that a created contract can only be used in the same or deeper rollback scopes as the create, so if rolledBack is true then consumedInView is false.

    rolledBack

    Whether the contract creation has a different rollback scope than the view.

  8. sealed trait DomainParametersLookup[+P] extends AnyRef

    This class allows to query domain parameters, regardless of whether they are static or dynamic.

    This class allows to query domain parameters, regardless of whether they are static or dynamic. The returned value can be a single parameter (see reconciliation interval example below) or a set of values.

    Type parameter P is the type of the returned value.

  9. final case class DriverContractMetadata(salt: Salt) extends HasVersionedWrapper[DriverContractMetadata] with PrettyPrinting with Product with Serializable
  10. final case class DynamicDomainParameters(participantResponseTimeout: NonNegativeFiniteDuration, mediatorReactionTimeout: NonNegativeFiniteDuration, transferExclusivityTimeout: NonNegativeFiniteDuration, topologyChangeDelay: NonNegativeFiniteDuration, ledgerTimeRecordTimeTolerance: NonNegativeFiniteDuration, mediatorDeduplicationTimeout: NonNegativeFiniteDuration, reconciliationInterval: PositiveSeconds, maxRatePerParticipant: NonNegativeInt, maxRequestSize: MaxRequestSize)(representativeProtocolVersion: RepresentativeProtocolVersion[DynamicDomainParameters.type]) extends HasProtocolVersionedWrapper[DynamicDomainParameters] with PrettyPrinting with Product with Serializable

    participantResponseTimeout

    the amount of time (w.r.t. the sequencer clock) that a participant may take to validate a command and send a response. Once the timeout has elapsed for a request, the mediator will discard all responses for that request. Choose a lower value to reduce the time to reject a command in case one of the involved participants has high load / operational problems. Choose a higher value to reduce the likelihood of commands being rejected due to timeouts.

    mediatorReactionTimeout

    the maximum amount of time (w.r.t. the sequencer clock) that the mediator may take to validate the responses for a request and broadcast the result message. The mediator reaction timeout starts when the confirmation response timeout has elapsed. If the mediator does not send a result message within that timeout, participants must rollback the transaction underlying the request. Also applies to determine the max-sequencing-time of daml 3.x topology transactions governed by mediator group. Choose a lower value to reduce the time to learn whether a command has been accepted. Choose a higher value to reduce the likelihood of commands being rejected due to timeouts.

    transferExclusivityTimeout

    this timeout affects who can initiate a transfer-in. Before the timeout, only the submitter of the transfer-out can initiate the corresponding transfer-in. From the timeout onwards, every stakeholder of the contract can initiate a transfer-in, if it has not yet happened. Moreover, if this timeout is zero, no automatic transfer-ins will occur. Choose a low value, if you want to lower the time that contracts can be inactive due to ongoing transfers. Choosing a high value currently has no practical benefit, but will have benefits in a future version. TODO(M41): Document those benefits

    topologyChangeDelay

    determines the offset applied to the topology transactions before they become active, in order to support parallel transaction processing

    ledgerTimeRecordTimeTolerance

    the maximum absolute difference between the ledger time and the record time of a command. If the absolute difference would be larger for a command, then the command must be rejected.

    mediatorDeduplicationTimeout

    the time for how long a request will be stored at the mediator for deduplication purposes. This must be at least twice the ledgerTimeRecordTimeTolerance. It is fine to choose the minimal value, unless you plan to subsequently increase ledgerTimeRecordTimeTolerance.

    reconciliationInterval

    The size of the reconciliation interval (minimum duration between two ACS commitments). Note: default to StaticDomainParameters.defaultReconciliationInterval for backward compatibility. Should be significantly longer than the period of time it takes to compute the commitment and have it sequenced of the domain. Otherwise, ACS commitments will keep being exchanged continuously on an idle domain.

    maxRatePerParticipant

    maximum number of messages sent per participant per second

    maxRequestSize

    maximum size of messages (in bytes) that the domain can receive through the public API

    Exceptions thrown

    DynamicDomainParameters$.InvalidDomainParameters if mediatorDeduplicationTimeout is less than twice of ledgerTimeRecordTimeTolerance.

  11. class DynamicDomainParametersLookup[P] extends DomainParametersLookup[P] with NamedLogging
  12. final case class DynamicDomainParametersWithValidity(parameters: DynamicDomainParameters, validFrom: CantonTimestamp, validUntil: Option[CantonTimestamp], domainId: DomainId) extends Product with Serializable

    Dynamic domain parameters and their validity interval.

    Dynamic domain parameters and their validity interval. Mostly so that we can perform additional checks.

    validFrom

    Start point of the validity interval (exclusive)

    validUntil

    End point of the validity interval (inclusive)

  13. final case class InputContract(contract: SerializableContract, consumed: Boolean) extends PrettyPrinting with Product with Serializable

    consumed

    Whether this contract is consumed in the core of the view this InputContract belongs to.

    See also

    com.digitalasset.canton.data.ViewParticipantData.coreInputs

  14. type LedgerTransactionNodeStatistics = TransactionNodeStatistics
  15. type LfActionNode = Action

    Shorthand for Daml-LF "action" nodes (all node types besides "rollback" nodes)

  16. type LfChoiceName = Name
  17. type LfCommittedTransaction = T
  18. type LfContractId = ContractId

    Shorthand for Daml-LF contract ids

  19. type LfContractInst = Versioned[ContractInstance]

    Shorthand for contract instances.

  20. type LfGlobalKey = GlobalKey

    Shorthand for global contract keys (with template_id).

  21. type LfGlobalKeyWithMaintainers = GlobalKeyWithMaintainers
  22. type LfHash = Hash
  23. type LfLeafOnlyActionNode = LeafOnlyAction

    Shorthand for leaf only action nodes.

  24. type LfNode = Node

    Shorthand for Daml-LF nodes.

    Shorthand for Daml-LF nodes. Nodes include NodeIds of their children. Children need to be looked up in the underlying transaction.

  25. type LfNodeCreate = Create

    Shorthand for create nodes.

  26. type LfNodeExercises = Exercise

    Shorthand for exercise nodes.

    Shorthand for exercise nodes. Nodes include NodeIds of their children. Children need to be looked up in the underlying transaction.

  27. type LfNodeFetch = Fetch

    Shorthand for fetch nodes.

  28. type LfNodeId = NodeId
  29. type LfNodeLookupByKey = LookupByKey

    Shorthand for lookup by key nodes.

  30. type LfNodeRollback = Rollback

    Shorthand for rollback nodes.

  31. type LfSubmittedTransaction = T
  32. type LfTemplateId = Identifier
  33. type LfTransaction = Transaction

    Shorthand for Daml-LF transaction wrapped in versioned transaction in turn wrapped in committed or submitted transaction

  34. type LfTransactionVersion = TransactionVersion
  35. type LfVersionedTransaction = VersionedTransaction
  36. final case class MalformedContractId(id: String, message: String) extends Product with Serializable
  37. final case class PackageDescription(packageId: LfPackageId, sourceDescription: String256M) extends Product with Serializable

    packageId

    the unique identifier for the package

    sourceDescription

    an informal human readable description of what the package contains

  38. trait PackageInfoService extends AnyRef
  39. trait Phase37Processor[RequestBatch] extends AnyRef
  40. final case class RequestAndRootHashMessage[RequestEnvelope](requestEnvelopes: NonEmpty[Seq[RequestEnvelope]], rootHashMessage: RootHashMessage[SerializedRootHashMessagePayload], mediator: MediatorRef, isReceipt: Boolean) extends Product with Serializable

    Request messages, along with the root hash message, the mediator ID that received the root hash message, and whether the delivery was a receipt or not (i.e.

    Request messages, along with the root hash message, the mediator ID that received the root hash message, and whether the delivery was a receipt or not (i.e. contained a message ID).

  41. final case class RequestId(ts: CantonTimestamp) extends PrettyPrinting with Product with Serializable

    A confirmation request is identified by the sequencer timestamp.

  42. type RequestProcessor[VT <: ViewType] = Phase37Processor[RequestAndRootHashMessage[OpenEnvelope[EncryptedViewMessage[VT]]]]
  43. final case class ResolvedKey(key: LfGlobalKey, resolution: SerializableKeyResolution) extends Product with Serializable
  44. final case class RollbackContext extends PrettyPrinting with Ordered[RollbackContext] with Product with Serializable

    RollbackContext tracks the location of lf transaction nodes or canton participant views within a hierarchy of LfNodeRollback suitable for maintaining the local position within the hierarchy of rollback nodes when iterating over a transaction.

  45. case class RootHash(hash: Hash) extends PrettyPrinting with HasCryptographicEvidence with Product with Serializable

    The root hash of a Merkle tree used as an identifier for requests.

    The root hash of a Merkle tree used as an identifier for requests.

    Extends com.digitalasset.canton.serialization.HasCryptographicEvidence so that RootHash's serialization can be used to compute the hash of an inner Merkle node from its children using RootHash.getCryptographicEvidence. Serialization to Protobuf fields can be done with RootHash.toProtoPrimitive

    Here is how we use it: (1) Every participant gets a “partially blinded” Merkle tree, defining the locations of the views they are privy to. (2) That Merkle tree has a root. That root has a hash. That’s the root hash. (3) The mediator receives a fully blinded Merkle tree, with the same hash. (4) The submitting participant will send for each receiving participant an additional “root hash message” in the same batch. That message will contain the same hash, with recipients (participant, mediator). (5) The mediator will check that all participants mentioned in the tree received a root hash message and that all hashes are equal. (6) Once the mediator sends out the verdict, the verdict will include the tree structure and thus the root hash. Hence, the participant will now have certainty about the mediator having checked all root hash messages and having observed the same tree structure.

    Annotations
    @SuppressWarnings()
  46. case class SerializableContract(contractId: LfContractId, rawContractInstance: SerializableRawContractInstance, metadata: ContractMetadata, ledgerCreateTime: CantonTimestamp, contractSalt: Option[Salt]) extends HasVersionedWrapper[SerializableContract] with PrettyPrinting with Product with Serializable

    Represents a serializable contract.

    Represents a serializable contract.

    contractId

    The ID of the contract.

    rawContractInstance

    The raw instance of the contract.

    metadata

    The metadata with stakeholders and signatories; can be computed from contract instance

    ledgerCreateTime

    The ledger time of the transaction creating the contract

    Annotations
    @SuppressWarnings()
  47. final case class SerializableContractWithWitnesses(contract: SerializableContract, witnesses: Set[PartyId]) extends Product with Serializable

    Serializable contract with witnesses for contract add/import used in admin repairs.

    Serializable contract with witnesses for contract add/import used in admin repairs.

    contract

    serializable contract

    witnesses

    optional witnesses that observe the creation of the contract

  48. final case class SerializableDeduplicationPeriod(deduplicationPeriod: DeduplicationPeriod) extends Product with Serializable
  49. final case class SerializableRawContractInstance extends MemoizedEvidenceWithFailure[EncodeError] with Product with Serializable

    Represents a serializable contract instance and memoizes the serialization.

  50. final case class SourceDomainId(id: DomainId) extends TransferDomainId with Product with Serializable
  51. final case class StaticDomainParameters(reconciliationInterval: PositiveSeconds, maxRatePerParticipant: NonNegativeInt, maxRequestSize: MaxRequestSize, uniqueContractKeys: Boolean, requiredSigningKeySchemes: NonEmpty[Set[SigningKeyScheme]], requiredEncryptionKeySchemes: NonEmpty[Set[EncryptionKeyScheme]], requiredSymmetricKeySchemes: NonEmpty[Set[SymmetricKeyScheme]], requiredHashAlgorithms: NonEmpty[Set[HashAlgorithm]], requiredCryptoKeyFormats: NonEmpty[Set[CryptoKeyFormat]], protocolVersion: ProtocolVersion)(representativeProtocolVersion: RepresentativeProtocolVersion[StaticDomainParameters.type]) extends HasProtocolVersionedWrapper[StaticDomainParameters] with Product with Serializable
    Annotations
    @nowarn()
  52. class StaticDomainParametersLookup[P] extends DomainParametersLookup[P]
  53. final case class StoredParties(parties: SortedSet[LfPartyId]) extends HasVersionedWrapper[StoredParties] with Product with Serializable
  54. final case class TargetDomainId(id: DomainId) extends TransferDomainId with Product with Serializable
  55. final case class TransactionId(hash: Hash) extends HasCryptographicEvidence with Product with Serializable

    A hash-based transaction id.

  56. final case class TransactionMetadata(ledgerTime: CantonTimestamp, submissionTime: CantonTimestamp, seeds: Map[LfNodeId, LfHash]) extends Product with Serializable

    Collects the metadata of a LF transaction to the extent that is needed in Canton

    Collects the metadata of a LF transaction to the extent that is needed in Canton

    ledgerTime

    The ledger time of the transaction

    submissionTime

    The submission time of the transaction

    seeds

    The node seeds by node ID

  57. sealed trait TransferDomainId extends PrettyPrinting with Product with Serializable

    This trait can be used when distinction between source and target domain is important.

  58. final case class TransferId(sourceDomain: SourceDomainId, transferOutTimestamp: CantonTimestamp) extends PrettyPrinting with Product with Serializable

    A transfer is identified by the source domain and the sequencer timestamp on the transfer-out request.

  59. final case class Unicum(unwrap: Hash) extends AnyVal with Product with Serializable

    A hash-based identifier for contracts.

    A hash-based identifier for contracts. Must be paired with a discriminator to obtain a complete contract ID.

  60. class UnicumGenerator extends AnyRef

    Generates ContractSalts and Unicums for contract IDs such that the Unicum is a cryptographic commitment to the following:

    Generates ContractSalts and Unicums for contract IDs such that the Unicum is a cryptographic commitment to the following:

    The commitment is implemented as a blinded hash with the view action salt as the blinding factor.

    The above data is split into two groups:

    The Unicum is then the cryptographic hash of the ContractSalt and the second group.

    The ContractSalt contains all the information that ensures uniqueness of contract IDs in Canton. The second group contains the information that is relevant for using the contract in transactions. The commitment to the information in the second group can be opened by revealing the ContractSalt. Since the ContractSalt is a blinded hash, such an opening does not reveal information about the data in the first group.

    Properties

    • If a transaction is added to the virtual domain ledger for a given domain, then the [[Unicum]] is globally unique unless a hash collision occurs.
      Contracts with the same Unicum must run over the same domain, have the same transaction UUID, and are handled by the same mediator. The definition of the virtual domain ledger ensures that transaction UUIDs are unique within the com.daml.api.util.LedgerEffectiveTimeTolerance and within the mediator handling the request, and that the sequencing time deviates from the ledger time by at most this tolerance. So two contracts with the same Unicum must be generated by the same transaction. However, the com.digitalasset.canton.data.ViewPosition and the create index uniquely identify the node in the transaction that creates the contract.

    We include both the com.digitalasset.canton.topology.DomainId and the com.digitalasset.canton.topology.MediatorId in the ContractSalt because we cannot exclude that mediators on different domains happen to have the same identifier and there may be mupltiple mediators on a domain.

    • If the submitter is honest and chooses a random transaction seed, the [[Unicum]] does not leak information about template arguments.
      The transaction seed's randomness propagates to the action seed through the seed derivation scheme. Since the honest submitter does not leak the transaction seed and shows the action seed only to the witnesses of the view, the ContractSalt looks random to non-witnesses of the view. Accordingly, the ContractSalt blinds the template arguments.
    • The [[Unicum]] authenticates the contract details (ledger time and template arguments) if the hash function is preimage resistant.
      By checking the hash of the ContractSalt and the contract details against the Unicum, everyone can verify that they fit together. As the hash function is preimage resistant, it is therefore computationally infeasible for a participant to find a different ContractSalt such that different contract details lead to the same hash.
    • Participants learning about the contract only through divulgence or disclosure do not learn in which transaction the contract was created unless the submitter or witnesses of the creation leak this information.
      By the honesty assumption, the action seed is a random value to those participants. Accordingly, since the ContractSalt contains all the information that ties the contract to a particular transaction, the participants cannot say which transaction with the same ledger time created the contract.
    • The [[Unicum]] does not leak the contract details when a contract ID is shown to a third party if the submitter and all witnesses and divulgees are honest.
      By the honesty assumption, the action seed is a random value to the third party, and so is the ContractSalt. This entropy hides the contract details to the third party.
  61. case class ViewHash(hash: Hash) extends PrettyPrinting with Product with Serializable

    A hash-based transaction view id

    A hash-based transaction view id

    Views from different requests may have the same view hash.

    Annotations
    @SuppressWarnings()
  62. final case class WellFormedTransaction[+S <: State] extends Product with Serializable

    Used to mark a transaction to be well-formed.

    Used to mark a transaction to be well-formed. That means:

    • tx is well-formed according to the Daml-LF definition, i.e., a root node is not child of another node and every non-root node has exactly one parent and is reachable from a root node. (No cycles, no sharing, no orphaned node).
    • All node Ids are non-negative.
    • The type parameter S determines whether all create nodes have suffixed IDs or none.
    • Create nodes have unique contract ids of shape com.daml.lf.value.Value.ContractId.V1. The contract id of a create node is not referenced before the node. The contract id of a rolled back create node is not referenced outside its rollback scope.
    • The discriminators of create nodes without suffixed contract ids are unique among all discriminators that appear in the transaction.
    • Every action node has at least one signatory.
    • Every signatory is also a stakeholder.
    • Fetch actors are defined.
    • All created contract instances and choice arguments in the transaction can be serialized.
    • All nodes in the transaction have the optLocation field set to None.
    • metadata contains seeds exactly for those node IDs from tx that should have a seed (creates and exercises).
    • Keys of transaction nodes don't contain contract IDs.
    • The maintainers of keys are non-empty.
    • ByKey nodes have a key.
    • All parties referenced by the transaction can be converted to com.digitalasset.canton.topology.PartyId
    • The transaction has the optUsedPackages set to scala.None$
    • Every rollback node has at least one child and no rollback node appears at the root unless the transaction has been merged by Canton.
  63. final case class WithContractHash[+A](x: A, contractHash: LfHash) extends Product with Serializable
  64. final case class WithContractMetadata[+A](x: A, metadata: ContractMetadata) extends Product with Serializable
  65. final case class WithRollbackScope[T](rbScope: RollbackScope, unwrap: T) extends Product with Serializable
  66. final case class WithTransactionId[+A](x: A, transactionId: TransactionId) extends Product with Serializable

Value Members

  1. val DummyTransactionVersion: LfTransactionVersion
  2. val LedgerTransactionNodeStatistics: TransactionNodeStatistics.type
  3. val LfChoiceName: ChoiceName.type
  4. val LfCommittedTransaction: CommittedTransaction.type
  5. val LfContractId: ContractId.type
  6. val LfContractInst: VersionedContractInstance.type
  7. val LfGlobalKey: GlobalKey.type
  8. val LfGlobalKeyWithMaintainers: GlobalKeyWithMaintainers.type
  9. val LfHash: Hash.type
  10. val LfNodeCreate: Create.type
  11. val LfNodeExercises: Exercise.type
  12. val LfNodeFetch: Fetch.type
  13. val LfNodeId: NodeId.type
  14. val LfNodeLookupByKey: LookupByKey.type
  15. val LfNodeRollback: Rollback.type
  16. val LfSubmittedTransaction: SubmittedTransaction.type
  17. val LfTemplateId: TypeConName.type
  18. val LfTransaction: Transaction.type
  19. val LfTransactionVersion: TransactionVersion.type
  20. val LfVersionedTransaction: VersionedTransaction.type
  21. def maxTransactionVersion(versions: NonEmpty[Seq[LfTransactionVersion]]): LfTransactionVersion
  22. object AgreementText extends Serializable
  23. case object AuthenticatedContractIdVersion extends CantonContractIdVersion with Product with Serializable
  24. case object AuthenticatedContractIdVersionV2 extends CantonContractIdVersion with Product with Serializable
  25. object CantonContractIdVersion extends Serializable
  26. object ConfirmationPolicy extends Serializable
  27. object ContractIdSyntax
  28. object ContractMetadata extends HasVersionedMessageCompanion[ContractMetadata] with HasVersionedMessageCompanionDbHelpers[ContractMetadata] with Serializable
  29. object ContractSalt extends Serializable
  30. object CreatedContract extends Serializable
  31. object CreatedContractInView extends Serializable
  32. object DomainParameters
  33. object DomainParametersLookup
  34. object DriverContractMetadata extends HasVersionedMessageCompanion[DriverContractMetadata] with Serializable
  35. object DynamicDomainParameters extends HasProtocolVersionedCompanion[DynamicDomainParameters]
  36. object GlobalKeySerialization
  37. object InputContract extends Serializable
  38. object LfHashSyntax
  39. case object NonAuthenticatedContractIdVersion extends CantonContractIdVersion with Product with Serializable
  40. object PackageDescription extends Serializable
  41. object RefIdentifierSyntax
  42. object RequestId extends Serializable
  43. object ResolvedKey extends Serializable
  44. object RollbackContext extends Serializable
  45. object RootHash extends Serializable
  46. object SerializableContract extends HasVersionedMessageCompanion[SerializableContract] with HasVersionedMessageCompanionDbHelpers[SerializableContract] with Serializable
  47. object SerializableDeduplicationPeriod extends Serializable
  48. object SerializableRawContractInstance extends Serializable
  49. object SourceDomainId extends Serializable
  50. object StaticDomainParameters extends HasProtocolVersionedCompanion[StaticDomainParameters] with ProtocolVersionedCompanionDbHelpers[StaticDomainParameters]
  51. object StoredParties extends HasVersionedMessageCompanion[StoredParties] with HasVersionedMessageCompanionDbHelpers[StoredParties] with Serializable
  52. object TargetDomainId extends Serializable
  53. object TransactionId extends Serializable
  54. object TransactionMetadata extends Serializable
  55. object TransferDomainId extends Serializable
  56. object TransferId extends Serializable
  57. object ViewHash extends Serializable
  58. object WellFormedTransaction extends Serializable
  59. object WithContractHash extends Serializable
  60. object WithContractMetadata extends Serializable
  61. object WithTransactionId extends Serializable

Inherited from AnyRef

Inherited from Any

Ungrouped