JSON-RPC programming tips using labels

JSON-RPC programming tips using labels

I added label related functions to help with managing multiple addresses per user.  New or renamed functions are:
 getreceivedbyaddress -- amount received on a single address
 getreceivedbylabel -- amount received by all addresses with this label
 listreceivedbyaddress -- list addresses and amounts they've received
 listreceivedbylabel -- list labels and amounts they've received
 setlabel -- misc label functions for completeness

For consistency I renamed getamountreceived->getreceivedbyaddress and getallreceived->listreceivedbyaddress.  The old names are still there so as not to break existing code, but they're deprecated.

The idea is that if you give the username whenever you call getnewaddress, you can get the user's total received across all their addresses using the "bylabel" functions.  You can freely change their address without worrying about tracking all their old addresses.

A good way to automate changing the user's receiving address: just before displaying their current address, check if it has been used to receive anything, if it has then replace it with a new one:

// Get a new address whenever the current one has received anything
if (strAddr == "" || getreceivedbyaddress(strAddr) > 0)
   strAddr = getnewaddress(strUsername); // Label the address with username
Display(strAddr); // Display their current receiving address

// Get total received by all the user's addresses
getreceivedbylabel(strUsername, 0) // unconfirmed
getreceivedbylabel(strUsername, 1) // available balance

If you're just getting one particular user's balance, such as in response to a page request by that user, use getreceivedbylabel, but if you're scanning over all users, it's better to use listreceivedbylabel to get the complete list and scan against the result.  Scanning users with getreceivedbylabel would be n-squared, using listreceivedbylabel is n-log-n (or n linear).

You should only really need to scan all users if you're polling in order to spontaneously take action in response to money received, rather than the user going to a webpage, seeing their balance and telling you what to do with it.  It's not necessary to poll very frequently.  If you require 1 confirmation, that'll take an average of 10 minutes anyway, so there's no point in polling more often than every few minutes.

If you're selling digital goods and services, where you don't lose much if someone gets a free access, and it can't be resold for profit, I think you're fine to accept 0 confirmations.

It's mostly only if you were selling gold or currency that you'd need multiple confirmations.