Merge pull request #147 from FabricLabs/feature/nat-cleanup

NAT Cleanup

API.md

@@ -164,6 +164,9 @@ execute either the full set or none.</p>
 <dt><a href="#Swarm">Swarm</a> : <code>String</code></dt>
 <dd><p>Orchestrates a network of peers.</p>
 </dd>
+<dt><a href="#Token">Token</a></dt>
+<dd><p>Implements a capability-based security token.</p>
+</dd>
 <dt><a href="#Transition">Transition</a></dt>
 <dd><p>The <a href="#Transition">Transition</a> type reflects a change from one finite
 <a href="#State">State</a> to another.</p>
@@ -326,10 +329,22 @@ Casts the Actor to a normalized Buffer.
 <a name="Actor+toGenericMessage"></a>
 
 ### actor.toGenericMessage() ⇒ <code>Object</code>
-Casts the Actor to a generic message.
+Casts the Actor to a generic message, used to uniquely identify the Actor's state.
+Fields:
+- `preimage`: JSON.stringify(state)
+- `hash`: SHA256(preimage)
+- `type`: 'FabricActorState'
+- `version`: 1 (for now)
+- `object`: state
+- `parent`: null (for now)
 
 **Kind**: instance method of [<code>Actor</code>](#Actor)  
 **Returns**: <code>Object</code> - Generic message object.  
+**See**
+
+- [https://en.wikipedia.org/wiki/Merkle_tree](https://en.wikipedia.org/wiki/Merkle_tree)
+- [https://dev.fabric.pub/messages](https://dev.fabric.pub/messages)
+
 <a name="Actor+toObject"></a>
 
 ### actor.toObject() ⇒ <code>Object</code>
@@ -932,6 +947,7 @@ the Fabric network using a terminal emulator.
     * [new CLI([settings])](#new_CLI_new)
     * [.start()](#CLI+start)
     * [.stop()](#CLI+stop)
+    * [._handleGrantCommand(params)](#CLI+_handleGrantCommand)
 
 <a name="new_CLI_new"></a>
 
@@ -956,6 +972,17 @@ Starts (and renders) the CLI.
 Disconnect all interfaces and exit the process.
 
 **Kind**: instance method of [<code>CLI</code>](#CLI)  
+<a name="CLI+_handleGrantCommand"></a>
+
+### clI.\_handleGrantCommand(params)
+Creates a token for the target signer with a provided role and some optional data.
+
+**Kind**: instance method of [<code>CLI</code>](#CLI)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| params | <code>Array</code> | Parameters array. |
+
 <a name="Collection"></a>
 
 ## Collection
@@ -2067,11 +2094,23 @@ Casts the Actor to a normalized Buffer.
 <a name="Actor+toGenericMessage"></a>
 
 ### logger.toGenericMessage() ⇒ <code>Object</code>
-Casts the Actor to a generic message.
+Casts the Actor to a generic message, used to uniquely identify the Actor's state.
+Fields:
+- `preimage`: JSON.stringify(state)
+- `hash`: SHA256(preimage)
+- `type`: 'FabricActorState'
+- `version`: 1 (for now)
+- `object`: state
+- `parent`: null (for now)
 
 **Kind**: instance method of [<code>Logger</code>](#Logger)  
 **Overrides**: [<code>toGenericMessage</code>](#Actor+toGenericMessage)  
 **Returns**: <code>Object</code> - Generic message object.  
+**See**
+
+- [https://en.wikipedia.org/wiki/Merkle_tree](https://en.wikipedia.org/wiki/Merkle_tree)
+- [https://dev.fabric.pub/messages](https://dev.fabric.pub/messages)
+
 <a name="Actor+toObject"></a>
 
 ### logger.toObject() ⇒ <code>Object</code>
@@ -3174,6 +3213,8 @@ Create an instance of a Service.
 | settings | <code>Object</code> |  | Configuration for this service. |
 | [settings.networking] | <code>Boolean</code> | <code>true</code> | Whether or not to connect to the network. |
 | [settings.@data] | <code>Object</code> |  | Internal data to assign. |
+| [settings.frequency] | <code>Object</code> |  | Interval frequency in hertz. |
+| [settings.state] | <code>Object</code> |  | Initial state to assign. |
 
 <a name="Service+init"></a>
 
@@ -3507,11 +3548,23 @@ Casts the Actor to a normalized Buffer.
 <a name="Actor+toGenericMessage"></a>
 
 ### signer.toGenericMessage() ⇒ <code>Object</code>
-Casts the Actor to a generic message.
+Casts the Actor to a generic message, used to uniquely identify the Actor's state.
+Fields:
+- `preimage`: JSON.stringify(state)
+- `hash`: SHA256(preimage)
+- `type`: 'FabricActorState'
+- `version`: 1 (for now)
+- `object`: state
+- `parent`: null (for now)
 
 **Kind**: instance method of [<code>Signer</code>](#Signer)  
 **Overrides**: [<code>toGenericMessage</code>](#Actor+toGenericMessage)  
 **Returns**: <code>Object</code> - Generic message object.  
+**See**
+
+- [https://en.wikipedia.org/wiki/Merkle_tree](https://en.wikipedia.org/wiki/Merkle_tree)
+- [https://dev.fabric.pub/messages](https://dev.fabric.pub/messages)
+
 <a name="Actor+toObject"></a>
 
 ### signer.toObject() ⇒ <code>Object</code>
@@ -3970,6 +4023,23 @@ Begin computing.
 
 **Kind**: instance method of [<code>Swarm</code>](#Swarm)  
 **Returns**: <code>Promise</code> - Resolves to instance of [Swarm](#Swarm).  
+<a name="Token"></a>
+
+## Token
+Implements a capability-based security token.
+
+**Kind**: global class  
+<a name="new_Token_new"></a>
+
+### new Token([settings])
+Create a new Fabric Token.
+
+**Returns**: [<code>Token</code>](#Token) - The token instance.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [settings] | <code>Object</code> | Configuration. |
+
 <a name="Transition"></a>
 
 ## Transition
@@ -4382,42 +4452,38 @@ Manages interaction with the Bitcoin network.
 
 * [Bitcoin](#Bitcoin) ⇐ [<code>Service</code>](#Service)
     * [new Bitcoin([settings])](#new_Bitcoin_new)
-    * _instance_
-        * [.UAString](#Bitcoin+UAString)
-        * [.tip](#Bitcoin+tip)
-        * [.height](#Bitcoin+height)
-        * [.broadcast(tx)](#Bitcoin+broadcast)
-        * [._processSpendMessage(message)](#Bitcoin+_processSpendMessage) ⇒ <code>BitcoinTransactionID</code>
-        * [._prepareTransaction(obj)](#Bitcoin+_prepareTransaction)
-        * [._handleCommittedBlock(block)](#Bitcoin+_handleCommittedBlock)
-        * [._handlePeerPacket(msg)](#Bitcoin+_handlePeerPacket)
-        * [._handleBlockFromSPV(msg)](#Bitcoin+_handleBlockFromSPV)
-        * [._handleTransactionFromSPV(tx)](#Bitcoin+_handleTransactionFromSPV)
-        * [._subscribeToShard(shard)](#Bitcoin+_subscribeToShard)
-        * [._connectSPV()](#Bitcoin+_connectSPV)
-        * [.connect(addr)](#Bitcoin+connect)
-        * [._requestBlockAtHeight(height)](#Bitcoin+_requestBlockAtHeight) ⇒ <code>Object</code>
-        * [._createContractProposal(options)](#Bitcoin+_createContractProposal) ⇒ <code>ContractProposal</code>
-        * [._buildPSBT(options)](#Bitcoin+_buildPSBT) ⇒ <code>PSBT</code>
-        * [.start()](#Bitcoin+start)
-        * [.stop()](#Bitcoin+stop)
-        * [.init()](#Service+init)
-        * [.tick()](#Service+tick) ⇒ <code>Number</code>
-        * [.beat()](#Service+beat) ⇒ [<code>Service</code>](#Service)
-        * [.get(path)](#Service+get) ⇒ <code>Mixed</code>
-        * [.set(path)](#Service+set) ⇒ <code>Mixed</code>
-        * [.trust(source)](#Service+trust) ⇒ [<code>Service</code>](#Service)
-        * [.handler(message)](#Service+handler) ⇒ [<code>Service</code>](#Service)
-        * [.lock([duration])](#Service+lock) ⇒ <code>Boolean</code>
-        * [.route(msg)](#Service+route) ⇒ <code>Promise</code>
-        * [._GET(path)](#Service+_GET) ⇒ <code>Promise</code>
-        * [._PUT(path, value, [commit])](#Service+_PUT) ⇒ <code>Promise</code>
-        * [.send(channel, message)](#Service+send) ⇒ [<code>Service</code>](#Service)
-        * [._registerActor(actor)](#Service+_registerActor) ⇒ <code>Promise</code>
-        * [._send(message)](#Service+_send)
-    * _static_
-        * ~~[.Transaction](#Bitcoin.Transaction)~~
-        * ~~[.MutableTransaction](#Bitcoin.MutableTransaction)~~
+    * [.UAString](#Bitcoin+UAString)
+    * [.tip](#Bitcoin+tip)
+    * [.height](#Bitcoin+height)
+    * [.broadcast(tx)](#Bitcoin+broadcast)
+    * [._processSpendMessage(message)](#Bitcoin+_processSpendMessage) ⇒ <code>BitcoinTransactionID</code>
+    * [._prepareTransaction(obj)](#Bitcoin+_prepareTransaction)
+    * [._handleCommittedBlock(block)](#Bitcoin+_handleCommittedBlock)
+    * [._handlePeerPacket(msg)](#Bitcoin+_handlePeerPacket)
+    * [._handleBlockFromSPV(msg)](#Bitcoin+_handleBlockFromSPV)
+    * [._handleTransactionFromSPV(tx)](#Bitcoin+_handleTransactionFromSPV)
+    * [._subscribeToShard(shard)](#Bitcoin+_subscribeToShard)
+    * [._connectSPV()](#Bitcoin+_connectSPV)
+    * [.connect(addr)](#Bitcoin+connect)
+    * [._requestBlockAtHeight(height)](#Bitcoin+_requestBlockAtHeight) ⇒ <code>Object</code>
+    * [._createContractProposal(options)](#Bitcoin+_createContractProposal) ⇒ <code>ContractProposal</code>
+    * [._buildPSBT(options)](#Bitcoin+_buildPSBT) ⇒ <code>PSBT</code>
+    * [.start()](#Bitcoin+start)
+    * [.stop()](#Bitcoin+stop)
+    * [.init()](#Service+init)
+    * [.tick()](#Service+tick) ⇒ <code>Number</code>
+    * [.beat()](#Service+beat) ⇒ [<code>Service</code>](#Service)
+    * [.get(path)](#Service+get) ⇒ <code>Mixed</code>
+    * [.set(path)](#Service+set) ⇒ <code>Mixed</code>
+    * [.trust(source)](#Service+trust) ⇒ [<code>Service</code>](#Service)
+    * [.handler(message)](#Service+handler) ⇒ [<code>Service</code>](#Service)
+    * [.lock([duration])](#Service+lock) ⇒ <code>Boolean</code>
+    * [.route(msg)](#Service+route) ⇒ <code>Promise</code>
+    * [._GET(path)](#Service+_GET) ⇒ <code>Promise</code>
+    * [._PUT(path, value, [commit])](#Service+_PUT) ⇒ <code>Promise</code>
+    * [.send(channel, message)](#Service+send) ⇒ [<code>Service</code>](#Service)
+    * [._registerActor(actor)](#Service+_registerActor) ⇒ <code>Promise</code>
+    * [._send(message)](#Service+_send)
 
 <a name="new_Bitcoin_new"></a>
 
@@ -4779,24 +4845,6 @@ Sends a message.
 | --- | --- | --- |
 | message | <code>Mixed</code> | Message to send. |
 
-<a name="Bitcoin.Transaction"></a>
-
-### ~~Bitcoin.Transaction~~
-***Deprecated***
-
-Provides bcoin's implementation of `TX` internally.  This static may be
-removed in the future.
-
-**Kind**: static property of [<code>Bitcoin</code>](#Bitcoin)  
-<a name="Bitcoin.MutableTransaction"></a>
-
-### ~~Bitcoin.MutableTransaction~~
-***Deprecated***
-
-Provides bcoin's implementation of `MTX` internally.  This static may be
-removed in the future.
-
-**Kind**: static property of [<code>Bitcoin</code>](#Bitcoin)  
 <a name="Exchange"></a>
 
 ## Exchange

DEVELOPERS.md

@@ -5,7 +5,7 @@ applications, so grab a coffee ☕ and settle in.
 ## Quick Start
 See also [`QUICKSTART.md`][quickstart-guide] for up-to-date instructions.
 
-0. `nvm use 16.17.1` (you can get `nvm` from [nvm.sh][nvm-official])
+0. `nvm use 18.19.0` (you can get `nvm` from [nvm.sh][nvm-official])
 1. `npm install -g @fabric/core` to add `fabric` to your path
 2. (optional) `fabric setup` to set up your environment (generates a new master key)
 3. `fabric` should now be enough to get you up and running!
@@ -15,6 +15,10 @@ That's it!  Let's take a look at overall Fabric system and how you, as a develop
 ## Architecture
 Fabric is two things — a protocol for machines to exchange information ("the Fabric Protocol"), and a sotware library (`@fabric/core`) offering up many tools and utilities for building your own networks which speak this protocol.
 
+Typically, you will need the following:
+
+  - a Bitcoin Node (bitcoind and/or bcoin with `bcoin --only=127.0.0.1`)
+
 ### Overview
 Using Fabric to interface securely with decentralized systems, you'll start by following the instructions above to obtain a globally-available version of the `fabric` command-line client, which provides the majority of tools you'll need along the way.
 

INSTALL.md

@@ -1,6 +1,6 @@
 # Installing Fabric
 ## Prerequisites
-- Node.js 16.17.1
+- Node.js 18.19.0
 
 ## Quick Start
 You can install Fabric by running:
@@ -24,8 +24,8 @@ By default, the Fabric CLI connects to `playnet` for an initial set of peers.  Y
 ## Notes
 If you don't have Node.js, or an incorrect version, we recommend [installing NVM][installing-nvm].  Once complete, you can install and set the default node version:
 ```
-nvm install 16.17.1
-nvm alias default 16.17.1 # optional
+nvm install 18.19.0
+nvm alias default 18.19.0 # optional
 ```
 
 [installing-nvm]: https://nvm.sh

QUICKSTART.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 0. (optional) Install NVM: `https://nvm.sh`
-1. Install Node 16.17.1 (use `nvm install 16.17.1` if using `nvm`)
+1. Install Node 18.19.0 (use `nvm install 18.19.0` if using `nvm`)
 
 ## Instructions
 0. Meet the prerequisites (above)

README.md

@@ -37,6 +37,9 @@ You'll also want `bitcoind` installed, and fully synchronized with your
 preferred network.  You can use `scripts/playnet.sh` to run a local playnet
 node, for which you can use the faucet: https://faucet.playnet.fabric.pub
 
+## What is Fabric?
+`@fabric/core` provides the reference implementation for [the Fabric Protocol][protocol], a "language" for exchanging information through peer-to-peer networks.  Written in JavaScript, it is meant to be well-documented and easy to understand — but not the final implementation.
+
 ## Contributing
 Fork and clone [the Fabric GitHub repository][fabric-github] and launch a local
 web server with `npm run examples` to view the examples, or `npm run docs` once
@@ -102,29 +105,6 @@ main().catch((exception) => {
 });
 ```
 
-### Using Fabric in the Browser
-[`@fabric/http`][fabric-http] generates a `fabric.min.js` bundle, which can be included with any HTML
-document to expose the API in a browser.
-
-```html
-<html>
-  <body>
-    <div>
-      <h1>Example</h1>
-    </div>
-    <script src="/bundles/fabric.min.js"></script>
-    <script type="text/javascript">
-      window.fabric.addEventListener('', (event) => {
-        console.log('Fabric Event:', event);
-      });
-
-      window.fabric.start();
-      console.log('Fabric started!');
-    </script>
-  </body>
-</html>
-```
-
 ## Plugins
 Fabric is an extensible framework, supporting a variety of plugins.
 
@@ -148,6 +128,25 @@ To add your project to the list, [read the API docs][api-docs], create a public
 repository for the source code, then [edit this file][edit-readme] to include a
 link to your work.
 
+### Edge Nodes
+Full Fabric nodes connected to the World Wide Web (WWW).  Only SSL (port 443) is supported.
+
+| Host | Status |
+| ---- | ------ |
+| `hub.fabric.pub` | `ONLINE`
+| `labs.fabric.pub` | `OFFLINE`
+
+### Fabric Projects
+Either Fabric libraries or projects running Fabric, this list encompasses the most interesting work in the ecosystem.
+
+| Name | Description | Status | v0.1.0-RC1 ready
+| ---- | ----------- | ------ | ----------
+| [`@fabric/core`][fabric-github] | Core Library
+| [`@fabric/http`][http-plugin] | Edge Nodes
+| [`hub.fabric.pub`](https://hub.fabric.pub) |
+| [`labs.fabric.pub`](https://labs.fabric.pub) |
+| [`grove.chat`][chat] |
+
 ## Learning More
 The best place to get started is in [the #learning channel][learning], a
 collection of empassioned educators eager to help you.
@@ -169,6 +168,7 @@ Fabric on Twitter: [@FabricProtocol][twitter]
 
 [fabric-github]: https://github.com/FabricLabs/fabric
 [http-plugin]: https://github.com/FabricLabs/fabric-http
+[hub-plugin]: https://github.com/FabricLabs/hub.fabric.pub
 [matrix-plugin]: https://github.com/FabricLabs/fabric-matrix
 [twilio-plugin]: https://github.com/FabricLabs/fabric-twilio
 [zapier-plugin]: https://github.com/FabricLabs/fabric-zapier
@@ -187,7 +187,9 @@ Fabric on Twitter: [@FabricProtocol][twitter]
 [badge-doorman-status]: https://img.shields.io/travis/FabricLabs/doorman.svg?branch=master&style=flat-square
 [badge-doorman-coverage]: https://img.shields.io/codecov/c/github/FabricLabs/doorman.svg?style=flat-square
 [badge-http-status]: https://img.shields.io/travis/FabricLabs/fabric-http.svg?branch=master&style=flat-square
+[badge-hub-status]: https://img.shields.io/travis/FabricLabs/fabric-hub.svg?branch=master&style=flat-square
 [badge-http-coverage]: https://img.shields.io/codecov/c/github/FabricLabs/fabric-http.svg?style=flat-square
+[badge-hub-coverage]: https://img.shields.io/codecov/c/github/FabricLabs/fabric-hub.svg?style=flat-square
 [badge-matrix-status]: https://img.shields.io/travis/FabricLabs/fabric-matrix.svg?branch=master&style=flat-square
 [badge-matrix-coverage]: https://img.shields.io/codecov/c/github/FabricLabs/fabric-matrix.svg?style=flat-square
 [badge-twilio-status]: https://img.shields.io/travis/FabricLabs/fabric-twilio.svg?branch=master&style=flat-square

constants.js

@@ -18,6 +18,8 @@ const BITCOIN_GENESIS = '000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b
 const BITCOIN_GENESIS_ROOT = '4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b';
 const FABRIC_KEY_DERIVATION_PATH = "m/44'/7777'/0'/0/0";
 const FIXTURE_SEED = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+const FIXTURE_XPUB = 'xpub661MyMwAqRbcF6GygV6Q6XAg8dqhPvDuhYHGniequi6HMbYhNNH5XC13Np3qRANHVD2mmnNGtMGBfDT69s2ovpHLr7q8syoAuyWqtRGEsYQ';
+const FIXTURE_XPRV = 'xprv9s21ZrQH143K2cCWaTZPjPDwac1CzTW4LKMfzLFEMNZJUoDYppxpyPgZXY7CZkjefGJTrTyqKnMrM4RG6nGn7Q9cwjHggCtn3CdFGJahaWY';
 
 // Message Constants
 const MAGIC_BYTES = 0xC0D3F33D;
@@ -126,6 +128,8 @@ module.exports = {
   FABRIC_KEY_DERIVATION_PATH,
   FABRIC_USER_AGENT,
   FIXTURE_SEED,
+  FIXTURE_XPUB,
+  FIXTURE_XPRV,
   HEADER_SIZE,
   GENERIC_MESSAGE_TYPE,
   LOG_MESSAGE_TYPE,