Coin Shuffling

Introduction

Coin Shuffling is a privacy feature that 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 detailed pop-up that 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 canceled 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 for shuffling processing to begin.
• Assignee represents the account that 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 the required number of participants do not register by this block height the shuffling is canceled and all funds are returned without a fine.
• Fee ratio The fee ratio that the shuffler will use to send transactions on the account's behalf. The participants have full control over the fee ratio to prevent that the shuffler will not be able to submit shuffling transactions in case there are no bundlers available.
• 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 monitors the blockchain for new shufflings. When a new shuffling meets 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=StandbyShuffling

The Standby Shufflers feature is enable within the Shuffling section in the Ardor Client Interface:

The main Standby Shufflers page lists the running standby shufflers on the current node. You can list the ones running for the current account or all of them by using the All and My tab selectors on the top right.

On this table, you will find the details of each shuffler as well as the pool of unused accounts status. The actual data will depend on the shuffler using the legacy list of public keys or the improved approach of deriving new accounts from an HD account.

The third button on the top right of the page opens the modal to start a new standby shuffler.

The bottom of the modal window allows you to define how the standby shuffler will get unused accounts for each new shuffling. You have two options: an HD wallet or a list of secret phrases. The new and recommended way is to use an HD wallet so the shuffler could derive new public keys from a BIP 32 node. You could also use the legacy approach of entering a list of secret phrases for unused accounts.

Pool of unused accounts

Each shuffling requires an unused recipient account. That means we need to provide each Standby Shuffler with a mechanism to get unused accounts. Before HD wallets the only way was to pass a list of public keys to the Standby Shuffler which will be used one at a time for each matching shuffling (see recipientsPublicKey parameter). This required to generate secret phrases in advance and limited the size of the pool of unused recipient accounts for the Standby Shuffler. With the new HD wallets, the derivation of public keys from a master public key is very easy and provides a simple mechanism that doesn't require generating new secrets and can produce a practically unlimited number of new accounts. This mechanism is also compatible with hardware devices like the Ledger wallet.

Using Seed / Hardware

You need to pass your Master Public Key to the Standby Shuffler so it can derive new accounts. Keep in mind this is not the public key of any specific account on the HD wallet. You can find this Master Public Key on the login screen when using a seed, click on the Advanced button just below the seed input.

The Start From Child Index allows you to adjust the starting index the standby shuffler will use to look for unused accounts. It doesn't matter if that index or any of the next indices are used, the standby shuffler will keep looking from that index until it finds an unused account, derive its public key, and use that for joining a matching shuffling.

Using Legacy accounts

You should generate the new accounts using the account wizard and write down the passphrases in 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. These 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, like other similar local node tools like bundlers 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.

Examples

Note: These examples were written for the legacy mechanism but are still valid. The only change when using the new HD wallets is that the Standby Shuffler will always have new accounts to use.

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 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 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 paid 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 that enables users to mix their funds quickly and efficiently with other users' funds by creating a random mapping between the existing user accounts and new recipient accounts provided by the users.

This feature is based 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 a 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, the 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 is canceled 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 canceled because the required number of participants is not met, nobody is penalized and all deposits are refunded. On testnet, the deposit and penalty are 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 canceled and this participant loses its 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 is successfully completed. 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 newly created. 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 a 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.