Shuffling

Coin shuffling can be used to perform mixing of NXT, MS currencies (unless created as non-shuffleable), or AE assets. Any account can create a new shuffling, specifying the holding to be shuffled, the shuffle amount, number of participants required, and registration deadline.

Get Account Shufflings

Retrieves info about shufflings for a specific account.

Request:

requestType is getAccountShufflings
account is the account ID
includeFinished is true to include completed shufflings (optional)
includeHoldingInfo is true to include holding info (optional)
firstIndex is a zero-based index to the first tagged data to retrieve (optional)
lastIndex is a zero-based index to the last tagged data to retrieve (optional)
adminPassword is a string with the admin password (optional)
requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)
shufflings (A) is an array containing the shuffling object (refer to Get Shuffling)

Get Account Shufflings Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getAccountShufflings&
 account=NXT-UZNP-6LBA-YQ38-3TEY8

Response

{
 "requestProcessingTime": 91,
 "shufflings": [
  {
   "blocksRemaining": 4372,
   "amount": "25000000000000",
   "shufflingStateHash": "be12c737ad86e551621f57ebddaaaa61e66cf0a206fabfe40538304ff674c7a7",
   "issuer": "11802441287912491934",
   "holding": "0",
   "stage": 0,
   "holdingType": 0,
   "participantCount": 7,
   "assigneeRS": "NXT-UZNP-6LBA-YQ38-3TEY8",
   "shuffling": "5901270965262160574",
   "registrantCount": 2,
   "assignee": "1403321141259239061",
   "issuerRS": "NXT-V4WY-U928-GRN8-CKPL9",
   "shufflingFullHash": "be12c737ad86e551621f57ebddaaaa61e66cf0a206fabfe40538304ff674c7a7"
  }
 ]
}

Get All Shufflings

Retrieves info about all shufflings.

Request:

requestType is getAllShufflings
includeFinished is true to include completed shufflings (optional)
includeHoldingInfo is true to include holding info (optional)
finishedOnly is true to omit not yet finished shufflings (optional)
firstIndex is a zero-based index to the first tagged data to retrieve (optional)
lastIndex is a zero-based index to the last tagged data to retrieve (optional)
adminPassword is a string with the admin password (optional)
requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)
shufflings (A) is an array containing the shuffling object (refer to Get Shuffling)

Get All Shufflings Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getAllShufflings

Response

{
 "requestProcessingTime": 81,
 "shufflings": [
  {
   "blocksRemaining": 226,
   "amount": "5000000000000",
   "shufflingStateHash": "9be2ed518e46d921df9f9f6425cc16a399f72a7833c58dbeb2a261e04620c392",
   "issuer": "16667202175165271068",
   "holding": "0",
   "stage": 0,
   "holdingType": 0,
   "participantCount": 5,
   "assigneeRS": "NXT-V4WY-U928-GRN8-CKPL9",
   "shuffling": "2439058250271679131",
   "registrantCount": 3,
   "assignee": "11802441287912491934",
   "issuerRS": "NXT-J52W-4BF7-L4J9-GEGMG",
   "shufflingFullHash": "9be2ed518e46d921df9f9f6425cc16a399f72a7833c58dbeb2a261e04620c392"
  }
 ]
}

Get Assigned Shufflings

Retrieves info about a shufflings that are currently assigned to a specific account.

Request:

requestType is getAssignedShufflings
account is the account ID
includeHoldingInfo is true to include holding info (optional)
firstIndex is a zero-based index to the first tagged data to retrieve (optional)
lastIndex is a zero-based index to the last tagged data to retrieve (optional)
adminPassword is a string with the admin password (optional)
requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)
shufflings (A) is an array containing the shuffling object (refer to Get Shuffling)

Get Assigned Shufflings Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getAssignedShufflings&
 account=NXT-V4WY-U928-GRN8-CKPL9

Response

{
 "blocksRemaining": 20,
 "amount": "5000000000000",
 "shufflingStateHash": "9be2ed518e46d921df9f9f6425cc1...",
 "requestProcessingTime": 3,
 "issuer": "16667202175165271068",
 "holding": "0",
 "stage": 1,
 "holdingType": 0,
 "participantCount": 5,
 "assigneeRS": "NXT-V4WY-U928-GRN8-CKPL9",
 "shuffling": "2439058250271679131",
 "registrantCount": 5,
 "assignee": "11802441287912491934",
 "issuerRS": "NXT-J52W-4BF7-L4J9-GEGMG",
 "shufflingFullHash": "9be2ed518e46d921df9f9f6425cc16a399..."
}

Get Holding Shufflings

Retrieves info about shufflings for a specific holding and/or stage.

Request:

requestType is getHoldingShufflings
holding is the holding ID (optional)
stage is the stage of the shuffling (See Get Constants for type definitions) (optional)
includeFinished is true to include completed shufflings (optional)
firstIndex is a zero-based index to the first tagged data to retrieve (optional)
lastIndex is a zero-based index to the last tagged data to retrieve (optional)
adminPassword is a string with the admin password (optional)
requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)
shufflings (A) is an array containing the shuffling object (refer to Get Shuffling)

Get Holding Shufflings Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getHoldingShufflings&
 holding=15344649963748848799&
 includeFinished=true

Response

{
 "requestProcessingTime": 4,
 "shufflings": [
  {
   "holding": "15344649963748848799",
   "blocksRemaining": 0,
   "amount": "1000",
   "stage": 4,
   "shufflingStateHash": "57ed7cc02fa5b1f289d2a345314be5ec557ad093a5fd3070a16aba952d30656f",
   "holdingType": 1,
   "participantCount": 5,
   "shuffling": "144176732027925694",
   "registrantCount": 1,
   "issuer": "17417706268123203912",
   "issuerRS": "NXT-A4CA-L7JT-ZYGU-HZ2G5",
   "shufflingFullHash": "beb46651f937000259819298872f1721170a4c2e1af7f7900cb2ca01188fd942"
  }
 ]
}

Get Shufflers

Retrieves info about active shufflers on the current node.

Request:

requestType is getShufflers
account is account ID (optional)
shufflingFullHash is shuffling full hash (optional)
secretPhrase is secret phrase of the account doing the shuffling (required if adminPassword is not provided)
adminPassword is the admin password (required if secretPhrase is not provided)
includeParticipantState to include each shuffling participant's state (optional)

Response:

shufflers (A) is an array containing all currently running shuffling processes on the node.
- account (S) is account ID
- accountRS (S) is the account Reed Solomon address
- recipient (S) is the recipient account ID to where the funds will be sent once the shuffling is completed
- recipientRS (S) is the recipient account Reed Solomon address to where the funds will be sent once the shuffling is completed
- shuffling (S) is the shuffling ID
- shufflingFullHash (S) is the shuffling full hash
- participantState (N) is the state for the participant (For more info, see shufflingParticipantStates array in Get Constants)
requestProcessingTime (N) is the API request processing time (in millisec)

Get Shufflers Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getShufflers&
 adminPassword=IWontTellYou

Response

{
 "shufflers": [
  {
   "accountRS": "NXT-7A48-47JL-T7LD-D5FS3",
   "recipientRS": "NXT-H42E-48UL-FM7A-AVEC2",
   "recipient": "9235083011255928844",
   "shuffling": "9534657251385467319",
   "account": "12745647715474645062",
   "shufflingFullHash": "b7e1eedb40e851849cb77a53075ce74aa..."
  }
 ],
 "requestProcessingTime": 0
}

Get Shuffling

Retrieves info about a shuffling.

Request:

requestType is getShuffling
shuffling is the shuffling ID
includeHoldingInfo is true to include holding info (optional)
requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

blocksRemaining (N) number of blocks remaining until current stage is finished.
amount (S) the amount of holdingType to be shuffled
shufflingStateHash (S) state hash of the shuffling
shufflingFullHash (S) the full hash of the shuffling
issuer (S) is the issuer account ID
issuerRS (S) is the Reed-Solomon address of the issuer account
assignee (S) is the current assignee account ID
assigneeRS (S) is the Reed-Solomon address of the current assignee account
shuffling (S) is the shuffling ID
holding (S) is the asset or currency ID
holdingType (N) is the holding type (See Get Constants for type definitions)
stage (N) is the current stage of the shuffling (See Get Constants for type definitions)
participantCount (N) is the number of participants required to start the shuffling
registrantCount (N) is the number of registrered participants
recipientPublicKeys (A) is an array of recipient public keys
holdingInfo (A) is an array containing the asset or currency info (if includeHoldingInfo is true and holdingType is not NXT)
requestProcessingTime (N) is the API request processing time (in millisec)

Get Shuffling Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getShuffling&
 shuffling=3347171811359602131

Response

{
 "blocksRemaining": 956,
 "amount": "100000000000",
 "shufflingStateHash": "d3354a42078b732e16561b67a37d699d0410c564a4d18568319170665bf5dd9b",
 "requestProcessingTime": 2,
 "issuer": "10740484011813680725",
 "holding": "0",
 "stage": 0,
 "holdingType": 0,
 "participantCount": 5,
 "assigneeRS": "NXT-V4WY-U928-GRN8-CKPL9",
 "shuffling": "3347171811359602131",
 "registrantCount": 2,
 "assignee": "11802441287912491934",
 "issuerRS": "NXT-PFLP-BQHY-NG4J-BXG5C",
 "shufflingFullHash": "d3354a42078b732e16561b67a37d699d0410c564a4d18568319170665bf5dd9b"
}

Get Shuffling Participants

Retrieves info about participants in a shuffling.

Request:

requestType is getShufflingParticipants
shuffling is the shuffling ID
requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

participants (A)
- shuffling (S) is the shuffling ID
- account (S) is the account ID
- accountRS (S) is the account Reed Solomong address
- state (N) is the state for the participant (For more info, see shufflingParticipantStates array in Get Constants)
- nextAccount (S) is the account ID of the next account in turn
- nextAccountRS (S) is the account Reed Solomon address of the next account in turn
requestProcessingTime (N) is the API request processing time (in millisec)

Get Shuffling Participants Example

Request

Test request

http://localhost:7876/nxt?
 requestType=getShufflingParticipants&
 shuffling=16292433427943984172

Response

{
 "requestProcessingTime": 5,
 "participants": [
  {
   "nextAccountRS": "NXT-KTTY-WRE6-2B5Y-4CYWR",
   "accountRS": "NXT-3ZXY-KWR5-LR8V-2PYAT",
   "shuffling": "16292433427943984172",
   "state": 2,
   "nextAccount": "3167098051496568638",
   "account": "910806360590974910"
  },
  {
   "nextAccountRS": "NXT-L8VW-NRUG-LZ6Q-62WWW",
   "accountRS": "NXT-KTTY-WRE6-2B5Y-4CYWR",
   "shuffling": "16292433427943984172",
   "state": 2,
   "nextAccount": "5653003407546981244",
   "account": "3167098051496568638"
  },
  {
   "nextAccountRS": "NXT-XC7L-35JW-FZCL-24NUT",
   "accountRS": "NXT-L8VW-NRUG-LZ6Q-62WWW",
   "shuffling": "16292433427943984172",
   "state": 2,
   "nextAccount": "930699247665195186",
   "account": "5653003407546981244"
  },
  {
   "nextAccountRS": "NXT-2222-2222-2222-22222",
   "accountRS": "NXT-XC7L-35JW-FZCL-24NUT",
   "shuffling": "16292433427943984172",
   "state": 2,
   "nextAccount": "0",
   "account": "930699247665195186"
  }
 ]
}

Shuffling Cancel

Cancels a shuffling

Request: Refer to Create Transaction Request for common parameters.

requestType is shufflingCancel
shuffling is the shuffling ID
shufflingStateHash is the state hash of the shuffling
cancellingAccount is the account ID (optional)

Response Refer to Create Transaction Response.

Shuffling Create

Creates a new shuffling.

Request: Refer to Create Transaction Request for common parameters.

requestType is shufflingCreate
holding is the holding id (optional if holdingType is 0)
holdingType is the holding type (See Get Constants for type definitions) (optional)
amount is the amount of the holding to shuffle
participantCount is the number of participants
registrationPeriod is the number of blocks the participants have to register until the shuffle is cancelled

Response Refer to Create Transaction Response.

Shuffling Create Example

Request

Test request

http://localhost:7876/nxt?
 requestType=shufflingCreate&
 amount=10000000000000&
 participantCount=7&
 registrationPeriod=9757&
 secretPhrase=IWontTellYou&
 feeNQT=100000000&
 deadline=1440

Response

{
 "senderPublicKey": "ffcafb6de1ec93db5fe0475a6e2efd82faa3cb89a47a7d96f5579b0deadd5c10",
 "signature": "36b410b83abb4e373bf77c715c8ef3b06ba6c872e621e3f5f412dc1424eb6a0710ed8...",
 "feeNQT": "100000000",
 "transactionIndex": 0,
 "requestProcessingTime": 5,
 "type": 7,
 "confirmations": 9906,
 "fullHash": "2d10f4e18f808aa8d0de06d5cddcd77828eb6e7548f62e48de83f58fdf0629d5",
 "version": 1,
 "phased": false,
 "ecBlockId": "13021232786632787054",
 "signatureHash": "18956d76e3ed20937027373615e5fb49f11d1ac86eed279176856b59644899f5",
 "attachment": {
  "holding": "0",
  "amount": "10000000000000",
  "registrationPeriod": 9757,
  "holdingType": 0,
  "participantCount": 7,
  "version.ShufflingCreation": 1
 },
 "senderRS": "NXT-V4WY-U928-GRN8-CKPL9",
 "subtype": 0,
 "amountNQT": "0",
 "sender": "11802441287912491934",
 "ecBlockHeight": 817230,
 "block": "435349863926964285",
 "blockTimestamp": 80029572,
 "deadline": 1440,
 "transaction": "12144660700617510957",
 "timestamp": 80029541,
 "height": 817245
}

Shuffling Process

Manually process the shuffling for a specific participant. Note that the shuffling must be in processing stage and the secretPhrase must match the current shuffling assignee.

Request: Refer to Create Transaction Request for common parameters.

requestType is shufflingProcess
shuffling is the shuffling ID
recipientSecretPhrase is the secret phrase of the recipient account (optional if recipientPublicKey is provided)
recipientPublicKey is the public key of the recipient account (optional if recipientSecretPhrase is provided)

Response Refer to Create Transaction Response.

Shuffling Process Example

Request

Test request

http://localhost:7876/nxt?
 requestType=shufflingProcess&
 shuffling=12144660700617510957&
 recipientSecretPhrase=IWontTellYou&
 secretPhrase=IWontTellYou&
 feeNQT=100000000&
 deadline=1440

Response

{
   "senderPublicKey": "ffcafb6de1ec93db5fe0475a6e2efd82faa3cb89a47a7d96f5579b0deadd5c10",
   "signature": "fb6112d759cedfefe14a7bdbe19b2fac73d334566f05fc20d7d79933879b140...",
   "feeNQT": "1000000000",
   "transactionIndex": 1,
   "type": 7,
   "confirmations": 251,
   "fullHash": "0d0855396fa1a60c8b50507069abdb5a7c6af3fdb49f12766c8630ec66309642",
   "version": 1,
   "phased": false,
   "ecBlockId": "17529486445813261105",
   "signatureHash": "a7c1d67e2ff01dd8e3cf72869428a708a6ad087bb6247e628fb1964456eea66b",
   "attachment": {
    "shuffling": "12144660700617510957",
    "shufflingStateHash": "e98b2810531c6e807e5e89bb2537025bc7b4fb72e79ab675deb6fec2b8ec6d78",
    "data": [
     "438e2560cd958a173dc3b7adc3eb3c02a69ea5..."
    ],
    "version.ShufflingProcessing": 1,
    "hash": "2e3cecabbf59a47d55399649be89d1bcd1b56264dca32cb269f88b30cbe2c262"
   },
   "senderRS": "NXT-V4WY-U928-GRN8-CKPL9",
   "subtype": 2,
   "amountNQT": "0",
   "sender": "11802441287912491934",
   "ecBlockHeight": 826902,
   "block": "15948287569415806210",
   "blockTimestamp": 80611249,
   "deadline": 1440,
   "transaction": "911593473664419853",
   "timestamp": 80611213,
   "height": 826917
  }

Shuffling Register

Registers a new participant to an existing shuffling. The shuffling must be in stage registration.

Request: Refer to Create Transaction Request for common parameters.

requestType is shufflingRegister
shufflingFullHash is the full hash of the shuffling to register

Response Refer to Create Transaction Response.

Shuffling Register Example

Request

Test request

http://localhost:7876/nxt?
 requestType=shufflingRegister&
 shufflingFullHash=2d10f4e18f808aa8d0de06d5cddcd77828eb6e7548f62e48de83f58fdf0629d5&
 secretPhrase=IWontTellYou&
 feeNQT=100000000&
 deadline=1440

Response

{
 "senderPublicKey": "6351706ab8ea5c94243e6b0bff3be05f2e1b9accc83004af3e655a8fbc104735",
 "signature": "23bb57aee566ba2c27fe8c83ea4e88821f9f23c820371a39b5d49dbd327...",
 "feeNQT": "100000000",
 "transactionIndex": 1,
 "requestProcessingTime": 3,
 "type": 7,
 "confirmations": 9924,
 "fullHash": "467e60696e598fe5c075446897ff636886bf7c0e9...",
 "version": 1,
 "phased": false,
 "ecBlockId": "4928509411801335816",
 "signatureHash": "b0e945000b9010814f5399d9006a21939089db5616...",
 "attachment": {
  "version.ShufflingRegistration": 1,
  "shufflingFullHash": "2d10f4e18f808aa8d0de06d5cddcd77828eb6e7..."
 },
 "senderRS": "NXT-D78H-8QHV-DEP2-5TAGA",
 "subtype": 1,
 "amountNQT": "0",
 "sender": "3763066681748198607",
 "ecBlockHeight": 817256,
 "block": "12642960475175742738",
 "blockTimestamp": 80031214,
 "deadline": 1440,
 "transaction": "16541538287104327238",
 "timestamp": 80031109,
 "height": 817265
}

Shuffling Verify

Sends a verification that an account's recipient public key is found within a shuffling.

Request: Refer to Create Transaction Request for common parameters.

requestType is shufflingVerify
shuffling is the shuffling ID
shufflingStateHash is the current state hash of the shuffle

Response Refer to Create Transaction Response.

Shuffling Verify Example

Request

Test request

http://localhost:7876/nxt?
 requestType=shufflingVerify&
 shuffling=12144660700617510957&
 shufflingStateHash=90832470918374087102938470198234&
 recipientSecretPhrase=IWontTellYou&
 secretPhrase=IWontTellYou&
 feeNQT=100000000&
 deadline=1440

Response

{
 "senderPublicKey": "f050f86b050c1de933d8094c9a05a346b2319912313a04b822bba15d6d256505",
 "signature": "a23968d9cf5313e745fa4b50102f7f6d664c1b574d8ff2fbcc721cb967a42a0225f1e...",
 "feeNQT": "100000000",
 "transactionIndex": 3,
 "requestProcessingTime": 3,
 "type": 7,
 "confirmations": 287,
 "fullHash": "296a76a1601da4a06c6524df5791553b5d305cb266f71afb6e9d7aa0149c04ff",
 "version": 1,
 "phased": false,
 "ecBlockId": "3207126357685519085",
 "signatureHash": "7b69ba9ffb10d725b693abb53157f274cbf42f2435e919821cda67f889f44e96",
 "attachment": {
  "version.ShufflingVerification": 1,
  "shuffling": "12144660700617510957",
  "shufflingStateHash": "fbc8b99c99c4e09203f1237771e38c7ee484c18a72572c3d1adae04da858fe92"
 },
 "senderRS": "NXT-KHDF-9KSG-2UCY-BUQZ4",
 "subtype": 4,
 "amountNQT": "0",
 "sender": "10484056935692287341",
 "ecBlockHeight": 826914,
 "block": "1046003298185760668",
 "blockTimestamp": 80612146,
 "deadline": 1440,
 "transaction": "11575409243111975465",
 "timestamp": 80611663,
 "height": 826925
}

Start Shuffler

Starts a automated Shuffler. 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.

Request:

requestType is startShuffler
secretPhrase is the secret phrase of the account entering the shuffling
shufflingFullHash the full hash of the shuffling
recipientSecretPhrase the secret phrase of the recipient account (optional if recipientPublicKey is present)
recipientPublicKey the public key of the recipient account (optional if recipientSecretPhrase is present)

Response

shuffling (S) is the shuffling ID
shufflingFullHash (S) is the full hash of the shuffling
account (S) is the account ID
accountRS (S) is the account Reed Solomong address
recipient (S) is the account ID of the recipient account
recipientRS (S) is the account Reed Solomon address of the recipient account
requestProcessingTime (N) is the API request processing time (in millisec)

Start Shuffler Example

Request

Test request

http://localhost:7876/nxt?
 requestType=startShuffler&
 shufflingFullHash=2d10f4e18f808aa8d0de06d5cddcd77828eb6e7548f62e48de83f58fdf0629d5&
 secretPhrase=IWontTellYou&
 recipientSecretPhrase=IWontTellYou

Response

{
 "shuffling": "12144660700617510957",
 "shufflingFullHash": "2d10f4e18f808aa8d0de06d5cddcd77828eb6e7548f62e48de83f58fdf0629d5",
 "account": "11802441287912491934",
 "accountRS": "NXT-V4WY-U928-GRN8-CKPL9",
 "recipient": "3763066681748198607",
 "recipientRS": "NXT-D78H-8QHV-DEP2-5TAGA",
 "requestProcessingTime": 7
}

Stop Shuffler

Stops a previously started automated Shuffler.

Request:

requestType is stopShuffler
account is the account ID (optional if shufflingFullHash or secretPhrase or adminPassword is provided)
shufflingFullHash the full hash of the shuffling (optional if account or adminPassword is provided)
secretPhrase is the secret phrase of the account entering the shuffling (optional if adminPassword is provided)
adminPassword is the admin password (optional if secretPhrase is provided)

Response

stoppedShuffler (B) means the specified shuffler was stopped
stoppedAllShufflers (B) means all shufflers on the node was stopped (only if adminPassword is provided in request)
requestProcessingTime (N) is the API request processing time (in millisec)

Stop Shuffler Example

Request

Test request

http://localhost:7876/nxt?
 requestType=stopShuffler&
 shufflingFullHash=2d10f4e18f808aa8d0de06d5cddcd77828eb6e7548f62e48de83f58fdf0629d5&
 secretPhrase=IWontTellYou

Response

{
 "stoppedShuffler": true,
 "requestProcessingTime": 7
}