Server Specification

CashShuffle Server Requirements

General

The server should support TLSv1.2 between the client and server and use the following protobuf specification for messages. It should only receive messages of the Packets type. All messages should have a stop-symbol (⏎) at the end of the message.

Enter the shuffling pool

After the SSL connection is established, the client should send the server a message containing only the verification key of the player and the and desired amount to shuffle in satoshis. This message should be unsigned:

packet {
  from_key {
    key: "verification key value"
  }
  registration: {
   amount: value_in_satoshis
  }
} 

If all is well with the verification key, the server should send back an empty message with a session value and the number in the pool.

packet {
  session: "some session UUID"
  number: number_in_the_pool
} 

If something goes wrong with the handshake, the server should send a blame message and close the connection:

packet {
  message {
    blame{
      reason: INVALIDFORMAT
    } 
 }
} 

Forming the pool

The server should be able to form the pools of a players of fixed size N. Every player who sends a proper entering message should be added to the current pool. After the pool reaches its limit (N) it should broadcast the announcement message to all pool participants:

packet {
  packet {
    phase: ANNOUNCEMENT
    number: number_of_players

  }
}

Broadcast and unicast messages to the players

After the client is registered as a player (it has a session uuid and number in the pool) it switches to game mode and can send/receive messages. There are two types of messages 'broadcast' and 'unicast'. 'broadcast' messages are for everyone in the pool and unicast messages are only from one player to another.

Everytime the server accepts a message from the client it should check:

• if the message has a valid session uuid
• if the message has a valid verification key
• if the message has a valid number
• if the message has a valid 'from_key' field
• if the message has a valid or null 'to_key' field

If the message has a null value for 'to_key' field, it means that it should be broadcast to every pool member If the message does not have a null value for 'to_key' is should be unicast to the specified player.

Blame messages

In the blame phase, players can exclude unreliable players from the pool. If server got n-1 messages from players to exclude a player with verification key excluded_key then the player with this verification key should be excluded. The message should be in the following form:

packet {
  packet {
    session: "session"
    from_key {
      key: "from_key"
    }
    phase: BLAME
    message {
      blame {
        reason: LIAR
        accused {
          key: "excluded_key"
        }
      }
    }
  }
}

Losing the connection

If one of the player closes their connection during a round of cash shuffling, players should begin a new round without the missing player.

The server should send the new round message to remaining participants.

packet {
  session: "some session UUID"
  number: number_in_the_pool
  message:{
    str:"New round"
  }  
} 

Exit from shuffling pool

If everything goes well, all the clients will disconnect when shuffling is complete.