Websockets

sync/wallets/

Inputs

• subscribe to multi-wallet events:

  { 
   "action": "subscribe", 
   "wallets": ["<wallet address without 0x prefix>"] 
  }

Outputs

• on subscribe action:

  { 
   "status": "success", 
   "message": "subscription group updated successfully" 
  }

• on incoming transfer:

  { 
   "status": "notify", 
   "message": { 
       "type": "incoming_transfer", 
       "topic": "<wallet address without 0x prefix>",
       "data": "<tx object>" 
   } 
  }

• on incoming receipt:

  { 
   "status": "notify", 
   "message": { 
       "type": "incoming_receipt", 
       "topic": "<wallet address without 0x prefix>",
       "data": "<tx object>" 
   } 
  }

• on incoming transfer confirmation:

  { 
   "status": "notify", 
   "message": { 
       "type": "incoming_confirmation", 
       "topic": "<wallet address without 0x prefix>",
       "data": "<tx object>" 
   } 
  }

• on transfer timeout:

  { 
   "status": "notify", 
   "message": { 
       "type": "timeout_transfer", 
       "topic": "<wallet address without 0x prefix>",
       "data": "<tx object>" 
   } 
  }

• on swap match:

  { 
   "status": "notify", 
   "message": { 
       "type": "matched_swap", 
       "topic": "<wallet address without 0x prefix>",
       "data": "<tx object>" 
   } 
  }

• on swap finalization:

  { 
   "status": "notify", 
   "message": { 
       "type": "finalized_swap", 
       "topic": "<wallet address without 0x prefix>",
       "data": "<tx object>" 
   } 
  }

• on wallet admission:

  { 
   "status": "notify", 
   "message": { 
       "type": "registered_wallet", 
       "topic": "<wallet address without 0x prefix>",
       "data": { "address": "<wallet address>", "token": "<token address>" }
   } 
  }

• on deposit confirmation:

  { 
   "status": "notify", 
   "message": { 
       "type": "confirmed_deposit", 
       "topic": "<wallet address without 0x prefix>",
       "data": { 
           "txid": "<ethereum tx id>", 
           "block": "<ethereum block number>", 
           "eon_number": "<commit-chain eon number>", 
           "amount": "<deposit amount>", 
           "time": "<deposit time>"
       }
   } 
  }

• on withdrawal request:

  { 
   "status": "notify", 
   "message": { 
       "type": "requested_withdrawal", 
       "topic": "<wallet address without 0x prefix>",
       "data": {
           "txid": "<ethereum tx id>", 
           "block": "<ethereum block number>", 
           "eon_number": "<commit-chain eon number>", 
           "amount": "<withdrawal request amount>", 
           "time": "<withdrawal request time>",
           "slashed": "<whether withdrawal request was slashed or not, this event will usually return slashed == false>"
       } 
   } 
  }

• on withdrawal confirmation:

  { 
   "status": "notify", 
   "message": { 
       "type": "confirmed_withdrawal",
       "topic": "<wallet address without 0x prefix>", 
       "data": {
           "txid": "<ethereum tx id>", 
           "block": "<ethereum block number>", 
           "eon_number": "<commit-chain eon number>", 
           "amount": "<withdrawal request amount>", 
           "time": "<withdrawal request time>",
           "request": "<withdrawal request object>",
       } 
   } 
  }

sync/swaps/

Inputs

• subscribe to token-pair events:

  { 
   "action": "subscribe", 
   "swaps": ["<sell token address without 0x prefix><buy token address withour 0x prefix>"] 
  }

Outputs

• on subscribe action:

  { 
   "status": "success", 
   "message": "subscription group updated successfully" 
  }

• on incoming swap:

  { 
   "status": "notify", 
   "message": { 
       "type": "incoming_swap", 
       "topic": "<sell token address without 0x prefix><buy token address withour 0x prefix>",
       "data": "<tx object>" 
   } 
  }

Notes to override the subscription list, simply send out another subscribe action message with the new list.

HTTP

Admission

Defines the endpoints and methods for registration.

• Getting registered wallets

  GET admission/?[format=json]

• Registering new wallet

  POST admission/
  body: {
  "authorization": "<commit-chain_authorisation>",
  "address": "<wallet address without 0x prefix>",
  "token": "<contract address without 0x prefix>"
  }

Auditor

Defines the endpoints for data retrieval by clients.

• Commit-chain status overview

  GET audit/?[format=json]

• List of commit-chain tokens

  GET audit/tokens/?[format=json]

• Wallet synchronization data

  GET audit/<token>/<wallet>/?[format=json]

• Wallet registration data

  GET audit/<token>/<wallet>/whois?[format=json]

• List buy and sell order for a token pair (left token, right token)

  GET audit/swaps/<left token address>/<right token address>?[format=json]

Transactor

Defines the endpoints for making transfers.

• Transfer submission

  PUT transfer/
  body: {
  "wallet": {
    "address": "<wallet address without 0x prefix>",
    "token": "<contract address without 0x prefix>"
  },
  "amount": <decimal>,
  "round": <round the transfer is performed>,
  "recipient": "<recipient address without 0x prefix>",
  "nonce": <nonce of the transfer | decimal>,
  "wallet_signature": {
    "value": "wallet_signature"
  },
  "wallet_balance_signature": {
    "value": "wallet_balance_signature"
  },
  ​
  ["id": <transfer id>,]
  ["time": "<datetime>",]
  ["sender_aggregate": {
    "wallet_signature": "<wallet_signature>",
    "hub_signature": "<hub_signature>",
    "updated_spendings": "<updated_spendings>",
    "updated_gains": "<updated_gains>",
    "tx_set_hash": "<tx_set_hash>",
    "tx_set_proof": [<tx_proof>, <tx_proof>, ...],
    "tx_set_index": <decimal>
  },]
  ["recipient_aggregate": {
    "wallet_signature": "<wallet_signature>",
    "hub_signature": "<hub_signature>",
    "updated_spendings": "<updated_spendings>",
    "updated_gains": "<updated_gains>",
    "tx_set_hash": "<tx_set_hash>",
    "tx_set_proof": [<tx_proof>, <tx_proof>, ...],
    "tx_set_index": <decimal>
  },]
  ["processed": <has the transfer been processed>,]
  ["complete": <is the transfer complete>,]
  ["final_receipt_hashes": "<final_receipt_hashes>",]
  ["final_receipt_index": "<integer>",]
  }

• Receipt

  GET transfer/<id>/[?format=json]

• Receipt submission

  POST transfer/<id>
  body: {
  "wallet_signature": {
    "value": "wallet_signature"
  },
  ​
  ["wallet": {
    "address": "<wallet address without 0x prefix>",
    "token": "<contract address without 0x prefix>"
  },]
  ["recipient": "<recipient address without 0x prefix>",]
  ["time": "<datetime>",]
  ["sender_aggregate": {
    "wallet_signature": "<wallet_signature>",
    "hub_signature": "<hub_signature>",
    "updated_spendings": "<updated_spendings>",
    "updated_gains": "<updated_gains>",
    "tx_set_hash": "<tx_set_hash>",
    "tx_set_proof": [<tx_proof>, <tx_proof>, ...],
    "tx_set_index": <decimal>
  },]
  ["recipient_aggregate": {
    "wallet_signature": "<wallet_signature>",
    "hub_signature": "<hub_signature>",
    "updated_spendings": "<updated_spendings>",
    "updated_gains": "<updated_gains>",
    "tx_set_hash": "<tx_set_hash>",
    "tx_set_proof": [<tx_proof>, <tx_proof>, ...],
    "tx_set_index": <decimal>
  },]
  ["processed": <has the transfer been processed>,]
  ["complete": <is the transfer complete>,]
  ["amount": <decimal>,]
  ["nonce": <nonce of the transfer | decimal>,]
  }

• Cancel a transfer

  XXX transfer/<id>/cancel
  body: {
  TODO: "to be documented"
  }

Swapper

Defines the endpoints for making swaps, and contains the matching engine.

• Swap submission

  PUT swap/
  body: {
  "wallet": {
    "address": "<wallet address without 0x prefix>",
    "token": "<contract address without 0x prefix>"
  },
  "amount": <decimal>,
  "round": <round the transfer is performed>,
  "recipient": {
    "address": "<wallet address without 0x prefix>",
    "token": "<contract address without 0x prefix>"
  },
  "nonce": <nonce of the transfer | decimal>,
  "debit_signature": {
    "value": "<debit_signature>"
  },
  "debit_balance_signature": {
    "value": "<debit_balance_signature>"
  },
  "credit_signature": {
    "value": "<credit_signature>"
  },
  "fulfillment_signature": {
    "value": "<fulfillment_signature>"
  },
  ​
  ["id": <transfer id>,]
  ["time": "<datetime>",]
  ["sender_aggregate": {
    "wallet_signature": "<wallet_signature>",
    "hub_signature": "<hub_signature>",
    "updated_spendings": "<updated_spendings>",
    "updated_gains": "<updated_gains>",
    "tx_set_hash": "<tx_set_hash>",
    "tx_set_proof": [<tx_proof>, <tx_proof>, ...],
    "tx_set_index": <decimal>
  },]
  ["recipient_aggregate": {
    "wallet_signature": "<wallet_signature>",
    "hub_signature": "<hub_signature>",
    "updated_spendings": "<updated_spendings>",
    "updated_gains": "<updated_gains>",
    "tx_set_hash": "<tx_set_hash>",
    "tx_set_proof": [<tx_proof>, <tx_proof>, ...],
    "tx_set_index": <decimal>
  },]
  ["processed": <has the transfer been processed>,]
  ["complete": <is the transfer complete>,]
  ["final_receipt_hashes": "<final_receipt_hashes>",]
  ["final_receipt_index": "<integer>",]
  ["amount_swapped": "<decimal>",]
  }

• Swap finalization

  PUT swap/<id>/finalize
  body: {
  "finalization_signature": {
    "value": "<finalization_signature>"
  }
  }

• Swap freeze

  PUT swap/<id>/freeze
  body: {
  "freezing_signature": {
    "value": "<freezing_signature>"
  }
  }

• Swap cancellation

  PUT swap/<id>/cancel
  body: {
  "sender_cancellation_signature": {
    "value": "<sender_cancellation_signature>"
  },
  "recipient_cancellation_signature": {
    "value": "<recipient_cancellation_signature>"
  }
  }