A proposal for bitcoin daemon boundraries and API calls.

bitcoin api proposal.txt

Daemons:

* bitcoin-netd
  Communicates with the bitcoin P2P network, and maintains a copy of the block chain and pending txns.
  Has functions for querying the block and txn chain.
  No private data whatsoever.

  API:
    * GetStatus() - Returns current latest block ID and generation number
    * GetPendingTransactions() - Returns transactions not yet in a block [may have filter fields of some sort]
    * GetBlock(hash, includeTxns) - Returns a specific block
    * GetTransaction(hash) - Returns a specific transaction
    * GetTransactionStatus(hash) - Returns txn state (pending, X confirmations, double-spent and rejected, invalid)
    * PostTransaction(txnContents) - Posts a transaction to the bitcoin network. Returns an error on malformed or doublespent txns
    * SearchTxns(filterTerms) - Searches for txns matching certain conditions eg:
        AfterBlock=blockID:hash - errors if the blockID does not match the hash given (ie, when the block chain is changed after block collisions). Returns txns in blocks after that block
        ToKey=keyHash - returns only txns redeemable with that key
    * WatchTxns(toKey=keyHash) - returns a stream of new transactions sent to the specified key
    * API calls for miners?

* bitcoin-walletd
  Responsible for securely storing the wallet data. May interact directly with the user for permission
  depending on configured policy.

  API:
    * GetBalance()
    * ListKeys(includeHidden=boolean, createdSince=time) - returns public key:description pairs
    * SetKeyDescription(pubKey=hash, desc=string)
    * CreateKey(description=string) - returns public key only
    * SetKeyHidden(pubKey=hash, hidden=boolean)

    * GetTransactionLog(afterIndex=int, count=int) - Returns log entries from the wallet.
      These entries correspond to both spends and receives; a single txn may produce multiple log entries.
      Entries should reference the specific txnin or txnout they refer to.
    * SendFunds(amount=int, dest=hash) - Send funds to the specified key.
      May prompt the user for permission. May take a long time to do so.
      Returns errors on insufficient funds or user refusal.

    * ImportKey(privateKey=hash, reclaim=boolean) - Imports a key (and all its funds) into this wallet.
      Invokes a search on the main netd to find such transactions. If reclaim=true, issues transactions
      to move these funds onto fresh keys as well.
    * streaming/event-based API?
  Backup/restore is beyond the scope of this API and would use a private interface, possibly with direct
  user intervention.

The API should be available in 3 forms:

1. as a static C library (C calling conventions only)
2. as a shared (dynamic) library
3. as a stand alone executable with a google protocol buffers socket api

The standalone version will require a bit more scaffolding to support authentication and encryption of the communications...it will also need to support multiple simultaneously connected clients.

In addition to the API calls outlined above, some mechanism for handling API versions should be implemented. Libraries often deal with versions utilizing filenames and filesystem links. To avoid the complexity that creates for the end user, I suggest we build a version handshake into the API. A call such as "init()" could return a struct listing the protocol versions supported. The client would choose the highest version that it also supports for use. All remaining API calls could use a version suffix (i.e. getBlock_v12() to indicate version 12 of the protocol). The library/executable should support at least 3 versions of the API to provide maximum compatibility. For static linking this is not really an issue, but for dynamic linking and the standalone executable, supporting multiple versions of the API is important and will help ensure that any given version of the libraries are widely compatible with various versions of clients.