Bundling
Description
The bundling process is used to group child chain transactions from a child chain into a transaction on the Ardor chain. Bundlers accept the fees from those child chain transactions, in the corresponding child chain coin, and pay fees in ARDR to the parent chain forgers.
Bundlers can be started from the cogwheel/bundlers menu, defining the coin to ARDR exchange rate they accept, a limit on the total fees in ARDR a bundler will pay, and an optional overpay amount representing an additional factor of the Ardor fee to pay in case of competing bundlers. This is a multiplier of what you will pay in terms of Ardor fee so if the fee is 100 ARDR and overpay is set to 0.1 you will pay 100 + 100 * 0.1 = 110 as bundling fee.
When a bundler is running, it checks the unconfirmed transactions pool every time a new transaction from the child chain being bundled arrives. If the transaction fee included by the transaction sender, in child chain coins, when converted to Ardor using the exchange rate accepted by the bundler is at least equal to the minimum Ardor fee required for this transaction, the bundler will generate a ChildBlock transaction, including in it this and all other currently unconfirmed child chain transactions satisfying this requirement. The Ardor fee the bundler will include for the ChildBlock transaction is equal to the sum of the minimum required Ardor fees for each, multiplied by the overpay amount, if any. Such overpay amount is optional and may be used by bundlers willing to pay more to have their transactions included in a block instead of those of competing bundlers.
The new ChildBlock transaction will displace from the unconfirmed pool any ChildBlock transactions of the same child chain that include only a subset of the same child transactions. When propagating through the network, ChildBlock transactions will only be accepted by peers if they either include child transactions not already included in other ChildBlock transactions the peer already has in its pool, or offer to pay a higher fee for the same transactions. This ensures the network is not flooded with ChildBlock transactions even if every node is running a bundler, and allows bundlers to compete for propagating their transactions through the network by offering to pay higher fees.
It is now possible for child transactions to be submitted with zero fees, in child chain coins. If a bundler is willing to pay the Ardor fees for those, they will be included in the blockchain in the ChildBlock created by such bundler.
To prevent the unconfirmed pool from being overfilled with such zero-fees child chain transactions, once the maxUnconfirmedTransactions limit (configured in nxt.properties, default 2000) has been exceeded, child chain transactions will be dropped unless a bundler has already submitted a ChildBlock transaction which includes them.
Bundlers advertise their accepted bundling rates to other peers, signing such rates announcements with the private key of the bundler's account. To prevent fake rates announcements, they can be filtered based on this account effective balance (default set in nxt.minBundlerBalanceFXT is 1000 ARDR).
The GetBundlerRates API can be used to retrieve known bundlers rates, again with optional filtering by minimum bundler effective balance.
Bundler Setup
Bundling like Forging requires sending the passphrase to the remote node. Therefore only run a bundler on a node under your control. To view the running bundler on a node, the wallet has to include the remote node admin password in its account settings.
The bundlers, like other similar local node tools like standby shufflers or forgers, are not persisted across node reboots. Check the Processes feature for an easy-to-use and secure tool to help you with recovering the configuration upon node restart.
Existing bundlers known to the remote node
Start a new bundler
Bundling rules
Since Ardor 2.10e it is possible to enable bundling rules. The bundling process is used to group child chain transactions from a child chain into a transaction on the Ardor chain. Bundlers accept the fees from those child chain transactions, in the corresponding child chain coin, and pay fees in ARDR to the parent chain forgers.
Bundlers can be started from the cogwheel/bundlers menu. The bundler will operate on the currently selected child chain. One or more bundling rules must be added to each bundler, and also a limit specifying the total fees in ARDR, which the bundler will pay.
The bundling rule has following properties:
Minimum Rate
The coin to ARDR exchange rate of this rule. Transactions are accepted by this rule if the fee included by the transaction sender, in child chain coins, when converted to ARDR using this rate is at least equal to the minimum Ardor fee required for this transaction.
Fee Calculator
Function used to determine the fee in ARDR, which the bundler will finally pay for each transaction, having the fee in child chain coins received from the transaction.
- MIN_FEE (default value, bundlers in Ardor v2.0 use this function): the Bundler will always pay the minimum protocol fee, no matter how much child chain coins are received from the child transaction.
- PROPORTIONAL_FEE: the Bundler pays fee in ARDR proportionally to the received child chain coins, according to the Minimum Rate. This would give an advantage to the bundler versus bundlers using the MIN_FEE function in case the transaction creators start competing for block space by specifying higher fee in child chain coins.
- Custom calculators can be developed as add-ons by implementing the Bundler.FeeCalculator interface. Their classes must be listed in the nxt.customBundlingFeeCalculators configuration property.
Overpay
An additional factor of the Ardor fee to pay for each transaction. Used to give advantage to this bundler when competing with other bundlers. This is a multiplier of what you will pay in terms of the ARDR fee (the result of the Fee Calculator function). So if the fee is 100 ARDR and overpay is set to 0.1 you will pay 100 + 100 * 0.1 = 110 as bundling fee. Custom Fee Calculators may use this value for a different purpose, or disregard it.
Filters
Zero or more additional filters are applied to the bundled transactions. The transaction must satisfy the minimum fee rate and all filters to be processed. Filters can check various properties of the transaction like the sender, the recipient the transaction type, or even the presence of other transaction(s). A parameter can be specified for every added filter. The parameter is a filter-specific arbitrary string. Default filters provided "out-of-the-box":
| Name | Description | Parameter |
|---|---|---|
| PersonalBundler | Only bundle the transactions of the bundler account | |
| PropertyBundler | Only bundle transactions sent by accounts which have the "bundling" property set on them by the bundler account | |
| AssetBundler | Bundles only transactions for asset with ID provided as parameter | Asset ID (numeric) |
| CurrencyBundler | Bundles only transactions for MS currency with ID provided as parameter | Currency ID (numeric). This is not the currency code |
| PurchaseBundler | Bundles only purchases of digital goods sold by an account provided as parameter | Account ID (numeric or RS format) |
| QuotaBundler | Bundles transaction until the quota per account and transaction type is reached. The quota is provided as parameter. | Max number of transactions per account and transaction type that will be accepted by the rule |
| TransactionTypeBundler | Bundles only transaction types provided as parameter. | Comma separated string, which contains the <type>:<subtype> pairs specifying the "type" and "subtype" identifier of the whitelisted transaction types. The "type" and "subtype" identifiers can be found in the transactionSubTypes field of the getConstants result. E.g. "7:1,7:2" bundles only ShufflingRegistration and ShufflingProcessing transactions. |
Additional filters can be developed as add-ons by implementing the Bundler.Filter interface. Their classes must be added to the nxt.availableBundlingFilters property.
Bundlers with at least one non-filtered rule advertise to other peers the minimum rate among their non-filtered rules. This is the minimum rate at which the bundler will accept child transactions without checking any other property except the fee. The bundler signs such rates announcements with the private key of the bundler's account. To prevent fake rates announcements, they can be filtered based on this account effective balance (default set in nxt.minBundlerBalanceFXT is 1000 ARDR). Bundlers that have at least one filter added to all of their rules are considered private and their rates are not announced.
When running a subsidizing bundler, it is more efficient to add a not-filtered rule with some acceptable rate at the last position in the list, so that the bundler bundles both zero-fee and regular (public) transactions. This will increase the total amount of ARDR in the ChildBlock transaction and will give it priority over ChildBlock transactions created by other bundlers. The transactions are prioritized first by the index of the rule accepting them, and then by the fee in child chain coins they pay. So a subsidizing bundler will include the subsidized transactions before the public transactions even if it receives 0 fee from them.
The GetBundlerRates API can be used to retrieve known bundlers rates, again with optional filtering by minimum bundler effective balance.
Bundler Setup 2.1.0e
Bundling like Forging requires sending the passphrase to the remote node. Therefore only run a bundler on a node under your control. To view the running bundler on a node, the wallet has to include the remote node admin password in its account settings.
Existing bundlers known to the remote node for the currently selected child chain (switch to ARDR chain to see the bundlers for all chains).
Start a new bundler
Initially the bundler is started with only one rule. More rules can be added with the Add Rule button:
