# Gavin Andresen
# 2010-10-27 18:41:36
# https://bitcointalk.org/index.php?topic=665.msg18890#msg18890

An impromptu brainstorm this morning in IRC chat (thanks everybody!) helped me think through a few issues for an "accounts" API. @p{par}

The big idea: @p{par}

Replace the JSON-RPC "label" API with the notion of "accounts". @p{par}

What is broken about the current API? @p{brk}
 + you can't get a list of all transactions that make up an account's balance @p{brk}
 + if your bitcoin service has the notion of maintaining a balance for multiple @p{brk}
   customers then you end up mirroring information stored in the bitcoin wallet database. @p{brk}
   Mirroring is a problem because if the connection between your service and bitcoin @p{brk}
   fails at the wrong time (e.g. between sending a "sendtoaddress" and getting @p{brk}
   back "sent") your database can be out of sync with the bitcoin reality. @p{par}

Problems this proposal does NOT tackle: @p{brk}
 + multiple "wallets" for GUI bitcoin users @p{brk}
 + improving anonymity by keeping "coins" from different people in different "wallets" @p{brk}
 + "push" notifications from bitcoin when coins are received (or blocks generated) @p{par}

NEW METHODS: @p{brk}
@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-} @p{brk}
getaccountaddress @p{lt}account@s{gt} @p{brk}
move @p{lt}fromaccount@s{gt} @p{lt}toaccount@s{gt} @p{lt}amount@s{gt} @p{brk}
sendfrom @p{lt}account@s{gt} @p{lt}tobitcoinaddress@s{gt} @p{lt}amount@s{gt} [minconf=1] [comment] [comment-to] @p{brk}
listtransactions @p{lt}account@s{gt} [minconf=1] [count=10] [start=0] @p{par}

CHANGES TO EXISTING METHODS: @p{brk}
@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}- @p{brk}
getbalance [account] [minconf=1] @p{par}

listreceivedbyaddress: @p{brk}
  return "account" instead of "label" in JSON-RPC result @p{par}

sendtoaddress: @p{brk}
  same API, but debits accounts as described below @p{par}

METHODS RENAMED: @p{brk}
@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}- @p{brk}
setlabel @p{--}@s{gt} setaccount @p{brk}
getlabel @p{--}@s{gt} getaccountfromaddress @p{brk}
getaddressesbylabel -@s{gt} getaddressesbyaccount @p{brk}
getreceivedbylabel -@s{gt} getreceivedbyaccount @p{brk}
listreceivedbylabel -@s{gt} listreceivedbyaccount @p{brk}
  ... returns "account" instead of "label" in result @p{par}

 @p{brk}
@p{(so}METHODS REMOVED (deprecated): @p{brk}
@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{@p{--}-}@p{--} @p{brk}
setlabel@p{so)} @p{par}

 @p{brk}
NOTES: @p{brk}
@p{@p{--}-}@p{@p{--}-} @p{par}

All existing routines would continue to be supported for a while (e.g. listreceivedbylabel would be kept as a synonym for listreceivedbyaccount, and would return both "account" and "label" in the JSON result). @p{par}

Coins going into or out of the wallet that don't have an associated account will be associated with a default account (named the empty string: ""). So sum(account balances) will always equal server account balance. @p{par}

Generated coins will be assigned to the default account when they mature. @p{par}

sendtoaddress, and the GUI "send" button, will debit @p{(so}accounts starting with the default account (if it has a non-zero balance) and continuing in alphabetical (ascii) order.@p{so)}the default address, which will be allowed to go negative. @p{par}

None of these changes will be visible in the graphical user interface. These changes are for people running bitcoind to support bitcoin-related services, not for end-users. @p{par}

It would be nice to support transactions by batching up several commmands and ensuring that they either all succeed or all fail.  But: this should be useful even without that feature.  The cleanest way of doing that is JSON-RPC-2.0 "batch send", and that all can come in a later version. @p{par}

@p{(so}Why remove setlabel?  Because it is not clear what "setaccount @p{lt}bitcoinaddrress@s{gt}" means for old transactions that were received on that address@p{--} do they remain credited to the old account (confusing!) or does history get rewritten so they are credited to the new account (your accountant/auditor will surely protest!).@p{so)} @p{par}

UPDATE: svn rev 188 implements most of this (all but gettransactions).  And due to the disaster recovery scenario described below, 'setlabel' stays as 'setaccount'. @p{brk}