Skip to content

Commit

Permalink
Merge pull request #61 from EOSIO/develop
Browse files Browse the repository at this point in the history
Release 4.0.1
  • Loading branch information
flux627 authored Mar 7, 2019
2 parents 50d9ec6 + 3d89ed2 commit b4fb0b8
Show file tree
Hide file tree
Showing 13 changed files with 1,045 additions and 738 deletions.
2 changes: 0 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# See https://help.github.com/ignore-files/ for more about ignoring files.

# dependencies
node_modules/

Expand Down
72 changes: 37 additions & 35 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -1,42 +1,44 @@
sudo: false
language: node_js
node_js:
- '10.0.0'
- 10.0.0
before_install:
- npm i -g [email protected]
- npm install -g typescript
- npm i -g [email protected]
- npm install -g typescript
stages:
- test
- name: publish-edge
if: (NOT type IN (pull_request)) AND (branch = develop)
- name: publish-latest
# Travis assigns the tag to branch for some reason. This matches any valid semver version.
if: branch =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
- test
- name: publish-edge
if: "(NOT type IN (pull_request)) AND (branch = develop)"
- name: publish-latest
if: branch =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
jobs:
include:
- stage: test
name: "Lint and Test"
script:
- npm run lint
- npm run test
- stage: publish-edge
name: "Publish @edge to NPM"
script:
- npm run build
deploy:
provider: script
skip_cleanup: true
script: ./scripts/publish-edge.sh
on:
branch: develop
- stage: publish-latest
name: "Publish @latest to NPM"
script:
- npm run build
deploy:
provider: script
skip_cleanup: true
script: ./scripts/publish-latest.sh
on:
all_branches: true
condition: $TRAVIS_TAG =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
- stage: test
name: Lint and Test
script:
- npm run lint
- npm run test
- stage: publish-edge
name: Publish @edge to NPM
script:
- npm run build
deploy:
provider: script
skip_cleanup: true
script: "./scripts/publish-edge.sh"
on:
branch: develop
- stage: publish-latest
name: Publish @latest to NPM
script:
- npm run build
deploy:
provider: script
skip_cleanup: true
script: "./scripts/publish-latest.sh"
on:
all_branches: true
condition: "$TRAVIS_TAG =~ ^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"
notifications:
webhooks:
secure: ji2Jmd5PZb0/4hTxcCPQDTaVVNWvY09VFN/q2jXxBlYd/h6QyXB4pDfEm+gm6O3kLMZrL/k+75HzlVf9UYRrHd1CO85Rj5nrqImgCwdxYbmPRnehdwgoAknz6+A8+CZRIphcxXyFKOw4Q5Fvs4WXlCu4vWeE/vbv1rY3bH22Iv8lmeddaAk5i61ReppZK+JiYXhSQwhpNWWWRpCFDw87jawujuXe3ToppSkJ0C3v/oaKg9+ngIbZ0skDqe2cD/Ia7AvSynyyemHRY3AJ/t+ekXAY3rnP4wvdMZ0A0mfRGOq2yzkZBtUa3vG4WrseoNz3K8z1uDDqQLEUEb14SitNd4NXIdYXEUG1suM0AoEszAjcDt7r3ddv7J6f3cJ8qxTLLXj6Qf7Ceee/AEU54CsJkIamG9PL2HQky4GnXsqNCOgpwivedYcFoEPiUmbz3Pcz8aR8LvnE7RH/IImUiMODhIwR0nMH6etARk+j3D5XyFeHzVkjYyg0P9gEo54vl/4T9Op4lQQJ63mqhPGvELNij5nrTLxIGSWsiz3LFn/ranDLUN1sSoCl8X3yXOWAfRxr/Q3Tg7/gvqLDov0HNfTXQ45cDuAVxP0SlZwwsqMYFAU0+rPd8alLEMVxhGztezfZNA2mYhs5bxofy83UpnkvR6t7gNuarW+UTJXQZRZtVzU=
150 changes: 150 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
# Contributing to demux-js-eos

Interested in contributing? That's awesome! Here are some guidelines to get started quickly and easily:

- [Contributing to demux-js-eos](#contributing-to-demux-js-eos)
- [Reporting An Issue](#reporting-an-issue)
- [Bug Reports](#bug-reports)
- [Feature Requests](#feature-requests)
- [Change Requests](#change-requests)
- [Working on demux-js-eos](#working-on-demux-js-eos)
- [Feature Branches](#feature-branches)
- [Submitting Pull Requests](#submitting-pull-requests)
- [Testing and Quality Assurance](#testing-and-quality-assurance)
- [Conduct](#conduct)
- [Contributor License & Acknowledgments](#contributor-license--acknowledgments)
- [References](#references)

## Reporting An Issue

If you're about to raise an issue because you think you've found a problem with demux-js-eos, or you'd like to make a request for a new feature in the codebase, or any other reason… please read this first.

The GitHub issue tracker is the preferred channel for [bug reports](#bug-reports), [feature requests](#feature-requests), and [submitting pull requests](#submitting-pull-requests), but please respect the following restrictions:

* Please **search for existing issues**. Help us keep duplicate issues to a minimum by checking to see if someone has already reported your problem or requested your idea.

* Please **be civil**. Keep the discussion on topic and respect the opinions of others. See also our [Contributor Code of Conduct](#conduct).

### Bug Reports

A bug is a _demonstrable problem_ that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!

Guidelines for bug reports:

1. **Use the GitHub issue search** — check if the issue has already been
reported.

1. **Check if the issue has been fixed** — look for [closed issues](https://github.com/EOSIO/demux-js-eos/issues?q=is%3Aissue+is%3Aclosed) or try to reproduce it
using the latest `develop` branch.

A good bug report shouldn't leave others needing to chase you up for more information. Be sure to include the details of your environment and relevant tests that demonstrate the failure.

[Report a bug](https://github.com/EOSIO/demux-js-eos/issues/new?title=Bug%3A)

### Feature Requests

Feature requests are welcome. Before you submit one be sure to have:

1. **Use the GitHub search** and check the feature hasn't already been requested.
1. Take a moment to think about whether your idea fits with the scope and aims of the project.
1. Remember, it's up to *you* to make a strong case to convince the project's leaders of the merits of this feature. Please provide as much detail and context as possible, this means explaining the use case and why it is likely to be common.

### Change Requests

Change requests cover both architectural and functional changes to how demux-js-eos works. If you have an idea for a new or different dependency, a refactor, or an improvement to a feature, etc - please be sure to:

1. **Use the GitHub search** and check someone else didn't get there first
1. Take a moment to think about the best way to make a case for, and explain what you're thinking. Are you sure this shouldn't really be
a [bug report](#bug-reports) or a [feature request](#feature-requests)? Is it really one idea or is it many? What's the context? What problem are you solving? Why is what you are suggesting better than what's already there?

## Working on demux-js-eos

Code contributions are welcome and encouraged! If you are looking for a good place to start, check out the [good first issue](https://github.com/EOSIO/demux-js-eos/labels/good%20first%20issue) label in GitHub issues.

Also, please follow these guidelines when submitting code:

### Feature Branches

To get it out of the way:

- **[develop](https://github.com/EOSIO/demux-js-eos/tree/develop)** is the development branch. All work on the next release happens here so you should generally branch off `develop`. Do **NOT** use this branch for a production site.
- **[master](https://github.com/EOSIO/demux-js-eos/tree/master)** contains the latest release of demux-js-eos. This branch may be used in production. Do **NOT** use this branch to work on demux-js-eos's source.

### Submitting Pull Requests

Pull requests are awesome. If you're looking to raise a PR for something which doesn't have an open issue, please think carefully about [raising an issue](#reporting-an-issue) which your PR can close, especially if you're fixing a bug. This makes it more likely that there will be enough information available for your PR to be properly tested and merged.

### Testing and Quality Assurance

Never underestimate just how useful quality assurance is. If you're looking to get involved with the code base and don't know where to start, checking out and testing a pull request is one of the most useful things you could do.

Essentially, [check out the latest develop branch](#working-on-demux-js-eos), take it for a spin, and if you find anything odd, please follow the [bug report guidelines](#bug-reports) and let us know!

## Conduct

While contributing, please be respectful and constructive, so that participation in our project is a positive experience for everyone.

Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members

Examples of unacceptable behavior include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others’ private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting

## Contributor License & Acknowledgments

This repository contains a notice of a license (MIT), and in accordance with [GitHub’s Terms of Service](https://help.github.com/articles/github-terms-of-service/), whenever you make a contribution to this project, you license your contribution under the same terms, and you agree that you have the right to license your contribution under those terms.

Whenever you make a contribution to this project, you also certify in the terms of the Developer’s Certificate of Origin set out below:

```
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```

## References

* Overall CONTRIB adapted from https://github.com/mathjax/MathJax/blob/master/CONTRIBUTING.md
* Conduct section adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2018-2019 block.one

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
90 changes: 76 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ npm install demux-eos --save

## Usage

This library provides two Action Reader implementations for reading from EOSIO blockchains: `NodeosActionReader` and `MongoActionReader`. **It is currently recomended to use the `MongoActionReader` due to performance and the ability to read inline and deferred actions.**
This library provides three Action Reader implementations for reading from EOSIO blockchains: `NodeosActionReader`, `MongoActionReader`, and `StateHistoryPostgresActionReader`. **It is currently recomended to use the `MongoActionReader` due to performance and the ability to read inline and deferred actions.**

### MongoActionReader

Expand Down Expand Up @@ -54,13 +54,75 @@ const { MongoActionReader } = require("demux-eos")
// See supported Action Handlers here: https://github.com/EOSIO/demux-js#class-implementations
const actionHandler = ...

const actionReader = new MongoActionReader(
"mongo://...", // mongoEndpoint: the url of the mongodb instance
1234, // startAtBlock: the first block relevant to our application
false, // onlyIrreversible: whether or not to only process irreversible blocks
600, // the maximum history length
"EOS", // name of the database
const actionReader = new MongoActionReader({
startAtBlock: 1234, // startAtBlock: the first block relevant to our application
onlyIrreversible: false, // onlyIrreversible: whether or not to only process irreversible blocks
dbName: "EOS", // name of the database
mongoEndpoint: "mongo://...", // mongoEndpoint: the url of the mongodb instance
})

const actionWatcher = new BaseActionWatcher(actionReader, actionHander, 500)

// This must be done before calling watch so the MongoDB connection can be made
actionReader.initialize().then(() =>
actionWatcher.watch()
)
```

### StateHistoryPostgresActionReader

Reads from a Postgres instance when nodeos is configured to use the State History Plugin as well as the [fill-postgresql](https://github.com/EOSIO/fill-postgresql) tool.

#### Setup

To use the `StateHistoryPostgresActionReader`, you must first make sure that your environment is properly configured, as it otherwise may yield unpredictable or incorrect results. To set up a proper environment, make sure the following are true:

- You are running a producing node.

- You are running a second node with the state history plugin enabled.
- Is not producing blocks
- Is connected to the node(s) producing blocks via the `p2p-peer-address` configuration
- `--disable-replay-opts` set via CLI.
- `--plugin eosio::state_history_plugin` set via CLI.
- `--trace-history` set via CLI.
- `--chain-state-history` set via CLI.
- `--state-history-endpoint \"0.0.0.0:<preferred_port>\"` set via CLI.

- You are running fill-postgresql.
- `--endpoint=<ip_of_above_node:port_specified>` set via CLI.
- `--schema=<preferred_schema>` set via CLI.
- `--drop` set via CLI. This will cleanup any existing tables.
- `--create` set via CLI. This will create the schema/tables as needed.

This means that in a development environment, you will need to set up at least two Nodeos instances: one to produce blocks, and a peer with the State History plugin activated to populate the Postgresql instance.

#### Inline and Deferred Actions

Unlike the `NodeosActionReader`, inline and deferred actions are able to be captured and passed on to the Action Handler. Additionally, each Action has a `notifiedAccounts` property that lists all accounts notified of the blockchain action (this information is also not available via the `NodeosActionReader`).

#### Example

```javascript
const { BaseActionWatcher } = require("demux")
const { StateHistoryPostgresActionReader } = require("demux-eos")

// See supported Action Handlers here: https://github.com/EOSIO/demux-js#class-implementations
const actionHandler = ...

const massiveConfig = {
host: 'localhost',
port: 5432,
database: 'chain',
user: 'postgres',
password: 'postgres'
}

const actionReader = new StateHistoryPostgresActionReader({
startAtBlock: 1234, // startAtBlock: the first block relevant to our application
onlyIrreversible: false, // onlyIrreversible: whether or not to only process irreversible blocks
dbSchema: "chain", // name of the database
massiveConfig, // provides config to internal massivejs instance.
})

const actionWatcher = new BaseActionWatcher(actionReader, actionHander, 500)

Expand All @@ -70,6 +132,7 @@ actionReader.initialize().then(() =>
)
```


### NodeosActionReader

Makes requests directly to a specified Nodeos API endpoint to obtain block data.
Expand All @@ -82,17 +145,16 @@ All that is required is a running Nodeos instance that has the `chain_api_plugin

```javascript
const { BaseActionWatcher } = require("demux")
const { MongoActionReader } = require("demux-eos")
const { NodeosActionReader } = require("demux-eos")

// See supported Action Handlers here: https://github.com/EOSIO/demux-js#class-implementations
const actionHandler = ...

const actionReader = new MongoActionReader(
"http://...", // mongoEndpoint: the url of the Nodeos API
1234, // startAtBlock: the first block relevant to our application
false, // onlyIrreversible: whether or not to only process irreversible blocks
600, // the maximum history length
)
const actionReader = new NodeosActionReader({
startAtBlock: 1234, // startAtBlock: the first block relevant to our application
onlyIrreversible: false, // onlyIrreversible: whether or not to only process irreversible blocks
nodeosEndpoint: "http://...", // mongoEndpoint: the url of the Nodeos API
})

const actionWatcher = new BaseActionWatcher(actionReader, actionHander, 500)

Expand Down
Loading

0 comments on commit b4fb0b8

Please sign in to comment.