diff --git a/amount.go b/amount.go
new file mode 100644
index 0000000..d14b97a
--- /dev/null
+++ b/amount.go
@@ -0,0 +1,94 @@
+// Copyright (c) 2013, 2014 Conformal Systems LLC.
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+package btcutil
+
+import (
+ "errors"
+ "math"
+ "strconv"
+)
+
+// AmountUnit describes a method of converting an Amount to something
+// other than the base unit of a bitcoin. The value of the AmountUnit
+// is the exponent component of the decadic multiple to convert from
+// an amount in bitcoin to an amount counted in units.
+type AmountUnit int
+
+// These constants define the various standard units used when describing
+// a bitcoin monetary amount.
+const (
+ AmountMegaBitcoin AmountUnit = 6
+ AmountKiloBitcoin AmountUnit = 3
+ AmountBitcoin AmountUnit = 0
+ AmountMilliBitcoin AmountUnit = -3
+ AmountMicroBitcoin AmountUnit = -6
+ AmountBaseBitcoin AmountUnit = -8
+)
+
+// String returns the unit as a string. For recognized units, the SI
+// prefix is used, or "Satoshi" for the base unit. For all unrecognized
+// units, "1eN BTC" is returned, where N is the AmountUnit.
+func (u AmountUnit) String() string {
+ switch u {
+ case AmountMegaBitcoin:
+ return "MBTC"
+ case AmountKiloBitcoin:
+ return "kBTC"
+ case AmountBitcoin:
+ return "BTC"
+ case AmountMilliBitcoin:
+ return "mBTC"
+ case AmountMicroBitcoin:
+ return "μBTC"
+ case AmountBaseBitcoin:
+ return "Satoshi"
+ default:
+ return "1e" + strconv.FormatInt(int64(u), 10) + " BTC"
+ }
+}
+
+// Amount represents the base bitcoin monetary unit (colloquially referred
+// to as a `Satoshi'). A single Amount is equal to 1e-8 of a bitcoin.
+type Amount int64
+
+// NewAmount creates an Amount from a floating point value representing
+// some value in bitcoin.
+func NewAmount(f float64) (Amount, error) {
+ a := f * float64(SatoshiPerBitcoin)
+
+ // The amount is only valid if it does not exceed the total amount
+ // of bitcoin producable, and is not a floating point number that
+ // would otherwise fail that check such as NaN or +-Inf.
+ switch abs := math.Abs(a); {
+ case abs > float64(MaxSatoshi):
+ fallthrough
+ case math.IsNaN(abs) || math.IsInf(abs, 1):
+ return 0, errors.New("invalid bitcoin amount")
+ }
+
+ // Depending on the sign, add or subtract 0.5 and rely on integer
+ // truncation to correctly round the value up or down.
+ if a < 0 {
+ a = a - 0.5
+ } else {
+ a = a + 0.5
+ }
+ return Amount(a), nil
+}
+
+// ToUnit converts a monetary amount counted in bitcoin base units to a
+// floating point value representing an amount of bitcoin.
+func (a Amount) ToUnit(u AmountUnit) float64 {
+ return float64(a) / math.Pow10(int(u+8))
+}
+
+// Format formats a monetary amount counted in bitcoin base units as a
+// string for a given unit. The conversion will succeed for any unit,
+// however, known units will be formated with an appended label describing
+// the units with SI notation.
+func (a Amount) Format(u AmountUnit) string {
+ units := " " + u.String()
+ return strconv.FormatFloat(a.ToUnit(u), 'f', -int(u+8), 64) + units
+}
diff --git a/amount_test.go b/amount_test.go
new file mode 100644
index 0000000..f6d6d79
--- /dev/null
+++ b/amount_test.go
@@ -0,0 +1,183 @@
+// Copyright (c) 2013, 2014 Conformal Systems LLC.
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+package btcutil_test
+
+import (
+ . "github.com/conformal/btcutil"
+ "math"
+ "testing"
+)
+
+func TestAmountCreation(t *testing.T) {
+ tests := []struct {
+ name string
+ amount float64
+ valid bool
+ expected Amount
+ }{
+ // Positive tests.
+ {
+ name: "zero",
+ amount: 0,
+ valid: true,
+ expected: 0,
+ },
+ {
+ name: "max",
+ amount: 21e6,
+ valid: true,
+ expected: Amount(MaxSatoshi),
+ },
+ {
+ name: "min",
+ amount: -21e6,
+ valid: true,
+ expected: Amount(-MaxSatoshi),
+ },
+ {
+ name: "one hundred",
+ amount: 100,
+ valid: true,
+ expected: Amount(100 * SatoshiPerBitcoin),
+ },
+ {
+ name: "fraction",
+ amount: 0.01234567,
+ valid: true,
+ expected: Amount(1234567),
+ },
+ {
+ name: "rounding up",
+ amount: 54.999999999999943157,
+ valid: true,
+ expected: Amount(55 * SatoshiPerBitcoin),
+ },
+ {
+ name: "rounding down",
+ amount: 55.000000000000056843,
+ valid: true,
+ expected: Amount(55 * SatoshiPerBitcoin),
+ },
+
+ // Negative tests.
+ {
+ name: "exceeds max",
+ amount: 21e6 + 1,
+ valid: false,
+ },
+ {
+ name: "exceeds min",
+ amount: -21e6 - 1,
+ valid: false,
+ },
+ {
+ name: "not-a-number",
+ amount: math.NaN(),
+ valid: false,
+ },
+ {
+ name: "-infinity",
+ amount: math.Inf(-1),
+ valid: false,
+ },
+ {
+ name: "+infinity",
+ amount: math.Inf(1),
+ valid: false,
+ },
+ }
+
+ for _, test := range tests {
+ a, err := NewAmount(test.amount)
+ switch {
+ case test.valid && err != nil:
+ t.Errorf("%v: Positive test Amount creation failed with: %v", test.name, err)
+ continue
+ case !test.valid && err == nil:
+ t.Errorf("%v: Negative test Amount creation succeeded (value %v) when should fail", test.name, a)
+ continue
+ }
+
+ if a != test.expected {
+ t.Errorf("%v: Created amount %v does not match expected %v", test.name, a, test.expected)
+ }
+ }
+}
+
+func TestAmountUnitConversions(t *testing.T) {
+ tests := []struct {
+ name string
+ amount Amount
+ unit AmountUnit
+ converted float64
+ s string
+ }{
+ {
+ name: "MBTC",
+ amount: Amount(MaxSatoshi),
+ unit: AmountMegaBitcoin,
+ converted: 21,
+ s: "21 MBTC",
+ },
+ {
+ name: "kBTC",
+ amount: Amount(44433322211100),
+ unit: AmountKiloBitcoin,
+ converted: 444.33322211100,
+ s: "444.333222111 kBTC",
+ },
+ {
+ name: "BTC",
+ amount: Amount(44433322211100),
+ unit: AmountBitcoin,
+ converted: 444333.22211100,
+ s: "444333.222111 BTC",
+ },
+ {
+ name: "mBTC",
+ amount: Amount(44433322211100),
+ unit: AmountMilliBitcoin,
+ converted: 444333222.11100,
+ s: "444333222.111 mBTC",
+ },
+ {
+
+ name: "μBTC",
+ amount: Amount(44433322211100),
+ unit: AmountMicroBitcoin,
+ converted: 444333222111.00,
+ s: "444333222111 μBTC",
+ },
+ {
+
+ name: "satoshi",
+ amount: Amount(44433322211100),
+ unit: AmountBaseBitcoin,
+ converted: 44433322211100,
+ s: "44433322211100 Satoshi",
+ },
+ {
+
+ name: "non-standard unit",
+ amount: Amount(44433322211100),
+ unit: AmountUnit(-1),
+ converted: 4443332.2211100,
+ s: "4443332.22111 1e-1 BTC",
+ },
+ }
+
+ for _, test := range tests {
+ f := test.amount.ToUnit(test.unit)
+ if f != test.converted {
+ t.Errorf("%v: converted value %v does not match expected %v", test.name, f, test.converted)
+ continue
+ }
+
+ s := test.amount.Format(test.unit)
+ if s != test.s {
+ t.Errorf("%v: format '%v' does not match expected '%v'", test.name, s, test.s)
+ }
+ }
+}
diff --git a/test_coverage.txt b/test_coverage.txt
index 7b99711..41764c6 100644
--- a/test_coverage.txt
+++ b/test_coverage.txt
@@ -4,32 +4,36 @@ github.com/conformal/btcutil/base58.go Base58Encode 100.00% (15/15)
github.com/conformal/btcutil/block.go Block.Tx 100.00% (12/12)
github.com/conformal/btcutil/block.go Block.Transactions 100.00% (11/11)
github.com/conformal/btcutil/address.go encodeAddress 100.00% (9/9)
-github.com/conformal/btcutil/tx.go NewTxFromBytes 100.00% (7/7)
+github.com/conformal/btcutil/amount.go AmountUnit.String 100.00% (8/8)
+github.com/conformal/btcutil/amount.go NewAmount 100.00% (8/8)
github.com/conformal/btcutil/block.go NewBlockFromBytes 100.00% (7/7)
-github.com/conformal/btcutil/block.go Block.Sha 100.00% (5/5)
+github.com/conformal/btcutil/tx.go NewTxFromBytes 100.00% (7/7)
github.com/conformal/btcutil/tx.go Tx.Sha 100.00% (5/5)
+github.com/conformal/btcutil/block.go Block.Sha 100.00% (5/5)
+github.com/conformal/btcutil/amount.go Amount.Format 100.00% (2/2)
github.com/conformal/btcutil/address.go NewAddressScriptHash 100.00% (2/2)
github.com/conformal/btcutil/hash160.go calcHash 100.00% (2/2)
-github.com/conformal/btcutil/address.go AddressScriptHash.ScriptAddress 100.00% (1/1)
-github.com/conformal/btcutil/address.go AddressPubKey.EncodeAddress 100.00% (1/1)
-github.com/conformal/btcutil/address.go AddressScriptHash.String 100.00% (1/1)
-github.com/conformal/btcutil/tx.go Tx.MsgTx 100.00% (1/1)
-github.com/conformal/btcutil/address.go AddressPubKeyHash.String 100.00% (1/1)
-github.com/conformal/btcutil/tx.go Tx.SetIndex 100.00% (1/1)
-github.com/conformal/btcutil/address.go AddressPubKey.ScriptAddress 100.00% (1/1)
-github.com/conformal/btcutil/address.go AddressPubKey.String 100.00% (1/1)
-github.com/conformal/btcutil/address.go AddressPubKeyHash.ScriptAddress 100.00% (1/1)
-github.com/conformal/btcutil/block.go NewBlock 100.00% (1/1)
-github.com/conformal/btcutil/block.go Block.SetHeight 100.00% (1/1)
-github.com/conformal/btcutil/block.go Block.Height 100.00% (1/1)
github.com/conformal/btcutil/hash160.go Hash160 100.00% (1/1)
github.com/conformal/btcutil/address.go AddressPubKeyHash.EncodeAddress 100.00% (1/1)
-github.com/conformal/btcutil/tx.go NewTx 100.00% (1/1)
-github.com/conformal/btcutil/block.go NewBlockFromBlockAndBytes 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressPubKeyHash.ScriptAddress 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressPubKeyHash.String 100.00% (1/1)
github.com/conformal/btcutil/address.go AddressScriptHash.EncodeAddress 100.00% (1/1)
-github.com/conformal/btcutil/tx.go Tx.Index 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressScriptHash.ScriptAddress 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressScriptHash.String 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressPubKey.EncodeAddress 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressPubKey.ScriptAddress 100.00% (1/1)
+github.com/conformal/btcutil/address.go AddressPubKey.String 100.00% (1/1)
+github.com/conformal/btcutil/amount.go Amount.ToUnit 100.00% (1/1)
github.com/conformal/btcutil/block.go OutOfRangeError.Error 100.00% (1/1)
github.com/conformal/btcutil/block.go Block.MsgBlock 100.00% (1/1)
+github.com/conformal/btcutil/block.go Block.Height 100.00% (1/1)
+github.com/conformal/btcutil/block.go Block.SetHeight 100.00% (1/1)
+github.com/conformal/btcutil/block.go NewBlock 100.00% (1/1)
+github.com/conformal/btcutil/block.go NewBlockFromBlockAndBytes 100.00% (1/1)
+github.com/conformal/btcutil/tx.go Tx.MsgTx 100.00% (1/1)
+github.com/conformal/btcutil/tx.go Tx.Index 100.00% (1/1)
+github.com/conformal/btcutil/tx.go Tx.SetIndex 100.00% (1/1)
+github.com/conformal/btcutil/tx.go NewTx 100.00% (1/1)
github.com/conformal/btcutil/address.go DecodeAddress 95.65% (22/23)
github.com/conformal/btcutil/appdata.go appDataDir 92.00% (23/25)
github.com/conformal/btcutil/address.go NewAddressPubKeyHash 91.67% (11/12)
@@ -38,17 +42,17 @@ github.com/conformal/btcutil/address.go EncodePrivateKey 90.91% (20/22)
github.com/conformal/btcutil/block.go Block.TxLoc 88.89% (8/9)
github.com/conformal/btcutil/block.go Block.Bytes 88.89% (8/9)
github.com/conformal/btcutil/address.go AddressPubKey.serialize 85.71% (6/7)
+github.com/conformal/btcutil/address.go DecodePrivateKey 83.33% (20/24)
github.com/conformal/btcutil/address.go NewAddressPubKey 83.33% (15/18)
github.com/conformal/btcutil/address.go checkBitcoinNet 83.33% (5/6)
-github.com/conformal/btcutil/address.go DecodePrivateKey 82.61% (19/23)
github.com/conformal/btcutil/block.go Block.TxSha 75.00% (3/4)
github.com/conformal/btcutil/address.go AddressPubKeyHash.IsForNet 60.00% (3/5)
-github.com/conformal/btcutil/address.go AddressPubKey.IsForNet 60.00% (3/5)
github.com/conformal/btcutil/address.go AddressScriptHash.IsForNet 60.00% (3/5)
+github.com/conformal/btcutil/address.go AddressPubKey.IsForNet 60.00% (3/5)
github.com/conformal/btcutil/certgen.go NewTLSCertPair 0.00% (0/50)
github.com/conformal/btcutil/address.go AddressPubKey.AddressPubKeyHash 0.00% (0/3)
-github.com/conformal/btcutil/address.go AddressPubKey.SetFormat 0.00% (0/1)
github.com/conformal/btcutil/appdata.go AppDataDir 0.00% (0/1)
github.com/conformal/btcutil/address.go AddressPubKey.Format 0.00% (0/1)
-github.com/conformal/btcutil ------------------------------- 77.25% (275/356)
+github.com/conformal/btcutil/address.go AddressPubKey.SetFormat 0.00% (0/1)
+github.com/conformal/btcutil ------------------------------- 78.46% (295/376)