From CubeiaWiki

Contents 1 Introduction 1.1 Wallet Concepts 1.1.1 Entry 1.1.2 Transaction 1.1.3 Account 1.1.4 Session 2 Use Cases 2.1 Sit at table 2.1.1 Notes 2.1.2 API Calls 2.1.3 Firebase Service calls 2.2 Play a hand 2.2.1 Notes 2.2.2 API Calls 2.2.3 Firebase Service calls 2.3 Leave table 2.3.1 Notes 2.3.2 API Calls 2.3.3 Firebase Service calls 2.4 Get more chips on a table 2.4.1 Notes 2.4.2 API Calls 2.4.3 Firebase Service calls 2.5 Buy tournament ticket 2.5.1 Notes 2.5.2 API Calls 2.5.3 Firebase Service calls 2.6 Rebuy tournament 2.6.1 Notes 2.6.2 API Calls 2.6.3 Firebase Service calls 2.7 Tournament is finished 2.7.1 Notes 2.7.2 API Calls 2.7.3 Firebase Service calls 2.8 Purchase physical goods 2.8.1 Notes 2.8.2 API Calls 2.8.3 Firebase Service calls 3 Sequences 3.1 Example of table session (only one hand played)

Introduction

The Wallet Service is a service that wraps the accounting module together with its database and provides a web service suited for service oriented architectures (SOA) or web oriented architectures (WOA).

The User Service uses a specified JSON format over HTTP. XML can also be used by specifying the correct HTTP headers.

The Wallet Service manages its own database and it is not recommended to merge the tables with other tables in the same database since this would break the service isolation pattern.

For documentation of the generic communication scenarios and error handling please see the Cubeia Network Overview document.

Downloads and reference documentation can be found here.

Wallet Concepts

The accounting implementation uses a double-entry bookkeeping system. This means that every transaction within the system will be balanced over at least two accounts.

Below are some of the domain definitions for the wallet. These definitions are modeled and persisted to the database.

Entry

A single monetary transfer to or from one account. An entry will always be associated with a transaction.

Transaction

A transaction is a collection of entries. The sum of the amount over all entries within a transaction must always be zero. This ensures that every monetary transfer is always properly balanced by a debit or credit account.

Account

Account for a specific user. An account can be either session-specific or static. An account is a fairly light weight container for transaction and entry references.

Session

A Session is the same as a temporary account. When creating a session an account will be created with the type set to SessionAccount. Sessions are not modeled explicitly in the database but are contained in session accounts. Sessions and Session Accounts are typically used as place holders for transient events such as playing at a poker table.

Use Cases

The main use cases for an end user (player) have been scoped out as below. The notes do not map to the available protocol but rather to the business logic inside the wallet to give a description of the actions that will be taken.

API Calls are calls done directly to the server using JSON. Firebase Service calls is when you are developing your game within Firebase and use the Wallet Service deployed in Firebase.

A detailed REST API documentation can be found here.

Sit at table

Item	Description
Initial Condition	User is not seated at any table.
Use Case	The user sits down at a table and brings in money to the table.
End Condition	The user is seated with a chipstack at the table. A session has been started in the Wallet.

Notes

Whenever a transaction takes place a session must be started. The session is the context for all transactions that takes places. This use case involves two requests to the wallet. One for starting a table session and one for withdrawing the amount of money to the table.

Starting a table session will create a new account for this specific user and session.

API Calls

• Create Account Request, type = SESSION_ACCOUNT
• Transfer Request, transfer type = CREDIT, operator id needs to be set.

Firebase Service calls

• StartSession
• Withdraw

Play a hand

Item	Description
Initial Condition	User is participating in a game round.
Use Case	The hand is over and the pot is distributed to the players.
End Condition	User has received his part of the pot.

Notes

When the hand is complete the game should send out a transaction request that will adjust the players' balances accordingly. The report should contain each player's win/loss and the rake amount as a separate entry which will use a static account as credit account.

API Calls

ReportTransaction

Firebase Service calls

RoundResult

Leave table

Item	Description
Initial Condition	User has played some hands at a table. A session has been started and used for the duration of play.
Use Case	User deposits the remaining chips back to the operator and closes the session.
End Condition	User has closed the session and left the table. The wallet session account is empty and closed.

Notes

This use case involves two request to the wallet service. The first is for depositing the remaining chip stack to the backing accounting service and the second request is to close the session.

API Calls

Transfer Request, transfer type = DEBIT, operator id needs to be set. Close Account

Firebase Service calls

Deposit EndSession

Get more chips on a table

Item	Description
Initial Condition	User is sitting at a table. A session has been started for the given table.
Use Case	The user brings in more chips to the table.
End Condition	The user has an updated chips stack. The backing account has been debited accordingly.

Notes

Send a withdraw. The session is still open and should not be closed until the user leaves the table.

API Calls

Transfer Request, transfer type = CREDIT, operator id needs to be set.

Firebase Service calls

Withdraw

Buy tournament ticket

Item	Description
Initial Condition	The user decides to buy a tournament ticket.
Use Case	The users clicks on buy ticket in a tournament lobby.
End Condition	The ticket has been purchased and money has been withdrawn from the users backing account.

Notes

For this use case you need to start a session, withdraw the amount. If you want to keep the same session context for rebuys etc. then you should not close the session until the tournament is over.

API Calls

TBD

Firebase Service calls

TBD

Rebuy tournament

Item	Description
Initial Condition	The user has played a tournament. The ticket was purchased in an open session, I.e. The session was not closed after the purchase.
Use Case	The user clicks on rebuy.
End Condition	The money should have been withdrawn from the backing account and transferred to an internal account.

Notes

Send a withdraw and a transfer. The session is still open and should not be closed until the tournament is over.

API Calls

TBD

Firebase Service calls

TBD

Tournament is finished

Item	Description
Initial Condition	A tournament has been played out. A session was started for the tournament and has not been closed.
Use Case	The winnings of the tournament should be divided amongst the winners.
End Condition	The user has been credited his share of the win.

Notes

Send a transfer, a deposit and then close the session.

API Calls

TBD

Firebase Service calls

TBD

Purchase physical goods

Item	Description
Initial Condition	User decides to purchase a single item.
Use Case	User validates purchase and the item is now available and/or shipped to the user.
End Condition	The money has been deducted from the user's backing account.

Notes

Start a session, withdraw, transfer and finally close the account.

API Calls

TBD

Firebase Service calls

TBD

Sequences

This section contains example sequences derived from the use cases above.

Example of table session (only one hand played)

The key aspect with the table session example is that distributed calls to the remote accounting service only occurs at the life boundaries of the session. Calling the remote accounting will in most cases be an expensive operation since the remote accounting service will most likely not be co-localed with the wallet service.