Prime Specification

Functional

User

• sign up with e-mail activation and TOS acceptance
• sign in / out
• password reset
  • reset link valid for 24h or one use whatever comes first

Settings

• change password
• change email
• configure two factor authentication
• on/off API
• reset API key
• configure email notifications (TODO: details)
• complete account removal (privacy feature, TODO: is it viable? what about left funds and common history?)
• all changes require second method authentication (email confirmation or OTP)

Dashboard

• change market; market is a pair of currencies, i.e. USD/BTC, PLN/BTC

Order book

• live chart
• live table

Last trades

• live chart
• live table

Account

• Balances for the current market
• History
  • every balance change must have a corresponding transaction
• Open orders
  • cancel order

Deposit

Bitcoins

• generation of personal input address
  • internal maintenance of user input addresses (every user has a list of input addresses)
• displaying address and instructions to the user
  • funding user balance with incoming bitcoins
    • create entry in account history, remember bitcoin tx id

Fiat

• internal (LAN-only) API for custom scripts to bump fiat balance
  • create entry in account history, remember fiat tx id

Withdraw

Bitcoins

• edit bitcoin output address
• confirm with e-mail link or Google Authenticator OTP
• displaying form to send bitcoins
  • amount
  • instructions and fee information
  • send button with summary and confirmation
• mechanism to actually send bitcoins
  • create entry in account history, remember bitcoin tx id

Fiat

• edit bank account details
• confirm with e-mail link or Google Authenticator OTP
• display form to send fiat
  • amount
  • instructions
  • send button with summary and confirmation
• add FiatWithdrawal entry to the list of pending fiat withdrawal requests
  • publish pending fiat withdrawals in internal API
  • accept request to mark specific FiatWithdrawal as fulfilled
    • create entry in account history, remember fiat tx id(?)

Buy/Sell

• Display "Please be aware this is only approximation. Order book can change every second."
• Validate order value denominated in fiat is high enough
  • This is to prevent order and transaction spam/DOS

Buy bitcoins

• Instant buy
  • "I want to buy [____] BTC instantly."
  • "You will spend about ____ USD and receive ____ BTC after fee. Average BTC price will be about ____ USD."
  • Technically equals to submitting buy order with infinite price.
• Buy with price limit
  • "I want to buy [____] BTC at price [____] USD/BTC."
  • "You will spend about ____ USD and receive ____ BTC after fee. Average BTC price will be about ____ USD."
  • "You need at least ____ USD at hand to submit this order."
  • Validate user has enough funds to submit the order (assuming worst case scenario)
  • Block funds
  • Match with existing orders
  • Smart defaults: max BTC user can buy, market price

Sell bitcoins

• Instant sell
  • "I want to sell [____] BTC instantly."
  • "You will receive about ____ USD after fee. Average BTC price will be about ____ USD."
  • Technically equals to submitting sell order with 0 price.
• Sell with price limit
  • "I want to sell [____] BTC at price [____] USD/BTC."
  • "You will receive about ____ USD after fee. Average BTC price will be about ____ USD."
  • Validate user has enough funds to submit the order
  • Block funds
  • Match with existing orders
  • Smart defaults: all BTC, market price

Fees

Transaction fee

Percentage and minimum fee denominated in fiat, like 0.6% min 0.01 USD. Taken from both sides of transaction from the output amount.

Bitcoin withdrawal fee

Percentage and minimum fee denominated in bitcoin, like 0% min 0.0005 BTC.

Fiat withdrawal fee

Percentage and minimum fee denominated in fiat, like 0% min 2 USD.

Public API

Ticker

TODO: design

Trades

As explained on bitcoincharts.

Order Book

As explained on bitcoincharts.

Admin panel

Dashboard

• To be decided what goes on a dashboard

Financial

• Total funds on the exchange
  • Total funds accumulated on the exchange for each fiat (calculated from a database)
  • Total funds accumulated on the exchange for each cryptocurrency (calculated from a database)
• Number of buy and sell orders
• Number and volume of transactions

How wallets

• Number and percentage of funds in a hot wallet (actual value taken from a bitcoind) for each cryptocurrency

Users

• Total number of registered users
• Export emails.csv (i.e. for mass mailing via external software)
• Generate comprehensive report users.csv
  • designed to be open in a spreadsheat (Excel, Calc, etc.)
  • one user per line, fields:
    • e-mail hash, total balance BTC, total balance USD, ..., paid fees, number of transactions, transaction volume, sing-up date, sing-up IP, last sign-in date, last sign-in IP, number of sign-ins, number of open orders
• Search user by e-mail, username, name, or e-mail hash (to look up users from the report)
  • View user details
  • Deactivate / Activate
  • Impersonate

Performance

• Hot
  • Number of users online
  • Number of transactions in last minute
  • Job queue length
  • Pending fiat withdrawals (number, volume and the longest waiting)
• Historical
  • Number of transactions per hour chart (TODO: necessary in v1.0?)
• Settings
  • Min. order value denominated in primary currency for each market (i.e. denominated in USD for USD/BTC market)
  • Limit of requests per minute for signed-in user

Security

• Shutdown the service
• Rollback to the point in time (TODO: define details)
  • "Rollback wreaks havoc, causes some users and exchange to lose money and can be illegal in your jurisdiction. Rollback is irreversible. Rollback is a bad idea 99.999% of the time. Proceed only if you fully understand the consequences!!!"
  • Rollback should not be available through the web app, only as a command line tool

Non functional

Supported browsers

Prime example fronted is tested on the latest versions of:

• Chrome
• Firefox
• Internet Explorer 9
• Opera

There is nothing that prevents you from creating a Prime fronted that supports older browsers (see design).

Correct use of HTTP protocol

• Semantic use of HTTP methods GET, POST, PATCH, DELETE
• Correct HTTP status codes

Take advantage of HTML5

• Use HTML5 to the full extent possible
• Aim at HTML5 validity

Performance

• Disallow small value orders, see Performance settings in admin panel
  • Prevents order and transaction spam. Spammed order book is slow to match. Spammed transaction history can become to large to handle.
• Limit requests per minute for a signed-in user
  • Further requests will be rejected with 429 Too Many Requests
  • Does not insert logs into a database. Works buy incrementing user request_counter in scope of minute stored in request_counter_at. When current minute is larger than request_counter_at, it zeroes out request_counter and sets request_counter_at to the current minute. This isn't 100% accurate but this is acceptable.

Limitation of v1.0

• While Prime is designed from ground up to support multiple cryptocurrencies, the first version will deliver integration with bitcoin only.
• No support for multiple hot and cold wallets. Only one pair of hot/cold wallet will be supported.

Open questions

• Checking whether actual crypto and fiat balances cover values from a database (prevent fractional reserve)? How to do it correctly (i.e. delays in transfers, etc)?