Thanks Mora,
this is a great proposal, I fully support it!
To start off, heres my bid for mandatory fields
The names are only suggestions.
- to_address
- amount (in satoshi to avoid any radix point confusion)
- confirmations (Number of confirmations at the time of the notification, not necessary the requested amount)
- txhash (the hash of the transaction that contains the payment)
- block (height of the block that contained the tx, -1 if unconfirmed)
- signature (see below)
- service (name of the service, could be used in shops where 2 of 3 notifications are needed, before its accepted)
- IP (public ip of the service, since this is included in the signature, a replay attack has to be done from the same IP (yes it can be spoofed))
I propose an additional fied:
"timestamp" which should be the date/time this transaction was observed by the monitoring system.
I am currently working on extending notification possibilites of bitcoinmonitor.net to support outgoing payments. To support this also for http callback we should keep the wording neutral, so "to_address" would become "address" and "amount" can be positive for incoming and negative for outgoing payments.
About the block number - Is this really necessary? I am not sure if it adds significant information. If not, i would omit it just to keep the list of parameters as short as possible.
If we can agree on a hashing algorithm, thats cool.
But since we may not, and any algorithm in time could become obsolete, I think a field to specify the used algorithm is useful, also this could allow services to make a easier CRC, for the "internet of things", like xor/crc8.
- algorithm (sha1, md5, crc32, etc.)
To keep it simple to implement, we should only list the ones that are likely to be used, since any payment system will need to implement all, so if possible, we should keep to the most standard ones, that are likely to be available.
I would suggest using PHP as the reference, since its pretty popular, and contains quite a few hashing systems.
While this is a very flexible approach it might make adoption of the system a bit more complicated. I think we should be able to agree on one algorithm. TBH I am lacking background knowledge to make an educated decision - basically I don't care which one to use.
There still would be the option to put the algorithm specifier outside the common signed_data part, so special solutions would still be possible.
I hope we can agree on a sequence, so that the system does not need to load a list of fields to calculate the signature.
Very simple proposal which i chose also for bitcoinmonitor.net: Alphabetical ordering ;-)
After security checks, a signature validation could be performed in PHP
if ($_SERVER['REMOTE_ADDR'] == $ip &&
$$algorithm($to_address.$amount.$confirmations.$txhash.$block.$ip.$secret) == $signature)
The service name does not need to be included in the calculation, since it would be used to lookup the secret value, so if its changed the validation will fail.
Any service can add extra fields, like btc_amount, from_addresses, datetime, etc.
Since the signature does not include those fields, the same code can still be used.
If those fields contain data, a middle-man would have interest in modifying, a second signature could be added.
This is only my suggestion, please feel free to comment and explain your view on how it can/should be done.
Proposal how to store the data in the POST body:
Use a json string e.g.
{
"signed_data": {
"address": "12r9JzPNnyWs2j1s9KLW5keqBr4kbJjxz6",
"amount": 122678000,
"confirmations": 2,
"timestamp": "2012-02-19 10:37:20.203541",
"txhash": "e0c84120068bfefddab051e751f3df963c4ed29e7b13eadac026e6f17f55fb06",
"ip": "127.0.0.1"
},
"signature": "38a25ec14b9ffcfe98938f3e35ac9cf41de2a971",
"service": ""
}