Prime Specification
Contents
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
- funding user balance with incoming bitcoins
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
Withdrawal requests
Pending
- Total fiat funds pending for withdrawal
- FIFO list of pending fiat withdrawals
- time waiting, name, address, IBAN, amount, [insert bank withdrawal transaction id here] and click [MARK AS FULFILLED] button, [CANCEL] button
Other
- list of fulfilled and cancelled withdrawals, by date of fulfillment
Financial & Fees
- Stats
- 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
- Total funds on the exchange
- Fee settings
Hot 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
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.
Requirements
- commandline tools: pg_dump, openssl (to use built-in db backups)
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
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)?
Twitter
Telegram
