Accounts: svn rev 188 (JSON-RPC API changes)

[Gavin Andresen]

I just committed a minimal implementation of "accounts", as discussed a few weeks ago in this thread.

If you're using the command-line or JSON APIs, you should be aware of a change that might make your code break:  the sendtoaddress method will return a hexadecimal transaction id (256-bit hash) instead of the string 'sent'.

All of the 'label' commands have been renamed; the old names are still supported but are deprecated and may eventually be removed.

If you're developing a web service using bitcoin, the new 'sendfrom' and 'move' methods can make it much easier to keep track of customer account balances.  The API is intended to be used like this:

Create a new account:  just generate a unique account ID in your application (maybe customer's login name).

Get a bitcoin receiving address associated with the account:
  getaccountaddress <account_id>
 Note: multiple bitcoin addresses can be associated with the account

Send bitcoins from the customer's account:
  sendfrom <fromaccount> <tobitcoinaddress> <amount> [minconf=1] [comment] [comment-to]
 Will fail if <fromaccount> doesn't have enough bitcoins (otherwise returns transaction id)

Move bitcoins between accounts:
  move <fromaccount> <toaccount> <amount> [minconf=1] [comment]
 Will fail if <fromaccount> doesn't have enough bitcoins

Report account balance:
  getbalance [account] [minconf=1]


The empty-string account is a little bit special.  Any coins received on bitcoin addresses not associated with other accounts is credited to it, and coins sent via the (old) sendtoaddress method are debited from it.

Coming soon, I hope, will be a gettransaction <txid> method to return details of a transaction that is stored in your wallet (like which account it was to or from and whether or not transaction fees were paid).  And listtransactions, to get an accountant-friendly itemized list of all the transactions that went into any particular account balance.

[1714184411]

1714184411

[1714184411]

1714184411

[davout]

Oh gavin, you know how to speak directly to a developers heart. 
This is such a incredibly sweet change!

[davout]

Will call to sendtoaddress automatically use move behind the scenes if the two addresses belong to two different accounts on the same server ?

Will that require a normal transaction to be broadcast ?

[Gavin Andresen]

The send methods don't try to be clever; they always broadcast transactions.

If you want that behavior, be clever yourself:  call  getaccount <bitcoinaddress>  before calling send, and then call move instead of send* if you find out the bitcoinaddress is one of yours.

[nelisky]

So, if I have accounts and I still use the old sendtoaddress, will it fail if the empty account does not have enough funds? Or will it use these first, but then still go for the rest of the wallet addresses?

[davout]

The send methods don't try to be clever; they always broadcast transactions.

If you want that behavior, be clever yourself:  call  getaccount <bitcoinaddress>  before calling send, and then call move instead of send* if you find out the bitcoinaddress is one of yours.

Ok, I'm just a little confused as to how the network will be able to validate the transaction since balances are associated to addresses and not to accounts.

Like, how does it work if :
 - address A has 100 BTC available
 - address B has 50,
 - they're in the same wallet but owned by different accounts

Let's say 100 BTC are moved from account to account to B's account ends up holding 150 BTC, how is the network going to allow address B to send 150 BTC to another random address ?

[ribuck]

I feel a little uneasy about the "empty-string" account, because there will sometimes be user interface elements that need to display the account name, and leaving the field empty may be confusing to the end-user.

My first inclination is to suggest a reserved account name such as "default" that takes the place of the "empty-string" account. Then, a list of "balances by account" can include an entry for "default account" instead of an entry for a blankly-named account.

Obviously this will cause problems with internationalisation. So my next inclination is to suggest that some characters be excluded from a legal account name, so that those characters can be used to name the empty-string account. For example, English-language client software might present the empty-string account to the user as "(default)", but other languages could use other names enclosed by parentheses, if parentheses are not permitted to be used in a regular account name.

In any case, it should be specified which characters can be used to form an account name.

[Gavin Andresen]

So, if I have accounts and I still use the old sendtoaddress, will it fail if the empty account does not have enough funds? Or will it use these first, but then still go for the rest of the wallet addresses?

The "" (empty-string-named) account is allowed to have a negative balance.  You can sendtoaddress as long as the entire wallet has enough coins.

Accounts (like labels before them) are just a useful accounting mechanism.  The rest of the network doesn't know or care what accounts you have.  And although transactions to and from the wallet are credited or debited to accounts, all of the 'coins' get mixed together in the wallet, there is no notion of "this account received 100 bitcoins in this transaction, so we should use those for that transaction out..."

For example:

100 bitcoins are sent to an address associated with Account A.  A's balance is now +100.
50 bitcoins are sent to an address associated with B.  B's balance is now +50.
100 are moved from A to B. A has zero, B has 150.

B is allowed to send 150, but it won't necessarily be the 100 originally sent to A and the 50 sent to B; if other accounts have received coins (transactions), those might be sent instead.

it should be specified which characters can be used to form an account name

bitcoin doesn't care (use any valid JSON string for the name), and the rest of the network doesn't care, so use account names that make sense for your application.

[jgarzik]

IMO the wallet keys (== the db4 keys in a key/value table, not ECDSA keys) should be easier to group.

e.g. make the keys look like paths "/account/$name/ecdsa_keypair_1234abcde" or "/settings/generate"

This enables easier hierarchical organization based on sane, readable prefixes.  Using "/ac/$name/" would permit trivial searching and grouping using DB_SET_RANGE, for example.  (yes, I do see DB_SET_RANGE already in use, via the 'ac' prefix).

The current techniques of "flat namespace" or now "has 'ac' prefix" are straight out of the 1970s   Surely we can do better than that.

[jgarzik]

Another comment...  please make the default account something other than the empty string.

Make the default account name a wallet setting, with a default of 'default' or 'master' or similar.  ie. provide a sensible default, but don't force users to use that name if they really don't want to.  git follows a similar policy:  the "master" branch is named "master" by convention/default only, and may be changed to suit the user preferences.

An empty string just invites crazy scripting/quoting attacks, and is in other ways error prone for users, even if the actual bitcoin implementation is 100% bug-free and perfect.  Empty strings and specially quoted strings are a pain.

[jgarzik]

Is there no longer a way to place labels on a per-transaction basis?

It seems that my practice of labelling an address "mtgox-20101122-1", signalling an incoming transaction from mtgox, is no longer supported.

Even with the existence of accounts, per-BC-address labels are useful.  I wouldn't want to create a new account for each mtgox transaction...  mtgox withdrawals should all go into the same account.

[Gavin Andresen]

Is there no longer a way to place labels on a per-transaction basis?

There never was a way to place labels on a per-transaction basis.  It was always a one-label-to-multiple-bitcoin-addresses association.

But all of the old label functionality is still there, just renamed.  You should be able to do anything you were doing before.

However, you might think you were doing something that you weren't actually doing.  There was no way to label/name particular transactions before (just addresses).

RE: the empty string as the default account:   None of this is (or will be) visible to GUI users, and if you're a programmer using the JSON or the command-line interface SURELY you know how to quote strings.

RE: hierarchical wallet keys:  Huh?  If you want trivial searching and grouping... then export the info into a database and use SQL.

[bitcoinex]

I think this is a step towards to a multi-user bitcoind on 8333 port! Will only need to map the system usernames into bitcoind "accounts" and implement access permissions to bitcoind based on ident. upd: System users bitcoin "accounts" must be separated from manually created regular bitcoin "accounts" by the special wallet flag to avoid fraud.

[jgarzik]

Is there no longer a way to place labels on a per-transaction basis?

There never was a way to place labels on a per-transaction basis.  It was always a one-label-to-multiple-bitcoin-addresses association.

But all of the old label functionality is still there, just renamed.  You should be able to do anything you were doing before.

However, you might think you were doing something that you weren't actually doing.  There was no way to label/name particular transactions before (just addresses).

"my practice of labelling an address"

"per-BC-address labels"

So yes, I know they are labelling an address (key), not a single transaction.  That doesn't change the practice or the point.

RE: the empty string as the default account:   None of this is (or will be) visible to GUI users, and if you're a programmer using the JSON or the command-line interface SURELY you know how to quote strings.

I'm sure that's what they said when they invented shell scripts, SQL, ...   Surely decades of security-related quoting bugs have disproven this logic?

But irrespective of that, surely it is obvious that specifying empty strings such as e.g. on a shell command line is annoying and user-unfriendly, compared to something obvious and human-friendly like "default" or "master."

[wumpus]

I like the empty string more than a human readable name for the default account. It should be as different from the normal accounts as possible.

At least we now won't have problems when users register a 'default' or 'master' login on our site

This is a great thing to have. The only thing missing for fully fledged payment processing still is some kind of async notification mechanism (for example, a JSON RPC callback) when coins are incoming on some account.

[davout]

A really sweet thing would be the client storing its data in a MySQL DB

[wumpus]

A really sweet thing would be the client storing its data in a MySQL DB

Wouldn't that open a full can of worms about database support? A wants MySQL, B wants PostgresSQL, C wants Oracle, D wants some NoSQL thingy. And then the dev team will spend all their time with yet another database wrapper.

IMO, it would be better to keep the client self-contained (which can be done with BDB that is used now) and as small as possible. All queries can be done through JSONRPC. Why would you need SQL?

[nelisky]

re: multiple dbs and such, what I would really like to see is not necessarily client suport for multiple dbs, but rather a clean wallet interface and a default implementation, much like what is happening with mining today.

With this we could have custom builds for other DBs if need be and, more interestingly for me, make the import/export trivial and allow for some really neat tricks for web services without needing to keep mucking about the default client sources.

[wumpus]

Yeah, it's also a matter of documenting and specifying the protocol.

If that were documented, people could write their own clients in Python, PHP, Java, etc with their own database backends and fun. The official reference implementation could remain simple, small, optimized, without too much abstraction layers and dependencies.

Then again, it seems that bitcoind is still in a state of flux and unstable, so doing that now will be aiming for a moving target.

[davout]

A really sweet thing would be the client storing its data in a MySQL DB

Wouldn't that open a full can of worms about database support? A wants MySQL, B wants PostgresSQL, C wants Oracle, D wants some NoSQL thingy. And then the dev team will spend all their time with yet another database wrapper.

IMO, it would be better to keep the client self-contained (which can be done with BDB that is used now) and as small as possible. All queries can be done through JSONRPC. Why would you need SQL?

I think I opened a can of worms suggesting that

Also,

All some queries can be done through JSONRPC. Why would you need SQL?

I'm ok with the client being self contained, if i really need to go read the DB I'll find myself a nice little BerkeleyDB wrapper

On a side note, I'm really curious about how blocks and transactions are uniquely identified inside the client, through their hashes ?
They're not guaranteed to be unique, and, over the course of time I think it's almost certain collisions will happen. I was wondering about that when asking myself what column to use for primary key...