Bitcoin Wiki - User contributions [en]

Proper Money Handling (JSON-RPC)

2011-06-11T01:57:12Z

Sdfdsafsaff: /* Common Lisp */

== Overview ==
The original bitcoin client stores all bitcoin values as 64-bit integers, with 1 BTC stored as 100,000,000 (one-hundred-million of the smallest possible bitcoin unit). Values are expressed as double-precision Numbers in the JSON API, with 1 BTC expressed as 1.00000000

If you are writing software that uses the JSON-RPC interface you need to be aware of possible floating-point conversion issues. You, or the JSON library you are using, should convert amounts to either a fixed-point Decimal representation (with 8 digits after the decimal point) or ideally a 64-bit integer representation. In either case, rounding values is required.

Improper value handling can lead to embarrassing errors; for example, if you truncate instead of doing proper rounding and your software will display the value "0.1 BTC" as "0.09999999 BTC" (or, worse, "0.09 BTC").

The original bitcoin client does proper, full-precision rounding for all values passed to it via the RPC interface. So, for example, if the value 0.1 is converted to the value "0.099999999999" by your JSON-RPC library, that value will be rounded to the nearest 0.00000001 bitcoin and will be treated as exactly 0.1 bitcoins.

The rest of this page gives sample code for various JSON libraries and programming languages.

== BASH ==
<source lang="bash">
function JSONtoAmount() {
printf '%.8f' "$1" | tr -d '.'
}
</source>

== C/C++ ==
C/C++ JSON libraries return the JavaScript Number type as type 'double'. To convert, without loss of precision, from a double to a 64-bit integer multiply by 100,000,000 and round to the nearest integer:
int64_t JSONtoAmount(double value) {
return (int64_t)(value * 1e8 + (value < 0.0 ? -.5 : .5));
}

To convert to a JSON value divide by 100,000,000.0, and make sure your JSON implementation outputs doubles with 8 or more digits after the decimal point:
double forJSON = (double)amount / 1e8;

== ECMAScript ==

function JSONtoAmount(value) {
return amount = Math.round(1e8 * value);
}

== Perl ==
sub JSONtoAmount {
return sprintf '%.0f', 1e8 * shift;
}

== PHP ==
function JSONtoAmount($value) {
return round(value * 1e8);
}

== Python ==
def JSONtoAmount(value):
return long(round(value * 1e8))
def AmountToJSON(amount):
return float(amount / 1e8)

== Common Lisp ==
(defun json-to-amount (n)
(coerce (round (* n 1e8)) 'integer))

'''CAUTION''': The CL-JSON library parses numbers as ''single'' precision floating-point by
default. The default parsing behavior can be overridden as follows:

(set-custom-vars :real (lambda (n)
(json::parse-number (concatenate 'string n "d0"))))
[[Category:Technical]]
[[Category:Developer]]

Proper Money Handling (JSON-RPC)

2011-06-11T01:56:38Z

Sdfdsafsaff: /* Common Lisp */

== Overview ==
The original bitcoin client stores all bitcoin values as 64-bit integers, with 1 BTC stored as 100,000,000 (one-hundred-million of the smallest possible bitcoin unit). Values are expressed as double-precision Numbers in the JSON API, with 1 BTC expressed as 1.00000000

If you are writing software that uses the JSON-RPC interface you need to be aware of possible floating-point conversion issues. You, or the JSON library you are using, should convert amounts to either a fixed-point Decimal representation (with 8 digits after the decimal point) or ideally a 64-bit integer representation. In either case, rounding values is required.

Improper value handling can lead to embarrassing errors; for example, if you truncate instead of doing proper rounding and your software will display the value "0.1 BTC" as "0.09999999 BTC" (or, worse, "0.09 BTC").

The original bitcoin client does proper, full-precision rounding for all values passed to it via the RPC interface. So, for example, if the value 0.1 is converted to the value "0.099999999999" by your JSON-RPC library, that value will be rounded to the nearest 0.00000001 bitcoin and will be treated as exactly 0.1 bitcoins.

The rest of this page gives sample code for various JSON libraries and programming languages.

== BASH ==
<source lang="bash">
function JSONtoAmount() {
printf '%.8f' "$1" | tr -d '.'
}
</source>

== C/C++ ==
C/C++ JSON libraries return the JavaScript Number type as type 'double'. To convert, without loss of precision, from a double to a 64-bit integer multiply by 100,000,000 and round to the nearest integer:
int64_t JSONtoAmount(double value) {
return (int64_t)(value * 1e8 + (value < 0.0 ? -.5 : .5));
}

To convert to a JSON value divide by 100,000,000.0, and make sure your JSON implementation outputs doubles with 8 or more digits after the decimal point:
double forJSON = (double)amount / 1e8;

== ECMAScript ==

function JSONtoAmount(value) {
return amount = Math.round(1e8 * value);
}

== Perl ==
sub JSONtoAmount {
return sprintf '%.0f', 1e8 * shift;
}

== PHP ==
function JSONtoAmount($value) {
return round(value * 1e8);
}

== Python ==
def JSONtoAmount(value):
return long(round(value * 1e8))
def AmountToJSON(amount):
return float(amount / 1e8)

== Common Lisp ==
(defun json-to-amount (n)
(coerce (round (* n 1e8)) 'integer))

'''CAUTION''': The CL-JSON library parses numbers as ''single'' precision floating-point by
default, costing you precision. The default parsing behavior can be overridden as follows:

(set-custom-vars :real (lambda (n)
(json::parse-number (concatenate 'string n "d0"))))
[[Category:Technical]]
[[Category:Developer]]

Talk:Proper Money Handling (JSON-RPC)

2011-06-10T23:15:16Z

Sdfdsafsaff:

RE: best practices in ECMAScript:
Just converting to base units doesn't magically fix the issues; if I have 1.0BTC == 100000000.0 base units and I need to divide that value into three equal pieces, I'm going to run into issues whether the result is 0.3333333.... or 3333333.33333...

And the fixes are the same: either round to the nearest .0000001 or to the nearest 1 before display, etc.

::The real solution is not to write money-handling code in ECMAScript. [[User:Sdfdsafsaff|Sdfdsafsaff]] 23:15, 10 June 2011 (GMT)

For Ruby I think the syntax is:

(f * 1e8).round.to_f / 1e8

Correct?

== ECMAScript? ==

Since the value is already in ECMAScript's native representation, why would you use a conversion function?

Talk:Proper Money Handling (JSON-RPC)

2011-06-10T23:14:20Z

Sdfdsafsaff: /* ECMAScript? */ new section

RE: best practices in ECMAScript:
Just converting to base units doesn't magically fix the issues; if I have 1.0BTC == 100000000.0 base units and I need to divide that value into three equal pieces, I'm going to run into issues whether the result is 0.3333333.... or 3333333.33333...

And the fixes are the same: either round to the nearest .0000001 or to the nearest 1 before display, etc.

For Ruby I think the syntax is:

(f * 1e8).round.to_f / 1e8

Correct?

== ECMAScript? ==

Since the value is already in ECMAScript's native representation, why would you use a conversion function?

Proper Money Handling (JSON-RPC)

2011-06-10T23:09:34Z

Sdfdsafsaff: /* Common Lisp */

Proper Money Handling (JSON-RPC)

2011-06-10T23:09:18Z

Sdfdsafsaff: