Add support for personal_sign. (#136)

* add PersonalMessage to support personal_sign

* update docs about sign methods

* add one method recoverPortalPersonalSign

Co-authored-by: PanaW <wangpan@conflux-chain.org>

SUMMARY.md

@@ -10,6 +10,7 @@
   * [Account](docs/account.md)
   * [Sending Transaction](docs/how_to_send_tx.md)
   * [Interact with Contract](docs/interact_with_contract.md)
+  * [Sign methods](docs/sign_methods.md)
   * [Error Handling](docs/error_handling.md)
 * [API](docs/api/README.md)
   * [Conflux](docs/api/Conflux.md)

docs/providers.md

@@ -30,7 +30,7 @@ const cfx = new Conflux({
 ## Connect through Conflux Portal
 An Dapp can connect through Conflux Blockchain through [Portal](https://portal.conflux-chain.org/). Which is a browser extension that provides:
 
-* A connection to the Ethereum network (a Provider)
+* A connection to the Conflux network (a Provider)
 * Holds your private key and can sign things (a Signer)
 
 js-conflux-sdk can work with Portal to talk with Conflux blockchain, simply by set `conflux` to `Conflux` instance's provider.

docs/sign_methods.md

@@ -0,0 +1,96 @@
+# sign methods
+
+## Recover ConfluxPortal's personal_sign message
+
+To verify portal's personal_sign method signed signature, developer need to recover publicKey or address from it and message. `PersonalMessage` class provide a static method can do this.
+
+```js
+const { PersonalMessage } = require('js-conflux-sdk');
+const message = 'Hello World';
+const signature = '0xxxxx';
+
+// message can be a normal string, or a hex encoded string
+const publicKey = PersonalMessage.recoverPortalPersonalSign(signature, message);
+// 0x4646ae5047316b4230d0086c8acec687f00b1cd9d1dc634f6cb358ac0a9a8ffffe77b4dd0a4bfb95851f3b7355c781dd60f8418fc8a65d14907aff47c903a559
+```
+
+## CIP-23 personal_sign
+
+The SDK has provide a  `PersonalMessage` class with can be used to personal_sign a message.
+
+```js
+const { PersonalMessage } = require('js-conflux-sdk');
+const privateKey = '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'; // use your own private key here
+const message = 'Hello World';
+const signature = PersonalMessage.sign(privateKey, message);
+// 0xd72ea2020802d6dfce0d49fc1d92a16b43baa58fc152d6f437d852a014e0c5740b3563375b0b844a835be4f1521b4ae2a691048622f70026e0470acc5351043a01
+const publicKey = PersonalMessage.recover(signature, message);
+// 0x4646ae5047316b4230d0086c8acec687f00b1cd9d1dc634f6cb358ac0a9a8ffffe77b4dd0a4bfb95851f3b7355c781dd60f8418fc8a65d14907aff47c903a559
+```
+
+## CIP-23 typedDataSign
+
+Conflux also have support for typed data sign through [CIP23](https://github.com/Conflux-Chain/CIPs/blob/2d9fdbdb08f66f705348669a6cd85e2d53509e97/CIPs/cip-23.md), which is similar to [EIP712](https://eips.ethereum.org/EIPS/eip-712).
+
+There is a Node.js package [`cip-23`](https://www.npmjs.com/package/cip-23) which provide some utility functions that can help with signing and verifying CIP-23 based messages
+
+```json
+{
+  "types": {
+    "CIP23Domain": [
+      { "name": "name", "type": "string" },
+      { "name": "version", "type": "string" },
+      { "name": "chainId", "type": "uint256" },
+      { "name": "verifyingContract", "type": "address" }
+    ],
+    "Person": [
+      { "name": "name", "type": "string" },
+      { "name": "wallet", "type": "address" }
+    ],
+    "Mail": [
+      { "name": "from", "type": "Person" },
+      { "name": "to", "type": "Person" },
+      { "name": "contents", "type": "string" }
+    ]
+  },
+  "primaryType": "Mail",
+  "domain": {
+    "name": "Ether Mail",
+    "version": "1",
+    "chainId": 1,
+    "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
+  },
+  "message": {
+    "from": {
+      "name": "Cow",
+      "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826"
+    },
+    "to": {
+      "name": "Bob",
+      "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB"
+    },
+    "contents": "Hello, Bob!"
+  }
+}
+```
+
+```js
+import { getMessage } from 'cip-23';
+import { sign } from 'js-conflux-sdk';
+
+const typedData = { /*...*/ };
+const message = getMessage(typedData).toString('hex'); // Build message
+// 1901f2cee375fa42b42143804025fc449deafd50cc031ca257e0b194a650a912090fc52c0ee5d84264471806290a3f2c4cecfc5490626bf912d01f240d7a274b371e
+const messageHash = getMessage(typedData, true).toString('hex'); // Build message hash
+// be609aee343fb3c4b28e1df9e632fca64fcfaede20f02e86244efddf30957bd2
+const privateKey = '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'; // use your own private key here
+// Sign message hash with private key
+const sig = sign.ecdsaSign(messageHash, privateKey);
+```
+
+## Useful links
+
+1. [MetaMask sign methods](https://docs.metamask.io/guide/signing-data.html)
+2. [CIP23](https://github.com/Conflux-Chain/CIPs/blob/2d9fdbdb08f66f705348669a6cd85e2d53509e97/CIPs/cip-23.md)
+3. [EIP712](https://eips.ethereum.org/EIPS/eip-712)
+4. [EIP712 is here: What to expect and how to use it](https://medium.com/metamask/eip712-is-coming-what-to-expect-and-how-to-use-it-bb92fd1a7a26)

docs/utilities.md

@@ -0,0 +1,50 @@
+Common utilities
+===
+
+### Types Conversion
+The `format` utility can be used for format types:
+
+* uInt
+* bigInt
+* bigUInt
+* hex
+* address
+* hexAddress
+* hexBuffer
+* bytes
+* boolean
+* keccak256
+
+
+```js
+const { format } = require('js-conflux-sdk');
+// ======================== to hex string
+format.hex(null)
+// '0x'
+format.hex(1)
+// "0x01"
+format.hex(256)
+// "0x0100"
+format.hex(true)
+// "0x01"
+format.hex(Buffer.from([1,10,255]))
+// "0x010aff"
+format.hex("0x0a")
+// "0x0a"
+
+// ======================== to Conflux address
+format.address('0x0123456789012345678901234567890123456789', 1)
+// "cfxtest:aaawgvnhveawgvnhveawgvnhveawgvnhvey1umfzwp"
+
+// ======================== to hex40 address
+format.hexAddress('cfxtest:aaawgvnhveawgvnhveawgvnhveawgvnhvey1umfzwp')
+// 0x0123456789012345678901234567890123456789
+
+// ======================== to buffer
+format.hexBuffer(Buffer.from([0, 1]))
+// <Buffer 00 01>
+format.hexBuffer(null)
+// <Buffer >
+format.hexBuffer(1024)
+// <Buffer 04 00>
+```

package.json

@@ -1,7 +1,7 @@
 {
   "name": "js-conflux-sdk",
   "description": "JavaScript Conflux Software Development Kit",
-  "version": "1.6.12",
+  "version": "1.6.13",
   "license": "LGPL-3.0",
   "author": "Haizhou@conflux-chain.org",
   "repository": "https://github.com/Conflux-Chain/js-conflux-sdk.git",
@@ -34,7 +34,7 @@
     "lodash": "^4.17.19",
     "scrypt-js": "^3.0.1",
     "secp256k1": "^3.7.1",
-    "superagent": "^5.1.0",
+    "superagent": "^6.1.0",
     "websocket": "^1.0.31"
   },
   "devDependencies": {

src/Message.js

@@ -5,8 +5,6 @@ class Message {
   /**
    * Signs the hash with the privateKey.
    *
-   * > TODO support [CIP 23](https://github.com/Conflux-Chain/CIPs/blob/master/CIPs/cip-23.md)
-   *
    * @param privateKey {string|Buffer}
    * @param messageHash {string|Buffer}
    * @return {string} The signature as hex string.