Coin Shuffling
Introduction
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.
Shuffling Menu
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).
Standby Shuffling
The Standby Shuffling add-on allows the creation of Standby Shufflers that monitor the blockchain for new shufflings. When a new shuffling meets a given criteria the Standby Shuffler will start a shuffler on the node targeting an unused recipient account from a configured pool. See the API pages for more details.
A Standby Shuffler does not join active shufflings when started even if they meet the Standby Shuffler criteria. To join active shuffling use the "join" button from the Active Shufflings page.
In order to use this feature you need to configure the corresponding add-on:
nxt.addOns=nxt.addons.StandbyShuffling
The Standby Shuffling feature is enable within the Shuffling section in the Ardor Client Interface:
Start StandbyShuffler:
My StandbyShufflers:
Pool of unused accounts
Each shuffling requires an unused recipient account. Because of that a Standby Shuffler has a pool of unused accounts (see recipientsPublicKey parameter) in order to join shufflings.
You should generate the new accounts using the account wizard and write down the passphrases in a secure storage. Then paste the passphrases, one per line, on the corresponding input of the Start Standby Shuffler window.
Keep in mind that the secret passphrases are never submitted to the remote node, only the derived public keys are.
When an unused account is needed the first one on the pool is reserved and assigned to the Shuffler that will monitor the shuffling. It's not discarded right away to reuse it in case we don't end up using it on the shuffling. The moment that the key is completely removed from the Standby Shuffler is when we enter the processing stage. From this point a failed shuffling will reveal the link between our account and the new public key. This reserved keys are recovered when the Shuffler ends.
When both the unused and reserved pools become empty the Standby Shuffler is automatically removed from the node.
Configuration persistence
The Standby Shufflers, as other similar local node tools like bundlers or forgers, are not persisted across node reboots.
Check the Processes feature for a easy to use and secure tool to help you with recovering the configuration upon node restart.
Examples
Example 1
Suppose you have an account with 5000 IGNIS and you want to shuffle some of them. You are not in a hurry and don't care if you shuffle it in batches. So, you set up a Standby Shuffler with a minimum amount of 100 and a maximum amount of 1000. You generate three new accounts using the account wizard and write down the passphrases in a secure storage. Let's call them NewAccount01, NewAccount02 and NewAccount03. You start the Standby Shuffler.
Current status:
- NewAccount01: unused
- NewAccount02: unused
- NewAccount03: unused
A new shuffling appears with an amount of 500 IGNIS. Your Standby Shuffler checks the shuffling: it meets the amount limits, you have enough balance and it has unused accounts. So, it joins the shuffling. Suppose that a few blocks later the shuffling completes successfully.
Current status:
- NewAccount01: 500 IGNIS
- NewAccount02: unused
- NewAccount03: unused
A new shuffling is created, 600 IGNIS. Again, it meets the criteria (100 <= 600 <= 1000) so it joins the shuffling for you. Let’s suppose it also completes successfully.
Current status:
- NewAccount01: 500 IGNIS
- NewAccount02: 600 IGNIS
- NewAccount03: unused
A new shuffling is created, 90 IGNIS. As the shuffling is outside the limits the Standby Shuffler ignores it.
One more shuffling of 200 IGNIS is detected. It meets the criteria. You have unused accounts so you join the shuffling.
Final status:
- NewAccount01: 500 IGNIS
- NewAccount02: 600 IGNIS
- NewAccount03: 200 IGNIS
The Standby Shuffler has no more unused accounts on the pool so it shuts down.
Example 2
Suppose you have an account with 2000 IGNIS and you want to shuffle all of them. You set up a Standby Shuffler with a minimum amount of 500 and no maximum. You generate three new accounts using the account wizard and write down the passphrases in a secure storage. Let's call them NewAccount01, NewAccount02 and NewAccount03. You start the Standby Shuffler.
Current status:
- NewAccount01: unused
- NewAccount02: unused
- NewAccount03: unused
A new shuffling appears with an amount of 500 IGNIS. Your Standby Shuffler checks the shuffling: it meets the amount limits, you have enough balance and it has unused accounts. So, it joins the shuffling. Suppose that a few blocks later the shuffling completes successfully.
Current status:
- NewAccount01: 500 IGNIS
- NewAccount02: unused
- NewAccount03: unused
A new shuffling appears with an amount of 1800 IGNIS. You had initially 2000 IGNIS and you've shuffled 500 IGNIS and payed some fees so you are probably a bit below 1500 IGNIS. You don't have enough funds to join the shuffling so the Standby Shuffler skips this shuffling.
A new shuffling is created, 90 IGNIS. As the shuffling is outside the limits the Standby Shuffler ignores it.
A new shuffling appears with an amount of 1400 IGNIS. Let's suppose you have enough funds at this moment. So, it joins the shuffling. Suppose that a few blocks later the shuffling completes successfully.
Current status:
- NewAccount01: 500 IGNIS
- NewAccount02: 1400 IGNIS
- NewAccount03: unused
You currently have, probably, some funds left but the Standby Shuffler has a minimum of 500 IGNIS so it won't join any other shuffling.
Technical Background
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 [1] which is also the source of the feature name.
Overview:
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.
Warnings
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.
