Phasing

From Bitswift Wiki
Revision as of 15:24, 10 January 2018 by 45.78.172.6 (talk) (Created page with "<languages/> <translate> Bitswift Phasing Phasing allows transactions with deferred execution, with or without conditions. Phasing could be considered a form of smart trans...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

<languages/> <translate>

Bitswift Phasing

Phasing allows transactions with deferred execution, with or without conditions. Phasing could be considered a form of smart transactions.

Introduction

Bitswift Phasing is a feature that allows certain phasing-safe transactions to be created with conditional deferred execution based on the result of a vote, on a list of linked transactions or on the revelation of a secret; or simply with unconditional deferred execution. Phasing-safe transactions are indicated with italics in the API Create Transaction list.

Create a Phased Transaction

To create a phased Bitswift transaction, first click on Send Bitswift at the center top of the Bitswift Client as it appears in the default Ardor client. A pop-up entry form appears:

  • At this point the recipient account ID and the amount of Bitswift to send can be entered into the Recipient and Amount fields of the form, respectively.
  • If the Send Bitswift button in the lower right of the form is clicked, a transaction is created and immediately submitted to the peer network for inclusion in the blockchain, with a fee.
  • To instead make the transaction phased, click on the advanced link in the lower left area of the form to display the phasing related fields:
  • To return to the basic Send Bitswift form, click on the Basic link in the lower left area of the form.
  • The Referenced Transaction Hash field and the Do Not Broadcast and Note to Self? controls do not relate to Phasing.
  • The Fee field contains the default minimum transaction fee. The box to the right with the gavel graphic automatically displays the fee surcharge for phasing, depending on the phasing configuration.
  • The Deadline (Hours) field displays the default 24 hour deadline for inclusion of the transaction into a block.
  • The next row contains eight graphics for selecting the phasing voting model; hovering the cursor over the graphics causes descriptive tooltips to appear. The leftmost selection, the default, is for no phasing. The seven voting models are explained below.

Voting Models

Clicking on one of the phasing graphics selects the voting model, causes the fee surcharge to be updated and causes one or more new fields or controls to appear, as described in the sections below.

All voting models have in common a field/control for Finish Height which determines when deferred execution will occur if approved, that is, if all requirements for execution will have been met in the block just prior to the finish height. The voting models are named according to the method of approval.

For four of the voting models (the Vote By ... models), the results of a vote determine whether execution will occur at the finish height. These four models have in common: the Whitelist field for restricting voting to selected accounts and for generating Whitelisted Approval Requests, and the Min Balance Type control for restricting voting to accounts with a minimum balance of Bitswift, or any other digital asset existing on the Bitswift child chain.

None

  • The phased transaction will execute unconditionally at the Finish Height.

Vote By Account

  • Enter into the Number Accounts field the number of accounts that must vote for (approve) the transaction. Each account has one vote.
  • A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, the only mechanism for voting is Manual Approval.
  • Voting can be restricted to accounts with a minimum balance of Bitswift, an asset or a digital currency using the Min Balance Type drop-down control.
  • Update the Finish Height field to change the default value.

Vote By Account Balance

  • Enter into the Amount Bitswift field the minimum total amount of Bitswift needed to approve the transaction, with each voting account contributing to the total its Bitswift balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
  • A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, the only mechanism for voting is Manual Approval.
  • Voting can be restricted to accounts with a minimum balance of Bitswift using the Min Balance Type drop-down control.
  • Update the Finish Height field to change the default value.

Vote By Asset Balance

  • Enter into the Asset Quantity field the minimum total quantity of the asset needed to approve the transaction, with each voting account contributing to the total its asset balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
  • Enter into the Asset field the asset ID. The name of the asset is instantly displayed in the shaded box to the right to confirm the ID.
  • A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, an Asset Approval Request is automatically generated.
  • Voting can be restricted to accounts with a minimum balance of the asset using the Min Balance Type drop-down control.
  • Update the Finish Height field to change the default value.

Vote By Currency Balance

  • Enter into the Currency Units field the minimum total units of the currency needed to approve the transaction, with each voting account contributing to the total its currency balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
  • Enter into the Currency field the three- to five-letter currency code. The ID of the currency is instantly displayed in the shaded box to the right to confirm the code.
  • A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, an Currency Approval Request is automatically generated.
  • Voting can be restricted to accounts with a minimum balance of the currency using the Min Balance Type drop-down control.
  • Update the Finish Height field to change the default value.

By Linked Transactions

  • Enter the full hash of a transaction that must be in the blockchain at the finish height for the phased transaction to be executed.
  • A transaction already in the blockchain before the acceptance of the phased transaction can be linked, as long as it is not more than 60 days old, or itself a phased transaction. If the transaction is associated with your account, its full hash can be obtained by clicking on its timestamp in the My Transactions screen to open the Transaction Info pop-up window, then clicking on the Transactions Detail tab. Otherwise, the full hash can be obtained using the Bitswift API if the transaction ID is known.
  • A transaction not yet in the blockchain can be linked in advance if the transaction is created but not broadcast. The full hash is then available for linking to the phased transaction. The signed transaction bytes can be broadcast later (via the Transaction Operations item of the Settings Menu, before the finish height of the phased transaction, in order to approve it.
  • It is possible to link up to ten transactions via the Bitswift API, but currently only one can be linked via this entry form.
  • Update the Finish Height field to change the default value.

By Secret

If the eigth graphic is clicked, the following appears:

  • Select a Hash Algorithm from the pull-down control.
  • Enter into the Approved By Hashed Secret field the hash of a secret phrase that must be revealed by the finish height to approve execution of the phased transaction. The hash can be computed from the secret phrase using the Calculate Hash item of the Settings Menu.
  • Update the Finish Height field to change the default value.
  • To approve the phased transaction once it is confirmed and before the finish height, use Manual Approval.

Finish Height

  • The leftmost box is the entry field for Finish Height and is initialized to 7000 blocks (approximately a week) into the future. Enter the exact block height at which the phasing poll is to finish.
  • As a convenience, an estimated finish date is displayed to the right of the Finish Height label. This date adjusts automatically whenever the Finish Height field changes.
  • As a convenience, the second shaded box just to the right of the Finish Height field is a control which displays the current block height at the time the pop-up entry form was opened. Clicking on it causes the Finish Height field to change to this value.
  • As a convenience, the third and fourth boxes contain controls labeled - (minus) and + (plus) for decreasing or increasing, respectively, the Finish Height by 500 blocks (approximately half of a day).

Whitelist

Selection of one of the four Vote By ...voting models causes the Accounts (Whitelist) field and its associated controls to appear:

  • Enter into the Accounts (Whitelist) field the account ID of an account that is eligible to vote.
  • Once the whitelist is created with the inclusion of a single account, only that account and up to nine other accounts optionally added to the whitelist are eligible to vote in the phasing poll.
  • To add another account to the whitelist, click on the + Add Account button and enter the account ID into the new field that appears.
  • To remove an account from the whitelist, click on the - (minus) control on the right.
  • Whitelisted accounts will receive a Whitelisted Approval Request, which is a mechanism for voting.

Minimum Balance Models

Selection of one of the four Vote By ... voting models causes the Min Balance Type drop-down control to appear:

  • The default selection is No min balance necessary, meaning that possessing a minimum balance is not an eligibility requirement for voting. There is no additional fee surcharge.

Clicking on the drop-down control causes a list of one or more minimum balance models (types) to appear, depending on the voting model:

  • The list shown is for the Vote By Account model and offers a choice of three minimum balance models: Min balance of Bitswift required, Min balance of asset quantity required and Min balance of currency units required.
  • If the voting model is Vote By Account Balance, Vote By Asset Balance or [Vote By Currency Balance, the minimum balance model must match the voting model and so only one choice is offered for each.
  • Selecting one of the minimum balance models causes a fee surcharge

Minimum Balance Of Bitswift

  • Enter into the Min Balance field the minimum balance of Bitswift required for an account to be eligible to vote in the phasing poll for approval of the transaction.
  • The account must possess this minimum balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.

Minimum Balance Of Asset Quantity

  • Enter into the Min Balance field the minimum balance of asset quantity required for an account to be eligible to vote in the phasing poll for approval of the transaction.
  • The account must possess this minimum balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
  • If the voting model is Vote By Account, enter into the Asset field the asset ID. The name of the asset is instantly displayed in the shaded box to the right to confirm the ID. This field is not displayed for the Vote By Asset Balance voting model, because the asset ID is already specified.

Minimum Balance Of Currency Units

  • Enter into the Min Balance field the minimum balance of currency units required for an account to be eligible to vote in the phasing poll for approval of the transaction.
  • The account must possess this minimum balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
  • If the voting model is Vote By Account, enter into the Currency field the three- to five-letter currency code. The ID of the currency is instantly displayed in the shaded box to the right to confirm the code. This field is not displayed for the [Vote By Currency Balance voting model, because the currency code is already specified.

Approve A Phased Transaction

Approval Requests are the best mechanism for approval of phased transactions, but they only apply to the four Vote By ... voting models, and in the cases of Vote By Account and Vote By Account Balance, only when a Whitelist is used. Otherwise, another mechanism must be used: Manual Approval. The By Linked Transactions voting model does not require manual approval, only the presence of the specified linked transaction(s) in the blockchain.

Approval Requests

Approval requests are invitations to vote in phasing polls, which apply to the four Vote By ... voting models. While voting is open (until the finish height of the phasing poll is reached), approval requests appear in all Bitswift Clients logged into accounts that are invited to vote in the poll, either by inclusion on a whitelist or by virtue of owning an asset or currency, depending on the voting configuration.

If a whitelist is used, then approval requests appear only on the Whitelisted Approval Requests screen, regardless of the voting model.

Absent a whitelist, Vote By Account and Vote By Account Balance voting model approval requests appear nowhere in the Bitswift Client while Vote By Asset Balance and Vote By Currency Balance voting model approval requests appear on the Asset Approval Requests and Currency Approval Requests screens, respectively.

Whitelisted Approval Requests

This screen is accessed from the Bitswift Client menu in the left pane by first clicking on Dashboard to expand the submenu, then clicking on the Approval Requests submenu item:

  • Note that the number of pending approval requests is displayed in a shaded circle to the right of the Approval Requests submenu item; this is an alert that approvals are requested.
  • (Account) in the screen title refers to the Vote By Account andVote By Account Balance voting models for which whitelisting is required to generate approval requests, but this screen also includes the other two voting models when a whitelist is used and so would more accurately be represented as (Whitelisted).
  • Details of phased transactions with open phasing polls are shown in each row of the list with an Approve button in the Actions column
  • The Approve button is highlighted and active if the logged-in account has not yet voted; after voting it becomes shaded and inactive.
  • Clicking on the Approve button opens an Approve Transaction pop-up entry form; then clicking on Approve creates an approval transaction.

Asset Approval Requests

This screen is accessed from the Bitswift Client menu in the left pane by first clicking on Asset Exchange to expand the submenu, then clicking on the Approval Requests submenu item; finally, select an asset from the drop-down list control under the screen title:

  • Details of phased transactions with open phasing polls are shown in each row of the list with an Approve button in the Actions column; the graphic in the gavel column indicates the phasing poll status.
  • The Approve button is highlighted and active if the logged-in account has not yet voted; after voting it becomes shaded and inactive.
  • Clicking on the Approve button opens an Approve Transaction pop-up entry form; then clicking on Approve creates an approval transaction.

Currency Approval Requests

This screen is accessed from the Bitswift Client menu in the left pane by first clicking on Monetary System to expand the submenu, then clicking on the Approval Requests submenu item; finally, select a currency from the drop-down list control under the screen title:

  • Details of phased transactions with open phasing polls are shown in each row of the list with an Approve button in the Actions column; the graphic in the gavel column indicates the phasing poll status.
  • The Approve button is highlighted and active if the logged-in account has not yet voted; after voting it becomes shaded and inactive.
  • Clicking on the Approve button opens an Approve Transaction pop-up entry form; then clicking on Approve creates an approval transaction.

Manual Approval

For any phased transaction that appears on the My Transactions screen but that uses neither the None nor the By Linked Transactions voting model, approval can be accomplished by the following procedure:

  1. click on the timestamp of the transaction to open the Transaction Info pop-up window
  2. click on the Actions tab
  3. click on the Approve Transaction button to open the Approve Transaction pop-up window
  4. click on the Approve button to approve the transaction, after entering the secret phrase in the case of the By Secret voting model

Only (confirmed) transactions that are directly connected with the logged-in account appear on this screen, including transactions sent or received, and those with phased polls with an invitation to vote (approval request).


When there is no approval request and the phased transaction does not appear on the My Transactions screen, it can still be found if the block height of the block containing the transaction is known, via the Blocks screen by clicking on the block height. Otherwise, the Approve Transaction API call can be used if the full hash of the phased transaction is known, and the full hash can be obtained using the Get Transaction API call if the transaction ID is known.

View Phasing Poll Status

The status of a phasing poll is indicated by a golden graphic which appears on an Approval Requests screen while the phasing poll is open and on the My Transactions screen, where the graphic changes color to green (approved) or red (disapproved) upon phasing poll completion at the finish height. A tooltip appears when the cursor hovers over the graphic, displaying status details.

The status can change until the phasing poll's completion, when it freezes. At the finish height, the phased transaction is executed only if all requirements for approval are met in the block just prior to the finish block.


</translate>