Skip to main content

Money Partition Transaction Types

  • SystemID: 1
  • UnitID length: 32 bytes unit part + 1 byte type part
  • Valid type parts in UnitID and the corresponding unit types:
    • h'00' - bill
    • h'0f' - fee credit record
  • Hash algorithm: SHA-256

Transfer Bill​

This transaction transfers a bill to a new owner. The value of the transferred bill is unchanged.

TransactionOrder.Payload.Type = "trans"
TransactionOrder.Payload.Attributes contains:

/transAttributes/ [
    /TargetOwner/ h'5376A8014F01411DBB429D60228CACDEA90D4B5F1C0B022D7F03D9CB9E5042BE3F74B7A8C23A8769AC01',
    /TargetValue/ 999999800099999996,
    /Backlink/    h'F4C65D760DA53F0F6D43E06EAD2AA6095CCF702A751286FA97EC958AFA085839'
]
  1. TargetOwner (byte string) is the new owner predicate of the bill.
  2. TargetValue (unsigned integer) must be equal to the value of the bill. The reason for including the value of the bill in the transaction order is to enable the recipient of the transaction to learn the received amount without having to look up the bill.
  3. Backlink (byte string) is the backlink to the previous transaction with the bill.

Split Bill​

This transaction splits a bill into two or more bills, creating new bills with new owner predicates (TargetUnit.TargetOwner) and values (TargetUnit.TargetValue). The value of the bill being split is reduced by the values of the new bills and is specified in the RemainingValue attribute. The sums of TargetUnit.TargetValues and RemainingValue must be equal to the value of the bill before the split.

TransactionOrder.Payload.Type = "split"
TransactionOrder.Payload.Attributes contains:

/splitAttributes/ [
    /TargetUnits/    [
        /TargetUnit/ [
            /TargetValue/ 99900000000,
            /TargetOwner/ h'5376A8014F0162C5594A5F1E83D7C5611B041999CFB9C67CFF2482AEFA72E8B636CCF79BBB1D8769AC01'
        ]
    ],
    /RemainingValue/ 999999899999999996,
    /Backlink/       h'2C8E1F55FC20A44687AB5D18D11F5E3544D2989DFFBB8250AA6EBA5EF4CEC319'
]
  1. TargetUnits (array) is an array of TargetUnit data items. Each TargetUnit is an array of two data items:
    1. TargetValue (unsigned integer) is the value of the new bill.
    2. TargetOwner (byte string) is the owner predicate of the new bill.
  2. RemainingValue (unsigned integer) is the remaining value of the bill being split.
  3. Backlink (byte string) is the backlink to the previous transaction with the bill being split.

Lock Bill​

This transaction locks the specified bill, making the bill impossible to spend before unlocking it first. The unlocking can happen manually with the Unlock Bill transaction or automatically on certain transactions, for example, Swap with Dust Collector or Reclaim Fee Credit. Locking of the bills is optional, however, it is necessary in order to prevent failures due to concurrent modifications by other transactions. The specified lock status must be non-zero value and the targeted bill must be unlocked.

TransactionOrder.Payload.Type = "lock"
TransactionOrder.Payload.Attributes contains:

/lockAttributes/ [
    /LockStatus/ 1,
    /Backlink/   h'F4C65D760DA53F0F6D43E06EAD2AA6095CCF702A751286FA97EC958AFA085839'
]
  1. LockStatus (unsigned integer) is the status of the lock, must be non-zero value.
  2. Backlink (byte string) is the backlink to the previous transaction with the bill.

Unlock Bill​

This transaction unlocks the specified bill, making the bill spendable again. The unlocking can also happen automatically on certain transactions, for example, Swap with Dust Collector or Reclaim Fee Credit. The targeted bill must be in locked status.

TransactionOrder.Payload.Type = "unlock"
TransactionOrder.Payload.Attributes contains:

/unlockAttributes/ [
    /Backlink/   h'F4C65D760DA53F0F6D43E06EAD2AA6095CCF702A751286FA97EC958AFA085839'
]
  1. Backlink (byte string) is the backlink to the previous transaction with the bill.

Transfer Bill to Dust Collector​

This transaction transfers a bill to a special owner—Dust Collector (DC). After transferring multiple bills to DC, the transferred bills can be joined into an existing bill with the Swap Bills With Dust Collector transaction. The target bill must be chosen beforehand and should not be used between the transactions. To ensure that, the target bill should be locked using a Lock Bill transaction.

Dust is not defined, any bills can be transferred to DC and joined into a larger-value bill.

TransactionOrder.Payload.Type = "transDC"
TransactionOrder.Payload.Attributes contains:

/transDCAttributes/ [
    /Value/              999999899999999996,
    /TargetUnitID/       h'',
    /TargetUnitBacklink/ h'',
    /Backlink/           h'2C8E1F55FC20A44687AB5D18D11F5E3544D2989DFFBB8250AA6EBA5EF4CEC319'
]
  1. Value (unsigned integer) is the value of the bill transferred to DC with this transaction.
  2. TargetUnitID (byte string) is the UnitID of the target bill for the Swap Bills With Dust Collector transaction.
  3. TargetUnitBacklink (byte string) is the Backlink of the target bill for the Swap Bills With Dust Collector transaction.
  4. Backlink (byte string) is the backlink to the previous transaction with the bill.

Swap Bills With Dust Collector​

This transaction joins the bills previously transferred to DC into a target bill. It also unlocks the target bill, if it was previously locked with Lock Bill transaction.

TransactionOrder.Payload.Type = "swapDC"
TransactionOrder.Payload.Attributes contains:

/swapDCAttributes/ [
    /OwnerPredicate/   h'',
    /DcTransfers/      [/omitted/],
    /DcTransferProofs/ [/omitted/],
    /TargetValue/      3
]
  1. OwnerPredicate (byte string) is the new owner predicate of the target bill.
  2. DcTransfers (array) is an array of Transfer Bill to Dust Collector transaction records ordered in strictly increasing order of bill identifiers.
  3. DcTransferProofs (array) is an array of Transfer Bill to Dust Collector transaction proofs. The order of this array must match the order of DcTransfers array, so that a transaction and its corresponding proof have the same index.
  4. TargetValue (unsigned integer) is the value added to the target bill and must be equal to the sum of the values of the bills transferred to DC for this swap.

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.Payload.Type = "lockFC"
TransactionOrder.Payload.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Payload.Attributes contains:

/lockFCAttributes/ [
    /LockStatus/ 1,
    /Backlink/   h'52F43127F58992B6FCFA27A64C980E70D26C2CDE0281AC93435D10EB8034B695'
]
  1. LockStatus (unsigned integer) is the new lock status. Must be non-zero value.
  2. Backlink (byte string) is the last hash of Lock Fee Credit, Unlock Fee Credit, Add Fee Credit or Close Fee Credit transaction with the 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.Payload.Type = "unlockFC"
TransactionOrder.Payload.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Payload.Attributes contains:

/lockFCAttributes/ [
    /Backlink/   h'52F43127F58992B6FCFA27A64C980E70D26C2CDE0281AC93435D10EB8034B695'
]
  1. Backlink (byte string) is the last hash of Lock Fee Credit, Unlock Fee Credit, Add Fee Credit or Close Fee Credit transaction with the fee credit record.

Transfer to Fee Credit​

This transaction reserves money on the Money Partition to be paid as fees on the target partition. The Money Partition can also be the target partition. A bill can be transferred to fee credit partially.

To bootstrap a fee credit record on the Money Partition, the fee for this transaction is handled outside the fee credit system. That is, the fee for this transaction is taken directly from the transferred Amount and the amount available for the fee credit record in the target partition is reduced accordingly. ClientMetadata.MaxTransactionFee still applies.

Note that an Add Fee Credit transaction must be executed on the target partition after each Transfer to Fee Credit transaction, to notify the target partition of the new credit.

TransactionOrder.FeeProof = null
TransactionOrder.Payload.Type = "transFC"
TransactionOrder.Payload.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Payload.Attributes contains:

/transFCAttributes/ [
    /Amount/               100000000,
    /TargetSystemID/       2,
    /TargetUnitID/         h'A0227AC5202427DB551B8ABE08645378347A3C5F70E0E5734F147AD45CBC1BA52F',
    /EarliestAdditionTime/ 13,
    /LatestAdditionTime/   23,
    /TargetUnitBacklink/   null,
    /Backlink/             h'52F43127F58992B6FCFA27A64C980E70D26C2CDE0281AC93435D10EB8034B695'
]
  1. Amount (unsigned integer) is the amount of money to reserve for paying fees in the target partition. A bill can be transferred to fee credits either fully or partially.
  2. TargetSystemID (unsigned integer) is the system identifier of the target partition where the Amount can be spent on fees.
  3. TargetUnitID (byte string) is the target fee credit record identifier (FeeCreditRecordID of the corresponding Add Fee Credit transaction).
  4. EarliestAdditionTime (unsigned integer) is the earliest round when the corresponding Add Fee Credit transaction can be executed in the target partition (usually current round number).
  5. LatestAdditionTime (unsigned integer) is the latest round when the corresponding Add Fee Credit transaction can be executed in the target partition (usually current round number + some timeout).
  6. TargetUnitBacklink (byte string) is the hash of the last fee credit transaction (Add Fee Credit, Close Fee Credit, Lock Fee Credit, Unlock Fee Credit) executed for the TargetUnitID in the target partition, or null if it does not exist yet.
  7. Backlink (byte string) is the backlink to the previous transaction with the bill.

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.Payload.Type = "addFC"
TransactionOrder.Payload.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Payload.Attributes contains:

/addFCAttributes/ [
    /TargetOwner/            h'5376A8014F01B327E2D37F0BFB6BABF6ACC758A101C6D8EB03991ABE7F137C62B253C5A5CFA08769AC01',
    /FeeCreditTransfer/      [/omitted/],
    /FeeCreditTransferProof/ [/omitted/]
]
  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. FeeCreditTransfer (array) is a record of the Transfer to Fee Credit transaction. Necessary for the target partition to verify the amount reserved as fee credit in the Money Partition.
  3. FeeCreditTransferProof (array) is the proof of execution of the transaction provided in FeeCreditTransfer attribute. Necessary for the target partition to verify the amount reserved as fee credit in the Money Partition.

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 TargetUnitBacklink 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 backlink.

TransactionOrder.FeeProof = null
TransactionOrder.Payload.Type = "closeFC"
TransactionOrder.Payload.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Payload.Attributes contains:

/closeFCAttributes/ [
    /Amount/             100000000,
    /TargetUnitID/       h'A0227AC5202427DB551B8ABE08645378347A3C5F70E0E5734F147AD45CBC1BA500',
    /TargetUnitBacklink/ h''
]
  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. TargetUnitBacklink (byte string) is the backlink to the previous transaction with the bill in the Money Partition that will receive the reclaimed fee credit amount.

Reclaim Fee Credit​

This transaction reclaims the fee credit, previously closed with a Close Fee Credit transaction in a target partition, to an existing bill in the Money Partition. It also unlocks the target bill, if it was previously locked with Lock Bill transaction.

TransactionOrder.FeeProof = null
TransactionOrder.Payload.Type = "reclFC"
TransactionOrder.Payload.ClientMetadata.FeeCreditRecordID = null
TransactionOrder.Payload.Attributes contains:

/reclFCAttributes/ [
    /CloseFeeCredit/      [/TransactionRecord/],
    /CloseFeeCreditProof/ [/TransactionProof/],
    /Backlink/            h''
]
  1. CloseFeeCredit (array) is a record of the Close Fee Credit transaction. Necessary for the Money Partition to verify the amount closed as fee credit in the target partition.
  2. CloseFeeCreditProof (array) is the proof of execution of the transaction provided in CloseFeeCredit attribute. Necessary for the Money Partition to verify the amount closed as fee credit in the target partition.
  3. Backlink (byte string) is the backlink to the previous transaction with the bill receiving the reclaimed fee credit.