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_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_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.