Merge pull request #1218 from maraoz/docs/pubkeys

improve PublicKey docs and fix #1215

docs/publickey.md

@@ -6,7 +6,10 @@ description: A simple interface for handling private keys.
 
 ## Description
 
-Represents a bitcoin public key and is needed to be able to receive bitcoin, as is usually represented as a bitcoin [Address](address.md), see the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Technical_background_of_version_1_Bitcoin_addresses). A PublicKey in Bitcore is an immutable object and can be instantiated from a [Point](crypto.md), string, [PrivateKey](privatekey.md), Buffer and a [BN](crypto.md).
+Represents a bitcoin public key and is needed to be able to receive bitcoin, as is usually represented as a bitcoin [Address](address.md).
+See the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Technical_background_of_version_1_Bitcoin_addresses).
+
+A PublicKey in Bitcore is an immutable object and can be instantiated from a [Point](crypto.md), string, [PrivateKey](privatekey.md), Buffer or a [BN](crypto.md).
 
 ## Instantiate a Public Key
 
@@ -34,4 +37,37 @@ if (PublicKey.isValid('02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0
 }
 ```
 
-Note: It's important to note that there are two possible ways to represent public key, the standard is *compressed* and includes the x value and parity (as represented above in the documentation). There is also a longer version that is *uncompressed* which includes both x and y values, and using this can generate a different bitcoin address, so it's important to note this possibility, however it's discouraged to be used.
+## Compressed vs Uncompressed
+
+It's important to note that there are two possible ways to represent a public key.
+The standard is *compressed* and includes the X value and parity (as represented above in the documentation).
+There is also a longer version that is *uncompressed* which includes both X and Y values. Using this encoding will generate a different bitcoin address, so be careful when selecting the encoding.
+Uncompressed public keys start with 0x04; compressed public keys begin with 0x03 or 0x02 depending on whether they're greater or less than the midpoint of the curve. These prefix bytes are all used in official secp256k1 documentation.
+
+Example:
+```javascript
+> var bitcore = require('bitcore');
+
+// compressed public key starting with 0x03 (greater than midpoint of curve)
+> var compressedPK = bitcore.PublicKey('030589ee559348bd6a7325994f9c8eff12bd'+
+    '5d73cc683142bd0dd1a17abc99b0dc');
+> compressedPK.compressed;
+true
+> compressedPK.toAddress().toString();
+'1KbUJ4x8epz6QqxkmZbTc4f79JbWWz6g37'
+// compressed public key starting with 0x02 (smaller than midpoint of curve)
+> var compressedPK2 = new bitcore.PublicKey('02a1633cafcc01ebfb6d78e39f687a1f'+
+    '0995c62fc95f51ead10a02ee0be551b5dc');
+> compressedPK2.compressed;
+true
+> compressedPK.toAddress().toString();
+'1KbUJ4x8epz6QqxkmZbTc4f79JbWWz6g37'
+// uncompressed public key, starting with 0x04. Contains both X and Y encoded
+> var uncompressed = bitcore.PublicKey('0479BE667EF9DCBBAC55A06295CE870B07029'+
+    'BFCDB2DCE28D959F2815B16F81798483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68'+
+    '554199C47D08FFB10D4B8');
+> uncompressed.compressed
+false
+> uncompressed.toAddress().toString()
+'1EHNa6Q4Jz2uvNExL497mE43ikXhwF6kZm'
+```

lib/publickey.js

@@ -343,8 +343,8 @@ PublicKey.isValid = function(data) {
  */
 PublicKey.prototype.toObject = function toObject() {
   return {
-    x: this.point.getX().toString('hex'),
-    y: this.point.getY().toString('hex'),
+    x: this.point.getX().toString('hex', 2),
+    y: this.point.getY().toString('hex', 2),
     compressed: this.compressed
   };
 };

test/publickey.js

@@ -194,6 +194,12 @@ describe('PublicKey', function() {
       }).to.throw();
     });
 
+    it('works for X starting with 0x00', function() {
+      var a = new PublicKey('030589ee559348bd6a7325994f9c8eff12bd5d73cc683142bd0dd1a17abc99b0dc');
+      var b = new PublicKey('03'+a.toObject().x);
+      b.toString().should.equal(a.toString());
+    });
+
   });
 
   describe('#fromPrivateKey', function() {