Utility.Commercials.V0.Model.CommercialAgreement

Templates used for payment of fees for using the Utility.

Templates

template CommercialAgreement

A commercial agreement that describes the fees that the user will pay for using the Utility.

Signatory: operator, user

Field	Type	Description
operator	Party	App operator.
user	Party	App user.
feeReceiver	Party	The party that will receive the fee for using the Utility services.
lockedAmuletCids	[ContractId LockedAmulet]	Coins locked to the operator which are used to pay fees.
currentLockedAmuletAmountCc	Decimal	Current amount of locked CC held as part of the commercial agreement.
utilityFees	UtilityFees	The fee that the user will pay for using the Utility services.
dso	Party	Reference to the DSO party (Decentralized Synchronizer Operations).
baseFeeBillingState	Optional BillingState	State of the base fee billing process. This field is available starting from version 0.1.0 of this package.
credentialFeeBillingState	Optional EventBillingState	State of the credential fee billing process. This field is available starting from version 0.2.0 of this package.
accruedFeesCc	Optional Decimal	Fees accrued (but not yet paid) as part of the commercial agreement. This field is available starting from version 0.3.0 of this package.
rewardReceiver	Optional Party	The party that will receive the rewards from the Utility service fees. This field is available starting from version 0.3.0 of this package.

• Choice Archive

  Controller: operator, user

  Returns: ()

  (no fields)

• Choice CommercialAgreement\_Bill

  Trigger a payment of the agreed fee for performing a billing on behalf of the user. Deprecated, use CommercialAgreement_BillCredentialFeeMulti instead. This choice is disabled as of version 0.2.1 of this package.

  Controller: operator

  Returns: CommercialAgreement\_Bill\_Result

  Field	Type	Description
  transferContext	AppTransferContext	Context for CC transfers.
  transferPreapprovalCid	ContractId TransferPreapproval	Preapproval from a party to receive the fee. If the fee payment should be a featured transfer, ensure that the TransferPreapproval contains a featuredAppRight.
  paymentTransferContext	PaymentTransferContext	Context for preapproved CC transfers.

• Choice CommercialAgreement\_BillBaseFee

  Trigger a payment of the agreed base fee. This choice is available starting from version 0.1.0 of this package.

  Controller: operator

  Returns: CommercialAgreement\_BillBaseFee\_Result

  Field	Type	Description
  transferContext	AppTransferContext	Context for CC transfers.
  transferPreapprovalCid	ContractId TransferPreapproval	Preapproval from a party to receive the fee. If the fee payment should be a featured transfer, ensure that the TransferPreapproval contains a featuredAppRight.
  paymentTransferContext	PaymentTransferContext	Context for preapproved CC transfers.

• Choice CommercialAgreement\_BillCredentialFeeMulti

  Trigger payments of the agreed fee for performing multiple credential billings on behalf of the user. This choice is available starting from version 0.2.0 of this package.

  Controller: operator

  Returns: CommercialAgreement\_BillCredentialFeeMulti\_Result

  Field	Type	Description
  transferContext	AppTransferContext	Context for CC transfers.
  transferPreapprovalCid	ContractId TransferPreapproval	Preapproval from a party to receive the fee. If the fee payment should be a featured transfer, ensure that the TransferPreapproval contains a featuredAppRight.
  paymentTransferContext	PaymentTransferContext	Context for preapproved CC transfers.
  numberOfBillings	Int	Number of credential billings performed on behalf of the user.
  currentLedgerOffset	Int	The current ledger offset, which is stored as reference data if the payment succeeds.
  currentMigrationId	Optional Text	The migration id is used to support Hard Domain Migration for this commercial agreement. This field is available starting from version 0.3.0 of this package.

• Choice CommercialAgreement\_BillCredentialFeeMultiUnfeatured

  Trigger payments of the agreed fee for performing multiple credential billings on behalf of the user. This choice is available starting from version 0.3.0 of this package.

  Controller: operator

  Returns: CommercialAgreement\_BillCredentialFeeMultiUnfeatured\_Result

  Field	Type	Description
  transferContext	AppTransferContext	Context for CC transfers.
  transferPreapprovalCid	ContractId TransferPreapproval	Preapproval from a party to receive the fee. If the fee payment should be a featured transfer, ensure that the TransferPreapproval contains a featuredAppRight.
  numberOfBillings	Int	Number of credential billings performed on behalf of the user.
  currentLedgerOffset	Int	The current ledger offset, which is stored as reference data if the payment succeeds.
  payoutThresholdCc	Optional Decimal	If the accrued fees exceed this threshold, they will be paid out as part of this billing operation.
  currentMigrationId	Optional Text	The migration id is used to support Hard Domain Migration for this commercial agreement. This field is available starting from version 0.3.0 of this package.

• Choice CommercialAgreement\_FlushExpiredDeposit

  Flush the deposit of a commercial agreement where the locked deposit has expired. This is useful to recover from missing/expired locked deposits. This choice was added as of version 0.4.0 of this package.

  Controller: actor

  Returns: CommercialAgreement\_FlushExpiredDeposit\_Result

  Field	Type	Description
  actor	Party	The party performing the flush (either the user or the operator).

• Choice CommercialAgreement\_LockCoin

  Lock coins (for future fee payments) to the operator. This increases (or decreases) the deposit to reach the specified target amount.

  Controller: user

  Returns: CommercialAgreement\_LockCoin\_Result

  Field	Type	Description
  targetAmount	Decimal	Lock coins so that the deposit reaches this target amount of totally locked coin.
  coinCids	[ContractId Amulet]	Coins to lock.
  transferContext	AppTransferContext	Context for CC transfers.

• Choice CommercialAgreement\_Modify

  Modify the commercial agreement. It keeps the operator, user, dso and deposit unchanged.

  Controller: operator

  Returns: CommercialAgreement\_Modify\_Result

  Field	Type	Description
  feeReceiver	Party	The party that will receive the fee for using the Utility services.
  utilityFees	UtilityFees	The fee that the user will pay for using the Utility services.
  rewardReceiver	Optional Party	The party that will receive the rewards from the Utility service fees. This field is available starting from version 0.3.0 of this package.

• Choice CommercialAgreement\_Revoke

  Revoke the commercial agreement (and unlock the deposit).

  Controller: actor

  Returns: CommercialAgreement\_Revoke\_Result

  Field	Type	Description
  transferContext	AppTransferContext	Reference data for unlocking the deposit.
  actor	Party	The party that is performing the revocation (either the user or the operator).
  transferPreapprovalCid	Optional (ContractId TransferPreapproval)	Preapproval from a party to receive the fee. If the fee payment should be a featured transfer, ensure that the TransferPreapproval is created by a featured provider. This field is available starting from version 0.3.0 of this package.

• Choice CommercialAgreement\_SetDefaultCredentialFeeBillingState

  Set a default credential fee billing state. This is useful for older versions of (or newly created) commercial agreements, which do not yet have a billing state. This choice is available starting from version 0.2.0 of this package.

  Controller: operator

  Returns: CommercialAgreement\_SetDefaultCredentialFeeBillingState\_Result

  Field	Type	Description
  currentLedgerOffset	Int	The current ledger offset.
  currentMigrationId	Optional Text	The migration id is used to support Hard Domain Migration for this commercial agreement. This field is available starting from version 0.3.0 of this package.

Data Types

data CommercialAgreement\_BillBaseFee\_Result

Result of CommercialAgreement_BillBaseFee.

CommercialAgreement\_BillBaseFee\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id after billing the base fee.

data CommercialAgreement\_BillCredentialFeeMultiUnfeatured\_Result

Result of CommercialAgreement_BillCredentialFeeMultiUnfeatured.

CommercialAgreement\_BillCredentialFeeMultiUnfeatured\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id after billing multiple credential fees.
credentialFeeBillingState	EventBillingState	The updated credential fee billing state.

data CommercialAgreement\_BillCredentialFeeMulti\_Result

Result of CommercialAgreement_BillCredentialFeeMulti.

CommercialAgreement\_BillCredentialFeeMulti\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id after billing multiple credential fees.
credentialFeeBillingState	EventBillingState	The updated credential fee billing state.

data CommercialAgreement\_Bill\_Result

Result of CommercialAgreement_Bill.

CommercialAgreement\_Bill\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id after billing a credential fee.

data CommercialAgreement\_FlushExpiredDeposit\_Result

Result of CommercialAgreement_FlushExpiredDeposit.

CommercialAgreement\_FlushExpiredDeposit\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id after flushing the expired deposit.

data CommercialAgreement\_LockCoin\_Result

Result of CommercialAgreement_LockCoin.

CommercialAgreement\_LockCoin\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id after locking coin.

data CommercialAgreement\_Modify\_Result

Result of CommercialAgreement_Modify.

CommercialAgreement\_Modify\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The modified commercial agreement contract id.

data CommercialAgreement\_Revoke\_Result

Result of CommercialAgreement_Revoke.

CommercialAgreement\_Revoke\_Result

Field	Type	Description
unlockedDeposit	[ContractId Amulet]	The unlocked deposit.

data CommercialAgreement\_SetDefaultCredentialFeeBillingState\_Result

Result of CommercialAgreement_SetDefaultCredentialFeeBillingState.

CommercialAgreement\_SetDefaultCredentialFeeBillingState\_Result

Field	Type	Description
commercialAgreementCid	ContractId CommercialAgreement	The updated commercial agreement contract id.
credentialFeeBillingState	EventBillingState	The updated credential fee billing state.

Functions

unlockCoins

: AppTransferContext -> ContractId LockedAmulet -> Update (ContractId Amulet)

Unlock an existing deposit and return the unlocked coins.

unlockDeposit

: AppTransferContext -> ContractId LockedAmulet -> Update TransferInput

Unlock an existing deposit and return the coin as InputAmulet for a transfer.

computeBillingCycleParams

: BillingContext -> Time -> FixedFee -> BillingState -> BillingCycleParams

Compute the billing parameters for the next billing cycle.

prepareAndValidatePreapprovedTransfer

: CommercialAgreement -> AppTransferContext -> ContractId TransferPreapproval -> Update [ContractId Amulet]

Unlock the deposit and validate the preapproval.

lockRemainingCoin

: [ContractId Amulet] -> Decimal -> CommercialAgreement -> Time -> BillingContext -> Update (ContractId LockedAmulet, Decimal)

Lock the remaining coin after the transfer.

payFee

: CommercialAgreement -> AppTransferContext -> ContractId TransferPreapproval -> PaymentTransferContext -> Decimal -> Time -> BillingContext -> Update ([ContractId LockedAmulet], Decimal)

Pay a commercial agreement fee using the locked deposit.

minutesToRelTime

: Int -> RelTime

Convert a number of minutes to a RelTime.

relTimeToMicros

: RelTime -> Decimal

Convert a RelTime to a number of microseconds expressed as Decimal.

relTimeToMinutes

: RelTime -> Decimal

Convert a RelTime to minutes. The time intervals dt we use are typically an integer multiple of minutes, so we can expect this calculation to be exact.

minutesPerDay

: Decimal

Number of minutes in a day.

chargeRatePerDay

: RatePerDay -> RelTime -> Decimal

Calculate the charge for a given period based on a RatePerDay. This operation might introduce rounding errors.

verifyAmulet

: Party -> ContractId Amulet -> Update Decimal

Verify the DSO party of a given Amulet and return the amount.

verifyAmulets

: Party -> [ContractId Amulet] -> Update Decimal

Verify a list of Amulets and return the total amount.

fetchAndValidateBillingContext

: Party -> Party -> AppTransferContext -> Update BillingContext

Fetch the billing context components from the ledger and validate them.