Coin Shuffling is a privacy feature which enables users to mix assets, currencies or child chain token funds (as long as the child chain has enabled such feature) quickly and efficiently with other users' funds by creating a random mapping between the existing user accounts and a new recipient accounts provided by the users.
This guide describes the Coin Shuffling feature, active for Ignis since the Ardor launch. Usage examples apply to the Ardor Client Interface.
Coin Shuffling is accessed by clicking on Shuffling in the left-pane menu area of the Ardor Client Interface, causing a submenu to appear:
|Shuffling: This item expands or contracts the submenu below and opens the Active Shufflings page which lists the active shufflings related to the child chain tokens selected.|
|Active Shufflings: This item displays a list of all Active Shufflings.|
|My Shufflings: This item displays all the shufflings in which the current account participates.|
|Create Shuffling: This item opens a pop-up entry form for creating a new shuffling as described in Create Shuffling.|
Active Shufflings Page
- Shuffling clicking on a shuffling link in the Shuffling column opens a detail pop-up which displays details about the shuffling state and the list of senders and recipients in case the shuffling is complete.
- Stage displays the current stage of the shuffling process.
- Holding shows the type of holding used for shuffling asset, currency or child chain tokens (eg: Ignis).
- Amount is the common amount to shuffle specified in the holding unit.
- Blocks Remaining is the number of blocks until shuffling is cancelled unless the required information necessary for the shuffling to advance to the next stage is provided.
- Participants shows the existing number of shuffling registrants and the number of required registrants in order for shuffling processing to begin.
- Assignee represents account who last updated the shuffling or the account which needs to specify the next piece of data.
- Status displays 'join' in case the user is still not registered for the shuffling or the shuffler status in case the user has registered.
My Shufflings Page
- First columns are similar to the active shufflings page.
- The Shuffler, Recipient and State columns represent the status of the Shuffler component which manages the shuffling process for the current account and shuffling.
Create Shuffling Modal
- Create a new Shuffling.
- Holding Type is the token used by the shuffling. child chain tokens (eg: Ignis), Asset id or Currency name.
- Amount the common amount used by all shuffling participants, specified in the holding token.
- Register Until shuffling registration deadline. If required number of participants do not register by this block height the shuffling is cancelled and all funds are returned without fine.
- Participant Count number of registrants required to trigger the shuffling. Between 3 and 30.
Start Shuffler Modal
- Start the shuffler process on the current node to coordinate the shuffling
- Recipient Passphrase the passphrase of the recipient account for your shuffling participant. Do not lose this passphrase since it is the passphrase to your shuffled funds.
- Recipient Account account id derived from the recipient passphrase (read only field).
Coin Shuffling is a privacy feature which enables users to mix their funds quickly and efficiently with other users' funds by creating a random mapping between the existing user accounts and a new recipient accounts provided by the users.
This feature is based on the on the academic paper  which is also the source of the feature name.
The implementation of the feature is based on the Ardor platform, this eliminates some of the manual steps and trust issues of existing 3rd party mixing solutions. The client wallet provides user interface for users to monitor and coordinate their actions during the shuffling process.
Shuffling can be performed using child chain tokens (eg: Ignis), assets or currencies as specified by the creator of the shuffling.
Any account can create a new shuffling, specifying the holding to be shuffled, the shuffle amount, number of participants required, and registration deadline.
This is done using the shufflingCreate API. The subsequent shuffling steps can be performed manually, by using the shufflingRegister (for accounts other than the creator), shufflingProcess and shufflingVerify or shufflingCancel APIs.
However, due to the complexity of the process and the difficulty to predict the timing in which actions should be submitted, it is impractical to manage a shuffling manually. Therefore shuffling is managed by an automated component called "Shuffler", using the startShuffler API.
Once started, the Shuffler monitors the blockchain state for transactions relevant to the specified shuffle, and automatically submits the required transactions on behalf of the user, performing shuffle processing, verification, or cancellation as needed. To do this, the Shuffler is required to keep the users' secret phrase in memory, same as when forging. And just like with forging, restart or a crash of the node requires restarting the shuffler manually. The shuffler remains running for 720 blocks after a shuffling either completes successfully or cancelled to make sure it is still active in case of an (unlikely) blockchain reorder.
There is a single shuffler per node/shuffling/participant combination. A single node can run up to 100 shufflers concurrently for various shufflings and participants.
To participate in a shuffling, a deposit of 0.12 Ignis is needed (see fees), in addition to the amount of currency or asset being shuffled or if shuffling, the amount of the shuffle must exceed this 0.12 Ignis minimum.
When a shuffling completes successfully, this amount is added to the recipient account balance, to allow it to send outgoing transactions (as it is required that only new, unused accounts are specified as recipients). In case the shuffling fails due to a registered participant failing to participate as required, or intentionally submitting false data, the participant responsible for the shuffle cancellation is penalized by sending this security deposit to the forgers of the shuffle finish block and the previous three blocks. If a shuffling is cancelled because the required number of participants is not met, nobody is penalized and all deposits are refunded. On testnet, the deposit and penalty is only 10 Ignis or 10 Bits.
After shuffling registration is complete, participants must submit processing data within a 100 blocks period each (10 blocks on testnet). For the verification and blame phase, the total allowance for all participants is 100 + numberOfParticipants blocks (again reduced to 10 + numberOfParticipants blocks on testnet). Full blocks are not counted towards the limit. If at any stage the deadline is reached without some participant submitting the next required transaction, the shuffling is cancelled and this participant loses it's security deposit of 0.12 Ignis. This process is managed by the shuffler. It is therefore critical that after registering for a shuffling, the shuffler started, is left running until the shuffling successful completion. In case the node must be restarted, all previously running shufflers must be started manually.
Query APIs to retrieve currently running shufflers, shufflings, and shuffling participants are: getAllShufflings, getAccountShufflings, getAssignedShufflings, getHoldingShufflings, getShufflers, getShuffling, and getShufflingParticipants.
Finished shufflings can be automatically deleted from the database in case the nxt.deleteFinishedShufflings property is set to true (default is false).
The fee for creating a shuffling or registering in one is 0.12 Ignis, for the shuffling process or shuffling cancel transactions 10 Ignis, and for the verify transaction 0.1 Ignis.
1. The recipient account of the shuffling participant must be a newly created account. Participants should take great care to create a strong passphrase for the recipient account and save this passphrase for later Failing to so will result in your funds being lost or stolen.
2. Once an account creates a shuffling or registers as participant in one, **the node used by this account must remain online and the shuffler must remain active.** The state of the shuffler can be monitored using the "My Shufflings" page. In case your node is restarted, make sure to start all shufflers related to the active shufflings in which your account participates.