stellar_core_commander 0.0.11 → 0.0.12

data/lib/stellar_core_commander/operation_builder.rb

@@ -3,7 +3,7 @@ module StellarCoreCommander
   class OperationBuilder
     include Contracts
 
-    Currency = Or[
+    Asset = Or[
       [String, Symbol],
       :native,
     ]
@@ -13,25 +13,38 @@ module StellarCoreCommander
     ]
 
     OfferCurrencies = Or[
-      {sell:Currency, for: Currency},
-      {buy:Currency, with: Currency},
+      {sell:Asset, for: Asset},
+      {buy:Asset, with: Asset},
     ]
 
-    ThresholdByte = And[Num, lambda{|n| (0..255).include? n}]
+    Byte = And[Num, lambda{|n| (0..255).include? n}]
+    ThresholdByte = Byte
+    MasterWeightByte = Byte
 
     Thresholds = {
-      low:           ThresholdByte,
-      medium:        ThresholdByte,
-      high:          ThresholdByte,
-      master_weight: ThresholdByte
+      low:    Maybe[ThresholdByte],
+      medium: Maybe[ThresholdByte],
+      high:   Maybe[ThresholdByte],
     }
 
+    SetOptionsArgs = {
+      inflation_dest: Maybe[Symbol],
+      clear_flags:    Maybe[ArrayOf[Symbol]],
+      set_flags:      Maybe[ArrayOf[Symbol]],
+      thresholds:     Maybe[Thresholds],
+      master_weight:  Maybe[MasterWeightByte],
+      home_domain:    Maybe[String],
+      signer:         Maybe[Stellar::Signer],
+    }
+
+    MAX_LIMIT= BigDecimal.new((2**63)-1) / Stellar::ONE
+
     Contract Transactor => Any
     def initialize(transactor)
       @transactor = transactor
     end
 
-    Contract Symbol, Symbol, Amount, Or[{}, {path: ArrayOf[Currency], with:Amount}] => Any
+    Contract Symbol, Symbol, Amount, Or[{}, {path: ArrayOf[Asset], with:Amount}] => Any
     def payment(from, to, amount, options={})
       from = get_account from
       to   = get_account to
@@ -45,7 +58,7 @@ module StellarCoreCommander
 
       tx =  if options[:with]
               attrs[:with] = normalize_amount(options[:with])
-              attrs[:path] = options[:path].map{|p| make_currency p}
+              attrs[:path] = options[:path].map{|p| make_asset p}
               Stellar::Transaction.path_payment(attrs)
             else
               Stellar::Transaction.payment(attrs)
@@ -55,7 +68,7 @@ module StellarCoreCommander
     end
 
     Contract Symbol, Symbol, Num => Any
-    def create_account(account, funder=:master, starting_balance=1000_0000000)
+    def create_account(account, funder=:master, starting_balance=1000)
       account = get_account account
       funder  = get_account funder
 
@@ -69,7 +82,7 @@ module StellarCoreCommander
 
     Contract Symbol, Symbol, String => Any
     def trust(account, issuer, code)
-      change_trust account, issuer, code, (2**63)-1
+      change_trust account, issuer, code, MAX_LIMIT
     end
 
     Contract Symbol, Symbol, String, Num => Any
@@ -79,14 +92,14 @@ module StellarCoreCommander
       Stellar::Transaction.change_trust({
         account:  account,
         sequence: next_sequence(account),
-        line:     make_currency([code, issuer]),
+        line:     make_asset([code, issuer]),
         limit:    limit
       }).to_envelope(account)
     end
 
     Contract Symbol, Symbol, String, Bool => Any
     def allow_trust(account, trustor, code, authorize=true)
-      currency = make_currency([code, account])
+      asset = make_asset([code, account])
       account = get_account account
       trustor = get_account trustor
 
@@ -94,7 +107,7 @@ module StellarCoreCommander
       Stellar::Transaction.allow_trust({
         account:  account,
         sequence: next_sequence(account),
-        currency: currency,
+        asset: asset,
         trustor:  trustor,
         authorize: authorize,
       }).to_envelope(account)
@@ -110,11 +123,11 @@ module StellarCoreCommander
       account = get_account account
 
       if currencies.has_key?(:sell)
-        taker_pays = make_currency currencies[:for]
-        taker_gets = make_currency currencies[:sell]
+        buying = make_asset currencies[:for]
+        selling = make_asset currencies[:sell]
       else
-        taker_pays = make_currency currencies[:buy]
-        taker_gets = make_currency currencies[:with]
+        buying = make_asset currencies[:buy]
+        selling = make_asset currencies[:with]
         price = 1 / price
         amount = (amount * price).floor
       end
@@ -122,8 +135,8 @@ module StellarCoreCommander
       Stellar::Transaction.manage_offer({
         account:  account,
         sequence: next_sequence(account),
-        taker_gets: taker_gets,
-        taker_pays: taker_pays,
+        selling: selling,
+        buying: buying,
         amount: amount,
         price: price,
       }).to_envelope(account)
@@ -134,11 +147,11 @@ module StellarCoreCommander
       account = get_account account
 
       if currencies.has_key?(:sell)
-        taker_pays = make_currency currencies[:for]
-        taker_gets = make_currency currencies[:sell]
+        buying = make_asset currencies[:for]
+        selling = make_asset currencies[:sell]
       else
-        taker_pays = make_currency currencies[:buy]
-        taker_gets = make_currency currencies[:with]
+        buying = make_asset currencies[:buy]
+        selling = make_asset currencies[:with]
         price = 1 / price
         amount = (amount * price).floor
       end
@@ -146,60 +159,103 @@ module StellarCoreCommander
       Stellar::Transaction.create_passive_offer({
         account:  account,
         sequence: next_sequence(account),
-        taker_gets: taker_gets,
-        taker_pays: taker_pays,
+        selling: selling,
+        buying: buying,
         amount: amount,
         price: price,
       }).to_envelope(account)
     end
 
-
-    Contract Symbol => Any
-    def require_trust_auth(account)
-      set_flags account, [:auth_required_flag]
-    end
-
-    Contract Symbol, ArrayOf[Symbol] => Any
-    def set_flags(account, flags)
+    Contract Symbol, SetOptionsArgs => Any
+    def set_options(account, args)
       account = get_account account
 
-      tx = Stellar::Transaction.set_options({
+      params = {
         account:  account,
         sequence: next_sequence(account),
-        set:      make_account_flags(flags),
-      })
+      }
+
+      if args[:inflation_dest].present?
+        params[:inflation_dest] = get_account args[:inflation_dest]
+      end
 
+      if args[:set_flags].present?
+        params[:set] = make_account_flags(args[:set_flags])
+      end
+
+      if args[:clear_flags].present?
+        params[:clear] = make_account_flags(args[:clear_flags])
+      end
+
+      if args[:master_weight].present?
+        params[:master_weight] = args[:master_weight]
+      end
+
+      if args[:thresholds].present?
+        params[:low_threshold] = args[:thresholds][:low]
+        params[:med_threshold] = args[:thresholds][:medium]
+        params[:high_threshold] = args[:thresholds][:high]
+      end
+
+      if args[:home_domain].present?
+        params[:home_domain] = args[:home_domain]
+      end
+
+      if args[:signer].present?
+        params[:signer] = args[:signer]
+      end
+
+      tx = Stellar::Transaction.set_options(params)
       tx.to_envelope(account)
     end
 
 
+    Contract Symbol, ArrayOf[Symbol] => Any
+    def set_flags(account, flags)
+      set_options account, set_flags: flags
+    end
+
+    Contract Symbol, ArrayOf[Symbol] => Any
+    def clear_flags(account, flags)
+      set_options account, clear_flags: flags
+    end
+
+    Contract Symbol => Any
+    def require_trust_auth(account)
+      set_flags account, [:auth_required_flag]
+    end
+
     Contract Symbol, Stellar::KeyPair, Num => Any
     def add_signer(account, key, weight)
-      account = get_account account
-
-      tx = Stellar::Transaction.set_options({
-        account:  account,
-        sequence: next_sequence(account),
-        signer:   Stellar::Signer.new({
-          pub_key: key.public_key,
-          weight: weight
-        }),
+      set_options account, signer: Stellar::Signer.new({
+        pub_key: key.public_key,
+        weight: weight
       })
+    end
 
-      tx.to_envelope(account)
+    Contract Symbol, Stellar::KeyPair => Any
+    def remove_signer(account, key)
+      add_signer account, key, 0
+    end
+
+    Contract(Symbol, MasterWeightByte => Any)
+    def set_master_signer_weight(account, weight)
+      set_options account, master_weight: weight
     end
 
     Contract(Symbol, Thresholds => Any)
     def set_thresholds(account, thresholds)
-      account = get_account account
+      set_options account, thresholds: thresholds
+    end
 
-      tx = Stellar::Transaction.set_options({
-        account:    account,
-        sequence:   next_sequence(account),
-        thresholds: make_thresholds_word(thresholds),
-      })
+    Contract(Symbol, Symbol => Any)
+    def set_inflation_dest(account, destination)
+      set_options account, inflation_dest: destination
+    end
 
-      tx.to_envelope(account)
+    Contract(Symbol, String => Any)
+    def set_home_domain(account, domain)
+      set_options account, home_domain: domain
     end
 
     Contract Symbol, Symbol => Any
@@ -216,13 +272,26 @@ module StellarCoreCommander
       tx.to_envelope(account)
     end
 
+
+    Contract None => Any
+    def inflation(account=:master)
+      account = get_account account
+
+      tx = Stellar::Transaction.inflation({
+        account:     account,
+        sequence:    next_sequence(account),
+      })
+
+      tx.to_envelope(account)
+    end
+
     private
 
     delegate :get_account, to: :@transactor
     delegate :next_sequence, to: :@transactor
 
-    Contract Currency => Or[[Symbol, String, Stellar::KeyPair], [:native]]
-    def make_currency(input)
+    Contract Asset => Or[[Symbol, String, Stellar::KeyPair], [:native]]
+    def make_asset(input)
       if input == :native
         return [:native]
       end
@@ -230,7 +299,7 @@ module StellarCoreCommander
       code, issuer = *input
       issuer = get_account issuer
 
-      [:alphanum, code, issuer]
+      [:alphanum4, code, issuer]
     end
 
     def make_account_flags(flags=nil)
@@ -247,7 +316,7 @@ module StellarCoreCommander
     def normalize_amount(amount)
       return amount if amount.first == :native
 
-      amount = [:alphanum] + amount
+      amount = [:alphanum4] + amount
       amount[2] = get_account(amount[2]) # translate issuer to account
 
       amount

data/lib/stellar_core_commander/process.rb

@@ -1,8 +1,22 @@
 module StellarCoreCommander
 
+  class UnexpectedDifference < StandardError
+    def initialize(kind, x, y)
+      @kind = kind
+      @x = x
+      @y = y
+    end
+    def message
+      "Unexpected difference in #{@kind}: #{@x} != #{@y}"
+    end
+  end
+
   class Process
     include Contracts
 
+    class Crash < StandardError ; end
+    class AlreadyRunning < StandardError ; end
+
     attr_reader :transactor
     attr_reader :working_dir
     attr_reader :name
@@ -10,40 +24,94 @@ module StellarCoreCommander
     attr_reader :identity
     attr_reader :server
     attr_accessor :unverified
-    attr_reader :threshold
     attr_reader :host
+    attr_reader :atlas
+    attr_reader :atlas_interval
+    attr_reader :network_passphrase
 
     DEFAULT_HOST = '127.0.0.1'
 
+    SPECIAL_PEERS = {
+      :testnet1 => {
+        :dns => "core-testnet1.stellar.org",
+        :key => "GDKXE2OZMJIPOSLNA6N6F2BVCI3O777I2OOC4BV7VOYUEHYX7RTRYA7Y",
+        :name => "core-testnet-001",
+        :get => "wget -q https://s3-eu-west-1.amazonaws.com/history.stellar.org/prd/core-testnet/%s/{0} -O {1}"
+      },
+      :testnet2 => {
+        :dns => "core-testnet2.stellar.org",
+        :key => "GCUCJTIYXSOXKBSNFGNFWW5MUQ54HKRPGJUTQFJ5RQXZXNOLNXYDHRAP",
+        :name => "core-testnet-002",
+        :get => "wget -q https://s3-eu-west-1.amazonaws.com/history.stellar.org/prd/core-testnet/%s/{0} -O {1}"
+      },
+      :testnet3 => {
+        :dns => "core-testnet3.stellar.org",
+        :key => "GC2V2EFSXN6SQTWVYA5EPJPBWWIMSD2XQNKUOHGEKB535AQE2I6IXV2Z",
+        :name => "core-testnet-003",
+        :get => "wget -q https://s3-eu-west-1.amazonaws.com/history.stellar.org/prd/core-testnet/%s/{0} -O {1}"
+      }
+    }
+
     Contract({
-      transactor:   Transactor,
-      working_dir:  String,
-      name:         Symbol,
-      base_port:    Num,
-      identity:     Stellar::KeyPair,
-      quorum:       ArrayOf[Symbol],
-      threshold:    Num,
-      manual_close: Or[Bool, nil],
-      host:         Or[String, nil]
+      transactor:          Transactor,
+      working_dir:         String,
+      name:                Symbol,
+      base_port:           Num,
+      identity:            Stellar::KeyPair,
+      quorum:              ArrayOf[Symbol],
+      peers:               Maybe[ArrayOf[Symbol]],
+      manual_close:        Maybe[Bool],
+      await_sync:          Maybe[Bool],
+      accelerate_time:     Maybe[Bool],
+      catchup_complete:    Maybe[Bool],
+      forcescp:            Maybe[Bool],
+      validate:            Maybe[Bool],
+      host:                Maybe[String],
+      atlas:               Maybe[String],
+      atlas_interval:      Num,
+      use_s3:              Bool,
+      s3_history_prefix:   String,
+      s3_history_region:   String,
+      database_url:        Maybe[String],
+      keep_database:       Maybe[Bool],
+      debug:               Maybe[Bool],
+      network_passphrase:  Maybe[String],
     } => Any)
     def initialize(params)
       #config
-      @transactor   = params[:transactor]
-      @working_dir  = params[:working_dir]
-      @name         = params[:name]
-      @base_port    = params[:base_port]
-      @identity     = params[:identity]
-      @quorum       = params[:quorum]
-      @threshold    = params[:threshold]
-      @manual_close = params[:manual_close] || false
-      @host         = params[:host]
+      @transactor         = params[:transactor]
+      @working_dir        = params[:working_dir]
+      @name               = params[:name]
+      @base_port          = params[:base_port]
+      @identity           = params[:identity]
+      @quorum             = params[:quorum]
+      @peers              = params[:peers] || params[:quorum]
+      @manual_close       = params[:manual_close] || false
+      @await_sync         = params.fetch(:await_sync, true)
+      @accelerate_time    = params[:accelerate_time] || false
+      @catchup_complete   = params[:catchup_complete] || false
+      @forcescp           = params.fetch(:forcescp, true)
+      @validate           = params.fetch(:validate, true)
+      @host               = params[:host]
+      @atlas              = params[:atlas]
+      @atlas_interval     = params[:atlas_interval]
+      @use_s3             = params[:use_s3]
+      @s3_history_region  = params[:s3_history_region]
+      @s3_history_prefix  = params[:s3_history_prefix]
+      @database_url       = params[:database_url]
+      @keep_database      = params[:keep_database]
+      @debug              = params[:debug]
+      @network_passphrase = params[:network_passphrase] || Stellar::Networks::TESTNET
 
       # state
       @unverified   = []
 
-
       if not @quorum.include? @name
-        @quorum << @name
+        @quorum = @quorum + [@name]
+      end
+
+      if not @peers.include? @name
+        @peers = @peers + [@name]
       end
 
       @server = Faraday.new(url: "http://#{hostname}:#{http_port}") do |conn|
@@ -52,16 +120,42 @@ module StellarCoreCommander
       end
     end
 
+    Contract None => Bool
+    def has_special_peers?
+      @peers.any? {|q| SPECIAL_PEERS.has_key? q}
+    end
+
+    Contract ArrayOf[Symbol], Symbol, Bool, Proc => ArrayOf[String]
+    def node_map_or_special_field(nodes, field, include_self)
+      specials = nodes.select {|q| SPECIAL_PEERS.has_key? q}
+      if specials.empty?
+        (nodes.map do |q|
+          if q != @name or include_self
+            yield q
+          end
+        end).compact
+      else
+        specials.map {|q| SPECIAL_PEERS[q][field]}
+      end
+    end
+
     Contract None => ArrayOf[String]
     def quorum
-      @quorum.map do |q|
+      node_map_or_special_field @quorum, :key, @validate do |q|
         @transactor.get_process(q).identity.address
       end
     end
 
     Contract None => ArrayOf[String]
-    def peers
-      @quorum.map do |q|
+    def peer_names
+      node_map_or_special_field @peers, :name, true do |q|
+        q.to_s
+      end
+    end
+
+    Contract None => ArrayOf[String]
+    def peer_connections
+      node_map_or_special_field @peers, :dns, false do |q|
         p = @transactor.get_process(q)
         "#{p.hostname}:#{p.peer_port}"
       end
@@ -72,32 +166,73 @@ module StellarCoreCommander
       2
     end
 
-    Contract None => Any
-    def rm_working_dir
-      FileUtils.rm_rf working_dir
-    end
-
     Contract None => String
     def idname
       "#{@name}-#{@base_port}-#{@identity.address[0..5]}"
     end
 
-    Contract None => Any
-    def wait_for_ready
-      loop do
+    Contract None => String
+    def database_url
+      if @database_url.present?
+        @database_url.strip
+      else
+        default_database_url
+      end
+    end
 
-        response = server.get("/info") rescue false
+    Contract None => URI::Generic
+    def database_uri
+      URI.parse(database_url)
+    end
 
-        if response
-          body = ActiveSupport::JSON.decode(response.body)
+    Contract None => Maybe[String]
+    def database_host
+      database_uri.host
+    end
 
-          state = body["info"]["state"]
-          $stderr.puts "state: #{state}"
-          break if state == "Synced!"
-        end
+    Contract None => String
+    def database_name
+      database_uri.path[1..-1]
+    end
+
+    Contract None => Sequel::Database
+    def database
+      @database ||= Sequel.connect(database_url)
+    end
+
+    Contract None => Maybe[String]
+    def database_user
+      database_uri.user
+    end
 
-        $stderr.puts "waiting until stellar-core #{idname} is synced"
-        sleep 1
+    Contract None => Maybe[String]
+    def database_password
+      database_uri.password
+    end
+
+    Contract None => String
+    def database_port
+      database_uri.port || "5432"
+    end
+
+    Contract None => String
+    def dsn
+      base = "postgresql://dbname=#{database_name} "
+      base << " user=#{database_user}" if database_user.present?
+      base << " password=#{database_password}" if database_password.present?
+      base << " host=#{database_host} port=#{database_port}" if database_host.present?
+
+      base
+    end
+
+    Contract None => Any
+    def wait_for_ready
+      Timeout.timeout(sync_timeout) do
+        loop do
+          break if synced?
+          $stderr.puts "waiting until stellar-core #{idname} is synced (state: #{info_field 'state'}, quorum heard: #{scp_quorum_heard})"
+          sleep 1
+        end
       end
     end
 
@@ -134,6 +269,45 @@ module StellarCoreCommander
       true
     end
 
+    Contract Num, Symbol => Any
+    def catchup(ledger, mode)
+      server.get("/catchup?ledger=#{ledger}&mode=#{mode}")
+    end
+
+    Contract None => Hash
+    def info
+      response = server.get("/info")
+      body = ActiveSupport::JSON.decode(response.body)
+      body["info"]
+    rescue
+      {}
+    end
+
+    Contract String => Any
+    def info_field(k)
+      i = info
+      i[k]
+    rescue
+      false
+    end
+
+    Contract None => Bool
+    def synced?
+      (info_field "state") == "Synced!"
+    end
+
+    Contract None => Num
+    def ledger_num
+      (info_field "ledger")["num"]
+    rescue
+      0
+    end
+
+    Contract None => Bool
+    def await_sync?
+      @await_sync
+    end
+
     Contract None => Hash
     def metrics
       response = server.get("/metrics")
@@ -143,13 +317,111 @@ module StellarCoreCommander
       {}
     end
 
-    Contract None => Num
-    def scp_ballots_prepared
-      metrics["scp.ballot.prepare"]["count"]
+    Contract String => Num
+    def metrics_count(k)
+      m = metrics
+      m[k]["count"]
+    rescue
+      0
+    end
+
+    Contract String => Num
+    def metrics_1m_rate(k)
+      m = metrics
+      m[k]["1_min_rate"]
     rescue
       0
     end
 
+    Contract String => Any
+    def dump_server_query(s)
+      fname = "#{working_dir}/#{s}-#{Time.now.to_i}-#{rand 100000}.json"
+      $stderr.puts "dumping server query #{fname}"
+      response = server.get("/#{s}")
+      File.open(fname, 'w') {|f| f.write(response.body) }
+    rescue
+      nil
+    end
+
+    Contract None => Any
+    def dump_metrics
+      dump_server_query("metrics")
+    end
+
+    Contract None => Any
+    def dump_info
+      dump_server_query("info")
+    end
+
+    Contract None => Any
+    def dump_scp_state
+      dump_server_query("scp")
+    end
+
+    Contract None => Num
+    def scp_ballots_prepared
+      metrics_count "scp.ballot.prepare"
+    end
+
+    Contract None => Num
+    def scp_quorum_heard
+      metrics_count "scp.quorum.heard"
+    end
+
+    Contract None => Bool
+    def check_no_error_metrics
+      m = metrics
+      for metric in ["scp.envelope.invalidsig",
+                     "history.publish.failure",
+                     "history.catchup.failure"]
+        c = m[metric]["count"] rescue 0
+        if c != 0
+          raise "nonzero metrics count for #{metric}: #{c}"
+        end
+      end
+      true
+    end
+
+    Contract Num, Num, Or[Symbol, Num] => Any
+    def start_load_generation(accounts, txs, txrate)
+      server.get("/generateload?accounts=#{accounts}&txs=#{txs}&txrate=#{txrate}")
+    end
+
+    Contract None => Num
+    def load_generation_runs
+      metrics_count "loadgen.run.complete"
+    end
+
+    Contract None => Num
+    def transactions_applied
+      metrics_count "ledger.transaction.apply"
+    end
+
+    Contract None => Num
+    def transactions_per_second
+      metrics_1m_rate "ledger.transaction.apply"
+    end
+
+    Contract None => Num
+    def operations_per_second
+      metrics_1m_rate "transaction.op.apply"
+    end
+
+    Contract None => Any
+    def start_checkdb
+      server.get("/checkdb")
+    end
+
+    Contract None => Num
+    def checkdb_runs
+      metrics_count "bucket.checkdb.execute"
+    end
+
+    Contract None => Num
+    def objects_checked
+      metrics_count "bucket.checkdb.object-compare"
+    end
+
     Contract None => Num
     def http_port
       base_port
@@ -171,10 +443,21 @@ module StellarCoreCommander
 
     end
 
+    Contract Stellar::KeyPair => Any
+    def account_row(account)
+      row = database[:accounts].where(:accountid => account.address).first
+      raise "Missing account in #{idname}'s database: #{account.address}" unless row
+      row
+    end
+
     Contract Stellar::KeyPair => Num
     def sequence_for(account)
-      row = database[:accounts].where(:accountid => account.address).first
-      row[:seqnum]
+      (account_row account)[:seqnum]
+    end
+
+    Contract Stellar::KeyPair => Num
+    def balance_for(account)
+      (account_row account)[:balance]
     end
 
     Contract None => Num
@@ -182,6 +465,87 @@ module StellarCoreCommander
       database[:ledgerheaders].max(:ledgerseq)
     end
 
+    Contract String => Any
+    def db_store_state(name)
+      database.select(:state).from(:storestate).filter(statename: name).first[:state]
+    end
+
+    Contract None => String
+    def latest_ledger_hash
+      s_lcl = db_store_state("lastclosedledger")
+      t_lcl = database.select(:ledgerhash)
+        .from(:ledgerheaders)
+        .filter(:ledgerseq=>latest_ledger).first[:ledgerhash]
+      raise "inconsistent last-ledger hashes in db: #{t_lcl} vs. #{s_lcl}" if t_lcl != s_lcl
+      s_lcl
+    end
+
+    Contract None => Any
+    def history_archive_state
+      ActiveSupport::JSON.decode(db_store_state("historyarchivestate"))
+    end
+
+    Contract None => Num
+    def account_count
+      database.fetch("SELECT count(*) FROM accounts").first[:count]
+    end
+
+    Contract None => Num
+    def trustline_count
+      database.fetch("SELECT count(*) FROM trustlines").first[:count]
+    end
+
+    Contract None => Num
+    def offer_count
+      database.fetch("SELECT count(*) FROM offers").first[:count]
+    end
+
+    Contract None => ArrayOf[Any]
+    def ten_accounts
+      database.fetch("SELECT * FROM accounts ORDER BY accountid LIMIT 10").all
+    end
+
+    Contract None => ArrayOf[Any]
+    def ten_offers
+      database.fetch("SELECT * FROM offers ORDER BY sellerid LIMIT 10").all
+    end
+
+    Contract None => ArrayOf[Any]
+    def ten_trustlines
+      database.fetch("SELECT * FROM trustlines ORDER BY accountid, issuer, assetcode LIMIT 10").all
+    end
+
+    Contract String, Any, Any => nil
+    def check_equal(kind, x, y)
+      raise UnexpectedDifference.new(kind, x, y) if x != y
+    end
+
+    Contract Process => nil
+    def check_equal_ledger_objects(other)
+      check_equal "account count", account_count, other.account_count
+      check_equal "trustline count", trustline_count, other.trustline_count
+      check_equal "offer count", offer_count, other.offer_count
+
+      check_equal "ten accounts", ten_accounts, other.ten_accounts
+      check_equal "ten trustlines", ten_trustlines, other.ten_trustlines
+      check_equal "ten offers", ten_offers, other.ten_offers
+    end
+
+    Contract Process => Any
+    def check_ledger_sequence_is_prefix_of(other)
+      q = "SELECT ledgerseq, ledgerhash FROM ledgerheaders ORDER BY ledgerseq"
+      our_headers = other.database.fetch(q).all
+      other_headers = other.database.fetch(q).all
+      our_hash = {}
+      other_hash = {}
+      other_headers.each do |row|
+        other_hash[row[:ledgerseq]] = row[:ledgerhash]
+      end
+      our_headers.each do |row|
+        check_equal "ledger hashes", other_hash[row[:ledgerseq]], row[:ledgerhash]
+      end
+    end
+
     Contract String => Maybe[String]
     def transaction_result(hex_hash)
       row = database[:txhistory].where(txid:hex_hash).first
@@ -196,14 +560,32 @@ module StellarCoreCommander
 
     Contract None => Num
     def close_timeout
-      15.0
+      150.0
+    end
+
+    Contract None => Num
+    def sync_timeout
+      if has_special_peers? and @catchup_complete
+        # catchup-complete can take quite a while on testnet; for now,
+        # give such tests an hour. May require a change in strategy later.
+        3600.0
+      else
+        # Checkpoints are made every 64 ledgers = 320s on a normal network,
+        # or every 8 ledgers = 8s on an accelerated-time network; we give you
+        # 3 checkpoints to make it to a sync (~16min) before giving up. The
+        # accelerated-time variant tends to need more tries due to S3 not
+        # admitting writes instantaneously, so we do not use a tighter bound
+        # for that case, just use the same 16min value, despite commonly
+        # succeeding in 20s or less.
+        320.0 * 3
+      end
     end
 
     Contract String, ArrayOf[String] => Maybe[Bool]
     def run_cmd(cmd, args)
       args += [{
-          out: "stellar-core.log",
-          err: "stellar-core.log",
+          out: ["stellar-core.log", "a"],
+          err: ["stellar-core.log", "a"],
         }]
 
       Dir.chdir working_dir do
@@ -211,5 +593,52 @@ module StellarCoreCommander
       end
     end
 
+    Contract None => Bool
+    def stopped?
+      !running?
+    end
+
+    Contract None => Bool
+    def launched?
+      !!@launched
+    end
+
+    Contract None => Bool
+    def crashed?
+      launched? && stopped?
+    end
+
+    Contract None => Any
+    def prepare
+      # noop by default, implement in subclass to customize behavior
+      nil
+    end
+
+    Contract None => Any
+    def run
+      raise Process::AlreadyRunning, "already running!" if running?
+      raise Process::Crash, "process #{name} has crashed. cannot run process again" if crashed?
+
+      setup
+      launch_process
+      @launched = true
+    end
+
+    # Dumps the database of the process to the working directory, returning the path to the file written to
+    Contract None => String
+    def dump_database
+      raise NotImplementedError, "implement in subclass"
+    end
+
+    private
+    Contract None => Any
+    def launch_process
+      raise NotImplementedError, "implement in subclass"
+    end
+
+    Contract None => Any
+    def setup
+      raise NotImplementedError, "implement in subclass"
+    end
   end
 end