ruby-trade 0.2 → 0.3

data/README.md

@@ -8,10 +8,77 @@ into the market to buy or sell shares.
 
 ## Installation
 
-Just install the gem (not working just yet)
+Just install the gem:
 
     gem install ruby-trade
 
+Mac users: some people are having some issues installing the ZeroMQ libraries
+on a Mac. If you install an older version of ZeroMQ it should work:
+
+    brew install zeromq22
+    gem install ruby-trade
+
+## Mechanics
+
+The mechanics of the market are for the most part like a real stock market. In
+ruby-trade there is only one stock, and everybody buys and sells that stock from
+other players within the market.
+
+### Orders
+
+The only way to buy or sell shares is through orders. The client script sends
+a orders to the market to buy or sell a number of shares at a specified price.
+When you send an order, the server checks to see if your order can be matched
+with any of the other orders and if it can be, it will execute a trade and your
+script will receive a notification.
+
+The server is real-time, there is no time interval between when things happen.
+If your script sends an order, it is sent to the market immediately.
+
+### Matching Example
+
+Here's an example of how the server will attempt to match a new order into the
+market. Suppose here are the existing orders:
+
+* Trader A has a buy order for 5k shares at $9.00
+* Trader B has a sell order for 10k shares at $10.00
+* Trader C has:
+  * a sell order for 2k shares at $10.00 but it was placed after trader B's order
+  * a sell order for 10k shares at $10.50
+  * a buy order for 10k shares at $8.00.
+
+In this case the "best" buy order is trader A's order at $9 because it has the
+highest price (picture yourself in the position of a seller, would you rather
+sell your shares to someone at $9 or at $8?). This best price is called the "bid".
+The best sell order on the other hand is trader B's sell order at $10, and this
+is called the "ask".
+
+Now Trader D comes along and sends a buy order for 15k shares at $12. Here's how
+the server will match up the orders:
+
+1. Trader D will buy 10k shares from trader B at $10.00 (it starts at the best
+   sell price).
+2. Trader D will then buy 2k shares from trader C at $10.00 (it resolves ties at
+   a certain price level using a first-come-first-serve algorithm).
+3. Trader D will finally buy 3k shares from trader C at $10.50. The first two
+   orders at $10.00 will be gone, and trader C's order at $10.50 will be updated
+   to only have 7k shares left.
+
+When this is over, the "bid" will still be $9.00 from trader A's order, but the
+"ask" will have gone up to $10.50 because all the orders at $10.00 are now gone.
+The "last" price (the price that the last trade was at) would be $10.50.
+
+Next, trader E sends a sell order for 10k shares at $8.50. The matching is like
+this:
+
+1. Trader E will sell 5k shares to trader A at $9.00 (the best buy price).
+2. Since there are no more orders left that are greater than or equal to $8.50,
+   trader E's order will enter the market as a sell order for 5k shares at $8.50.
+
+The "bid" gets updated to be $8.00 (for trader C's buy order) and the "ask" gets
+updated to be $8.50 (trader E's new sell order). The "last" will be $9.00.
+
+
 ## Lingo
 
 Before getting started, there are a few definitions that you should know about:
@@ -74,6 +141,21 @@ Here is an example client:
     # Connect to the server
     MyApp.connect_to "127.0.0.1", as: "Jim"
 
+### Hooks
+
+The following hooks are available:
+
+* `on_connect` - Called when the client connects to the server.
+* `on_tick level` - Called whenever something happens in the exchange. `level1`
+  is a hash containing `"bid"`, `"ask"`, and `"last"`.
+* `on_fill order, amount, price` - Called when `order` is filled. `amount` is
+  the amount (usually the size of the order, but will be less if the order was
+  partially filled before), and `price` is the price that it was filled at.
+* `on_partial_fill order, amount, price` - Same as `on_fill`, but this order is
+  still live in the market.
+* `on_dividend amount` - Called when a dividend is received, `amount` is the
+  cash value of the dividend (which will be negative for short positions).
+
 ## Events
 
 ### Dividend

data/examples/stress.rb

@@ -0,0 +1,37 @@
+require 'ruby-trade'
+
+TradeAmount = 20_000
+NumOrders = 2000
+InitialPrice = 10.0
+
+class Slammer
+  include RubyTrade::Client
+  
+  def self.on_connect *args
+    puts "Connected."
+
+    hit_it
+  end
+
+  def self.hit_it
+    @orders = (1..NumOrders).map do
+      buy 100, at: InitialPrice
+    end
+
+    EM.add_timer 1 do
+      @orders.each do |order|
+        order.cancel!
+      end
+
+      EM.add_timer 0.5 do
+        hit_it
+      end
+    end
+  end
+
+  def self.on_tick level1
+    @level1 = level1
+  end
+end
+
+Slammer.connect_to "127.0.0.1", as: "Slammer", ai: true

data/lib/client.rb

@@ -3,12 +3,15 @@ require 'json'
 require 'em-zeromq'
 
 require_relative "order"
+require_relative "../server/common"
 
 DEFAULT_FEED_PORT = 9000
 DEFAULT_ORDER_PORT = 9001
 
 module RubyTrade
   module ConnectionClient
+    include LineCleaner
+
     def self.setup args, parent
       @@username = args[:as]
       @@ai = args[:ai] || false
@@ -25,6 +28,7 @@ module RubyTrade
 
       send_data_f data
 
+      @buffer = ""
       @order_no = 0
       @orders = {}
       @cash, @stock = 0, 0
@@ -83,15 +87,6 @@ module RubyTrade
       send_data "\x02#{data}\x03"
     end
 
-    # Strip off begin/end transmission tokens
-    def clean data
-      if data.length > 2
-        data[1..-2].split("\x03\x02")
-      else
-        []
-      end
-    end
-
     # Called by EM when we receive data
     def receive_data data
       clean(data).each do |msg|
@@ -132,6 +127,9 @@ module RubyTrade
           @connect_triggered = true
           @@parent.on_connect
         end
+      when "dividend"
+        @cash += data["value"]
+        @@parent.on_dividend data["value"]
       end
     end
   end
@@ -142,6 +140,7 @@ module RubyTrade
       def on_tick *args; end
       def on_fill *args; end
       def on_partial_fill *args; end
+      def on_dividend *args; end
 
       # hook so we can call child methods
       def child= child

data/lib/order.rb

@@ -3,7 +3,7 @@ require 'observer'
 class Order
   include Observable
 
-  attr_reader :id, :local_id, :side, :size, :sent_at, :status
+  attr_reader :id, :side, :size, :sent_at, :status
   attr_accessor :price, :status
 
   def initialize id, side, price, size

data/{rubytrade.gemspec → ruby-trade.gemspec}

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "ruby-trade"
-  s.version = "0.2"
+  s.version = "0.3"
   s.date = "2013-11-09"
   s.summary = "A stock market simulation game."
   s.description = ""

data/server/account.rb

@@ -11,11 +11,20 @@ class Account
     @ai = false
   end
 
+  def process_dividend amount
+    value = stock * amount
+
+    @cash += value
+
+    changed
+    notify_observers :dividend, {amount: amount, value: value}
+  end
+
   def update_name name
     if @name != name
       @name = name
       changed
-      notify_observers
+      notify_observers :name_change, name
     end
   end
 

data/server/common.rb

@@ -0,0 +1,22 @@
+module LineCleaner
+  def clean data
+    @buffer ||= ""
+    @buffer += data
+
+    msgs = []
+
+    while @buffer.length > 0
+      next_close = @buffer.index "\x03"
+
+      break if next_close.nil?
+
+      next_piece = @buffer[1...next_close]
+
+      msgs << next_piece
+
+      @buffer = @buffer[(next_close + 1)..-1]
+    end
+
+    msgs
+  end
+end

data/server/exchange.rb

@@ -3,8 +3,10 @@ require_relative 'order-book'
 require_relative 'order'
 require_relative 'server'
 
-STARTING_EQUITY = 0
-STARTING_CASH = 10_000
+StartingEquity = 0
+StartingCash = 10_000
+DividendAmount = 0.25
+DividendFrequency = 600
 
 class Exchange
   def initialize
@@ -14,8 +16,19 @@ class Exchange
     @book = OrderBook.new
   end
 
+  def accounts
+    @accounts.values
+  end
+
+  # Pay dividends to all accounts
+  def pay_dividends
+    @accounts.values.each do |account|
+      account.process_dividend DividendAmount
+    end
+  end
+
   def identify data
-    account = @accounts[data["peer_name"]] || Account.new(data["peer_name"], data["name"], STARTING_EQUITY, STARTING_CASH)
+    account = @accounts[data["peer_name"]] || Account.new(data["peer_name"], data["name"], StartingEquity, StartingCash)
 
     account.ai = data["ai"]
     account.update_name data["name"]

data/server/public/app.js

@@ -26,6 +26,13 @@ $(function () {
       $(".ask").html(data.level1.ask.toFixed(2));
       $(".last").html(data.level1.last.toFixed(2));
       break;
+    case "accounts":
+      $("#leaderboard tbody").html(
+        $.map(data.accounts, function (obj) {
+          return "<tr><td>" + obj.join("</td><td>") + "</td></tr>";
+        }).join("")
+      );
+      break;
     }
   };
 

data/server/public/index.html

@@ -37,11 +37,19 @@
       </div>
       </div>
       <div class = "row-fluid">
-        <div class = "col-md-6">
-          <div class = "pull-right">
-            <label>Last</label>
-            <div class = "last">0.00</div>
-          </div>
+        <div class = "col-md-2">&nbsp;</div>
+        <div class = "col-md-8">
+          <table class = "table table-bordered table-striped" id = "leaderboard">
+            <thead>
+              <tr>
+                <th>Name</th>
+                <th>Value</th>
+                <th>Cash</th>
+                <th>Stock</th>
+              </tr>
+            </thead>
+            <tbody></tbody>
+          </table>
         </div>
       </div>
     </div>

data/server/server.rb

@@ -3,14 +3,36 @@ require 'json'
 
 require_relative 'exchange'
 require_relative 'web_server'
+require_relative 'common'
+
+AccountUpdateFrequency = 30
 
 class OrderServer < EM::Connection
+  include LineCleaner
+
   def self.setup parent
     @@exchange = Exchange.new
     @@parent = parent
+
+    EM.add_periodic_timer DividendFrequency do
+      @@exchange.pay_dividends
+    end
+
+    EM.add_periodic_timer AccountUpdateFrequency do
+      level1 = @@exchange.level1
+      Webapp.update_accounts(@@exchange.accounts.select { |account|
+        #not account.ai?
+        true
+      }.map { |account|
+        [account.name, account.net_value(level1[:last]), account.stock, account.cash]
+      }.sort_by { |row|
+        row[3]
+      })
+    end
   end
 
   def post_init
+    @buffer = ""
     @my_orders = {}
   end
 
@@ -52,20 +74,17 @@ class OrderServer < EM::Connection
         local_id: order.local_id
       }.to_json)
       @@parent.tick @@exchange
+    when :dividend
+      send_data_f({
+        action: "dividend",
+        value: args[0][:value]
+      }.to_json)
     end
   end
 
   def send_data_f data
     send_data "\x02#{data}\x03"
   end
-  
-  def clean data
-    if data.length > 2
-      data[1..-2].split("\x03\x02")
-    else
-      []
-    end
-  end
 
   def handle_message data
     case data["action"]
@@ -73,15 +92,17 @@ class OrderServer < EM::Connection
       _, ip = Socket.unpack_sockaddr_in get_peername
       data["peer_name"] = ip
       puts "User #{data['name']}@#{data["peer_name"]} connected."
+
+      @account.delete_observer self if @account
       @account = @@exchange.identify data
+      @account.add_observer self
+
       send_data_f({
         action: "account_update",
         cash: @account.cash,
         stock: @account.stock
       }.to_json)
     when "new_order"
-      puts "new order"
-
       error, order = @@exchange.new_order @account, data
 
       if error
@@ -102,14 +123,13 @@ class OrderServer < EM::Connection
           price: order.price
         }.to_json)
 
-        @my_orders[order.id] = order
+        @my_orders[order.local_id] = order
         @@exchange.send_order order
         @@parent.tick @@exchange
       end
     when "cancel_order"
       order = @my_orders[data["id"]]
       if order
-        puts "cancelling #{data["id"]}"
         @@exchange.cancel_order order
         @@parent.tick @@exchange
       else
@@ -127,15 +147,13 @@ end
 
 class Server
   def tick exchange
-    puts "sending tick"
     msg = {
       action: "tick",
       level1: exchange.level1
     }
     Webapp.level1_update exchange.level1
 
-    puts msg.inspect
-    puts @feed_socket.send_msg(msg.to_json)
+    @feed_socket.send_msg(msg.to_json)
   end
 
   def start args = {}
@@ -145,9 +163,9 @@ class Server
 
     @context = EM::ZeroMQ::Context.new 1
 
-    OrderServer.setup self
-
     EM.run do
+      OrderServer.setup self
+
       puts "Listening for clients on #{order_port}"
       EM.start_server "0.0.0.0", order_port, OrderServer
 

data/server/test/test_common.rb

@@ -0,0 +1,76 @@
+require_relative "../common"
+
+class Cleaner
+  include LineCleaner
+end
+
+describe LineCleaner do
+  before :each do
+    @cleaner = Cleaner.new
+  end
+
+  it "should work with a basic message" do
+    res = @cleaner.clean "\x02this is a message\x03"
+
+    res.length.should == 1
+    res[0].should == "this is a message"
+  end
+
+  it "should split multiple messages" do
+    res = @cleaner.clean "\x02this is a message\x03\x02this is another message\x03\x02this is a third message\x03"
+
+    res.length.should == 3
+    res[0].should == "this is a message"
+    res[1].should == "this is another message"
+    res[2].should == "this is a third message"
+  end
+
+  it "should carry through different transmissions" do
+    res = @cleaner.clean "\x02this is a message\x03\x02this is a second"
+
+    res.length.should == 1
+    res[0].should == "this is a message"
+
+    res = @cleaner.clean " message that has been chopped in half\x03\x02this is a final message\x03"
+
+    res.length.should == 2
+    res[0].should == "this is a second message that has been chopped in half"
+    res[1].should == "this is a final message"
+  end
+
+  it "should buffer a big message" do
+    res = @cleaner.clean "\x02this is a message that does not"
+
+    res.length.should == 0
+
+    res = @cleaner.clean " end until later\x03"
+
+    res.length.should == 1
+    res[0].should == "this is a message that does not end until later"
+  end
+
+  it "should not split on end of string" do
+    res = @cleaner.clean "\x02this is a message with a split at the end\x03\x02"
+
+    res.length.should == 1
+    res[0].should == "this is a message with a split at the end"
+
+    res = @cleaner.clean "and here is the end\x03"
+
+    res.length.should == 1
+    res[0].should == "and here is the end"
+  end
+
+  it "should not split at the start of the string" do
+    res = @cleaner.clean "\x02this is the message with the split at the start"
+
+    res.length.should == 0
+
+    res = @cleaner.clean "\x03\x02and here is the second bit.\x03"
+
+    res.length.should == 2
+    res[0].should == "this is the message with the split at the start"
+    res[1].should == "and here is the second bit."
+  end
+end
+

data/server/web_server.rb

@@ -2,14 +2,13 @@ require "sinatra/base"
 require "sinatra-websocket"
 require "thin"
 require "rack"
-require "rack/sockjs"
 require 'observer'
 require 'json'
 
 class Level1
   include Observable
 
-  attr_reader :level1
+  attr_reader :level1, :accounts
 
   def initialize
     @level1 = {
@@ -24,6 +23,12 @@ class Level1
     changed
     notify_observers :level1, level1
   end
+
+  def update_accounts accounts
+    @accounts = accounts
+    changed
+    notify_observers :accounts, accounts
+  end
 end
 
 class SocketWrapper
@@ -44,6 +49,11 @@ class SocketWrapper
         action: action,
         level1: data[0]
       }.to_json)
+    when :accounts
+      @socket.send({
+        action: action,
+        accounts: data[0]
+      }.to_json)
     end
   end
 end
@@ -88,6 +98,10 @@ class Webapp < Sinatra::Base
   def self.level1_update level1
     @@level1.update_level1 level1
   end
+
+  def self.update_accounts accounts
+    @@level1.update_accounts accounts
+  end
 end
 
 def run_webserver opts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-trade
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
   prerelease: 
 platform: ruby
 authors:
@@ -21,16 +21,18 @@ files:
 - README.md
 - examples/market_maker.rb
 - examples/slammer.rb
+- examples/stress.rb
 - lib/Gemfile
 - lib/Gemfile.lock
 - lib/client.rb
 - lib/order.rb
 - lib/ruby-trade.rb
-- rubytrade.gemspec
+- ruby-trade.gemspec
 - server/Gemfile
 - server/Gemfile.lock
 - server/account.rb
 - server/app.rb
+- server/common.rb
 - server/exchange.rb
 - server/order-book.rb
 - server/order.rb
@@ -159,6 +161,7 @@ files:
 - server/public/jquery-2.0.3.min.js
 - server/public/sockjs-0.2.1.min.js
 - server/server.rb
+- server/test/test_common.rb
 - server/test/test_order_book.rb
 - server/web_server.rb
 homepage: