Fee Credit Transaction Types

Add Fee Credit

This transaction creates or updates a fee credit record on the target partition (the partition this transaction is executed on), by presenting a proof of fee credit reserved in the Money Partition with the Transfer to Fee Credit transaction. As a result, execution of other fee-paying transactions becomes possible.

The fee for this transaction will also be paid from the fee credit record being created/updated.

TransactionOrder.FeeProof = null
TransactionOrder.Type = 16
TransactionOrder.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Attributes contains:

/AddFeeCreditAttributes/ [
    /TargetOwner/               h'5376A8014F01B327E2D37F0BFB6BABF6ACC758A101C6D8EB03991ABE7F137C62B253C5A5CFA08769AC01',
    /TransferFeeCreditProof/   /TransactionRecordProof/,
]

1. TargetOwner (byte string, optional) is the owner predicate for the created fee credit record. It needs to be satisfied by the TransactionOrder.FeeProof data item of the transactions using the record to pay fees.
2. TransferFeeCreditProof (array) is a pair of Transfer To Fee Credit transaction proof and record, that is, the response from state_getTransactionProof

Close Fee Credit

This transaction closes a fee credit record and makes it possible to reclaim the money with the Reclaim Fee Credit transaction on the Money Partition.

Note that fee credit records cannot be closed partially.

This transaction must be followed by a Reclaim Fee Credit transaction to avoid losing the closed fee credit. The TargetUnitCounter attribute fixes the current state of the bill used to reclaim the closed fee credit, and any other transaction with the bill would invalidate that counter.

TransactionOrder.FeeProof = null
TransactionOrder.Type = 17
TransactionOrder.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Attributes contains:

/CloseFeeCreditAttributes/ [
    /Amount/            100000000,
    /TargetUnitID/      h'A0227AC5202427DB551B8ABE08645378347A3C5F70E0E5734F147AD45CBC1BA500',
    /TargetUnitCounter/ 123
    /Counter/           1
]

1. Amount (unsigned integer) is the current balance of the fee credit record.
2. TargetUnitID (byte string) is the UnitID of the existing bill in the Money Partition that will receive the reclaimed fee credit amount.
3. TargetUnitCounter (unsigned integer) is the current counter value of the target bill where to reclaim fee credits in the Money Partition.
4. Counter (unsigned integer) is the transaction counter of this fee credit record.

Lock Fee Credit

Adding and reclaiming fee credits are multistep protocols, and it’s advisable to lock the target unit to prevent failures due to concurrent modifications by other transactions.

More specifically, for adding fee credits:

• If the target fee credit record exists, it should be locked using a Lock Fee Credit transaction in the target partition.
• The amount to be added to fee credits should be paid using a Transfer to Fee Credit transaction in the Money Partition. To prevent replay attacks, the Transfer to Fee Credit transaction must identify the target record and its current state.
• The transferred value is added to the target record using an Add Fee Credit transaction in the target partition. As this transaction completes the fee transfer process, it also unlocks the target record.

And for reclaiming fee credits:

• The target bill should be locked using a Lock Bill transaction in the Money Partition.
• The fee credit should be closed using a Close Fee Credit transaction in the target partition. To prevent replay attacks, the Close Fee Credit transaction must identify the target bill and its current state.
• The reclaimed value is added to the target bill using a Reclaim Fee Credit transaction in the Money Partition. As this transaction completes the fee transfer process, it also unlocks the target bill.

TransactionOrder.FeeProof = null
TransactionOrder.Type = 18
TransactionOrder.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Attributes contains:

/LockFeeCreditAttributes/ [
    /LockStatus/ 1,
    /Counter/    123
]

1. LockStatus (unsigned integer) is the new lock status. Must be non-zero value.
2. Counter (unsigned integer) is the current counter value of this bill.

Unlock Fee Credit

This transaction unlocks the specified fee credit record. Note that it's not required to manually unlock the unit as the fee credit record is automatically unlocked on Add Fee Credit transaction.

TransactionOrder.FeeProof = null
TransactionOrder.Type = 19
TransactionOrder.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Attributes contains:

/UnlockFeeCreditAttributes/ [
    /Counter/   123
]

1. Counter (unsigned integer) is the current counter value of this bill.