hyper-multisig 0.2.0 → 1.0.0

package/README.md

@@ -2,75 +2,134 @@
 
 # Hyper Multisig
 
-- Create multisig hypercores and hyperdrives
-- Create signing requests for multisig cores and drives
-- Sign and release multisig cores and drives
+Create and manage multisig hypercores and hyperdrives.
 
-Includes sanity checks to avoid common mistakes and risky releases (detecting conflicts before committing, ensuring all cores are seeded by multiple other peers etc.)
+Includes sanity checks to avoid common mistakes and risky releases (detecting conflicts before committing, ensuring all cores are seeded by multiple peers, etc.)
 
-## Install
+End users most likely want to use [hyper-multisig-cli](https://github.com/holepunchto/hyper-multisig-cli) instead of interacting directly with this module.
+
+## Installation
 
 ```
-npm i hyper-multisig
+npm install -g hyper-multisig
 ```
 
-## Usage
+## API
 
-End users most likely want to use [hyper-multisig-cli](https://github.com/holepunchto/hyper-multisig-cli) instead of interacting directly with this module.
+#### `const multisig = new HyperMultisig(store, swarm)`
+
+Create a new HyperMultisig instance.
+
+- `store` - a [Corestore](https://github.com/holepunchto/corestore) instance
+- `swarm` - a [Hyperswarm](https://github.com/holepunchto/hyperswarm) instance
+
+#### `const { manifest, key, core } = await multisig.createCore(publicKeys, namespace, [options])`
+
+Create a multisig hypercore.
+
+- `publicKeys` - array of z32-encoded public keys from all signers
+- `namespace` - string to avoid collisions (the combination of signers and namespace must be globally unique, as it deterministically defines the key of the resulting multisig hypercore)
+
+Options include:
+
+- quorum: minimum number of signatures required, defaults to half of public keys + 1
+
+Returns `{ manifest, key, core }` where `core` is a read-only Hypercore.
+
+#### `const { manifest, key, core, blobsManifest, blobsKey, blobsCore } = await multisig.createDrive(publicKeys, namespace, [options])`
+
+Create a multisig hyperdrive (with associated blobs core).
+
+Same parameters and options as `createCore`.
+
+#### `const runner = multisig.requestCore(publicKeys, namespace, srcCore, length, [options])`
 
-## Multisig Flow
+Generate a signing request from a source core.
+
+- `publicKeys` - array of public keys
+- `namespace` - namespace string
+- `srcCore` - source Hypercore to create a request for
+- `length` - length of the source core to use for the request
+
+Options include:
+
+```js
+{
+  force: false, // skip verification checks
+  quorum, // override default quorum
+  peerUpdateTimeout: 5000 // timeout in ms for peer updates
+}
+```
+
+Call `await runner.done()` to get `{ manifest, request }`. The `request` is the signing request, as a buffer.
+
+#### `const runner = multisig.requestDrive(publicKeys, namespace, srcDrive, length, [options])`
+
+Generate a signing request for a source drive.
+
+Same parameters and options as `requestCore`, but takes a Hyperdrive instead of a Hypercore.
+
+Call `await runner.done()` to get `{ manifest, request }`.
+
+#### `const runner = multisig.commitCore(publicKeys, namespace, srcCore, request, responses, [options])`
+
+Commit signed data to a multisig core.
+
+- `publicKeys` - array of public keys
+- `namespace` - namespace string
+- `srcCore` - source Hypercore that was signed
+- `request` - the signing request
+- `responses` - array of signed responses from signers
+
+Options include:
+
+```js
+{
+  quorum, // override default quorum
+  dryRun: false, // perform validation without committing
+  force: false, // advanced option, and dangerous
+  skipTargetChecks: false, // only useful for the first commit
+  peerUpdateTimeout: 5000, // timeout in ms for peer updates
+  minFullCopies: 2 // minimum number of peers with a full copy of the core
+}
+```
 
-- Step 1: Each signer uses [hypercore-sign](https://github.com/holepunchto/hypercore-sign) to generate a key pair (secret key and public key). Later, public keys from all signers will be collected to create a multisig core.
+Call `await runner.done()` to get `{ manifest, core, quorum, result }` where `quorum` is the amount of valid signatures.
 
-  ```shell
-  hypercore-sign generate-keys
+The runner emits events during the commit process:
 
-  # to create an additional key pair
-  HYPERCORE_SIGN_KEYS_DIRECTORY=<path-to-another-dir> hypercore-sign generate-keys
-  ```
+- `'verify-committable-start'` - fired with `(srcCoreKey, destCoreKey)`
+- `'commit-start'` - fired when the commit begins
+- `'verify-committed-start'` - fired with `(destCoreKey)` after the commit completes
 
-- Step 2: Create a multisig core given the public keys from the previous step, and a namespace to avoid collisions (the combination signers-namespace has to be globally unique, as it determinstically defines the key of the resulting multisig hypercore).
+#### `const runner = multisig.commitDrive(publicKeys, namespace, srcDrive, request, responses, [options])`
 
-  ```js
-  // collect public keys of all signers generated by hypercore-sign
-  const publicKeys = ['o37a1...', 'qgbd9...', '6r66j...']
+Commit signed data to a multisig drive.
 
-  // to avoid collision, we structure namespace based on repo path
-  const namespace = 'holepunchto/my-repo'
+Same parameters and options as `commitCore`, but takes a Hyperdrive instead of a Hypercore.
 
-  const store = new Corestore('storage')
-  await store.ready()
+Call `await runner.done()` to get `{ manifest, core, blobsCore, quorum, result }`.
 
-  const multisig = new HyperMultisig(store, swarm)
-  const { manifest, core } = await multisig.createCore(publicKeys, namespace).done()
-  ```
+## Multisig flow
 
-- Step 3: Generate a signing request based on a normal core (non-multisig) with the manifest from the previous step.
+1. Each signer uses [hypercore-sign](https://github.com/holepunchto/hypercore-sign) to generate a key pair:
 
-  ```js
-  const srcCore = store.get({ name: 'my-core' })
-  await srcCore.ready()
+   ```sh
+   hypercore-sign generate-keys
+   ```
 
-  srcCore.append('hello world 1')
-  srcCore.append('hello world 2')
-  srcCore.append('hello world 3')
+2. Collect all public keys and create a multisig core or drive with `createCore` or `createDrive`.
 
-  const multisig = new HyperMultisig(store)
-  const { request } = await multisig.requestCore(publicKeys, namespace, srcCore, 3).done()
-  ```
+3. Generate a signing request with `requestCore` or `requestDrive`.
 
-- Step 4: Use [hypercore-sign](https://github.com/holepunchto/hypercore-sign) to sign the signing request to generate a signature. Later, signatures from all signers will be collected to sign the multisig core.
+4. Each signer signs the request using [hypercore-sign](https://github.com/holepunchto/hypercore-sign):
 
-  ```shell
-  hypercore-sign <signingRequest>
-  ```
+   ```sh
+   hypercore-sign <signingRequest>
+   ```
 
-- Step 5: Commit the multisig core with the signatures from the previous step.
+5. Collect all signatures and commit with `commitCore` or `commitDrive`.
 
-  ```js
-  // collect signatures from all signers generated by hypercore-sign
-  const signatures = [signature1, signature2, ...]
+## License
 
-  const multisig = new HyperMultisig(store, swarm)
-  await multisig.commitCore(publicKeys, namespace, srcCore, request, signatures).done()
-  ```
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-multisig",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Multisig hypercore and hyperdrive",
   "main": "index.js",
   "files": [