# simple-hypercore-protocol

> Hypercore protocol state machine

Latest version **2.1.2** (published 2021-08-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-hypercore-protocol
pnpm add simple-hypercore-protocol
yarn add simple-hypercore-protocol
bun add simple-hypercore-protocol
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.2 |
| Published | 2021-08-31 |
| First published | 2019-08-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 55.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 29 |
| Author | Mathias Buus |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/simple-hypercore-protocol
- Repository: https://github.com/mafintosh/simple-hypercore-protocol
- Issues: https://github.com/mafintosh/simple-hypercore-protocol/issues
- npm.io page: https://npm.io/package/simple-hypercore-protocol

## Dependencies (7)

- [varint](https://npm.io/package/varint.md) ^5.0.0
- [noise-protocol](https://npm.io/package/noise-protocol.md) ^3.0.1
- [hypercore-crypto](https://npm.io/package/hypercore-crypto.md) ^2.1.0
- [simple-handshake](https://npm.io/package/simple-handshake.md) ^3.0.0
- [xsalsa20-universal](https://npm.io/package/xsalsa20-universal.md) ^1.0.0
- [simple-message-channels](https://npm.io/package/simple-message-channels.md) ^1.2.1
- [protocol-buffers-encodings](https://npm.io/package/protocol-buffers-encodings.md) ^1.1.0

## Recent versions

- 2.1.2 (latest) — 2021-08-31
- 2.1.1 — 2020-09-24
- 2.1.0 — 2020-07-01
- 2.0.1 — 2020-05-16
- 2.0.0 — 2020-05-13
- 1.5.0 — 2020-02-04
- 1.4.0 — 2019-11-13
- 1.3.1 — 2019-10-12
- 1.3.0 — 2019-10-11
- 1.2.1 — 2019-10-08
- 1.2.0 — 2019-10-08
- 1.1.3 — 2019-09-23
- 1.1.2 — 2019-09-12
- 1.1.0 — 2019-09-11
- 1.0.1 — 2019-09-10
- … 2 more at https://npm.io/package/simple-hypercore-protocol/versions

## README

# simple-hypercore-protocol

Hypercore protocol state machine

```
npm install simple-hypercore-protocol
```

Includes a Noise handshake, and is not backwards compatible with Hypercore <= 7

## Usage

``` js
const Protocol = require('simple-hypercore-protocol')

const a = new Protocol(true, {
  send (data) { // send hook should send data
    b.recv(data)
  }
})

const b = new Protocol(false, {
  onrequest (channel, message) {
    console.log('got request message', message, 'on channel', channel)
  },
  send (data) {
    a.recv(data)
  }
})

// send a request message on channel 10
a.request(10, {
  index: 42
})
```

## API

This is still a work in progress, so that messages supported might change.
See the schema.proto file for the schema for each message.

#### `p = new Protocol(isInitator, handlers)`

Create a new protocol state machine.

* `isInitator` is a boolean indicating if you are a client or server
* `handlers` is a series of functions handling incoming messages

Everytime a binary message should be sent to another peer,
`handlers.send(data)` is invoked.

If there is a critical error, `handlers.destroy(err)` is called.

After the initial handshake transport encryption is enabled,
to ensure your stream is private.

To disable transport encryption set `handlers.encrypted = false`.

To disable the NOISE handshake set `handlers.noise = false` (works only when `encrypted` is also set to false).

#### `p.recv(data)`

Call this with incoming data.

#### `buf = p.remoteCapability(key)`

Create a remote capability for a key. Use this to verify
if a remote indeed had a key when you get an `open` message.

#### `buf = p.capability(key)`

Create a local capability.

#### `p.destroy(err)`

Destroy the protocol state machine.

#### `p.publicKey`

The local public key used for authentication.

#### `p.remotePublicKey`

The remotes public key.

#### `p.handshakeHash`

The noise handshake hash which uniquely identifies the noise session.

http://noiseprotocol.org/noise.html#channel-binding

#### `handlers.onauthenticate(remotePublicKey, done)`

Called when you should authenticate a remote public key.

#### `handlers.onhandshake()`

Called when the initial protocol handshake has finished.

#### `p.open(channel, message)`

Send an open message on a channel.

Note that if you message.key the protocol, will turn that into a capability that is sent instead of the key.

Receiving an open message triggers `handlers.onopen(channel, message)`

#### `p.options(channel, message)`

Send a options message on a channel.

Receiving a handshake message triggers `handlers.onoptions(channel, message)`

#### `p.status(channel, message)`

Send a status message on a channel.

Receiving a info message triggers `handlers.onstatus(channel, message)`

#### `p.have(channel, message)`

Send a have message on a channel.

Receiving a have message triggers `handlers.onhave(channel, message)`

#### `p.unhave(channel, message)`

Send an unhave message on a channel.

Receiving an unhave message triggers `handlers.onunhave(channel, message)`

#### `p.want(channel, message)`

Send a want message on a channel.

Receiving a want message triggers `handlers.onwant(channel, message)`

#### `p.unwant(channel, message)`

Send an unwant message on a channel.

Receiving an unwant message triggers `handlers.onunwant(channel, message)`

#### `p.request(channel, message)`

Send a request message on a channel.

Receiving a request message triggers `handlers.onrequest(channel, message)`

#### `p.cancel(channel, message)`

Send a cancel message on a channel.

Receiving a cancel message triggers `handlers.oncancel(channel, message)`

#### `p.data(channel, message)`

Send a data message on a channel.

Receiving a data message triggers `handlers.ondata(channel, message)`

#### `keyPair = Protocol.keyPair([seed])`

Static function to generate a Noise key pair, optionally from a seed.

## License

MIT

---
_Source: https://npm.io/package/simple-hypercore-protocol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._