Skip to content

Commit

Permalink
chore: updating readme and some further setups
Browse files Browse the repository at this point in the history
  • Loading branch information
ohager committed Jul 25, 2021
1 parent 3772ac7 commit 7e23d30
Show file tree
Hide file tree
Showing 5 changed files with 197 additions and 1,146 deletions.
4 changes: 4 additions & 0 deletions .husky/pre-push
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npm test
166 changes: 80 additions & 86 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
<img src="../assets/burstjs.png" alt="burstjs" width="600" align="middle" />
<img src="./assets/burstjs.png" alt="burstjs" width="600" align="middle" />

> The Signum Network Type/Javascript Reference Library
> The Signum Network SDK for Javascript (written in Typescript)
![npm](https://img.shields.io/npm/v/@signumjs/core.svg?style=flat)
[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lernajs.io/)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/81a6119af03d4a7e8a55c65999884709)](https://www.codacy.com/app/ohager/phoenix?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=burst-apps-team/phoenix&amp;utm_campaign=Badge_Grade)
[![Build](https://github.com/burst-apps-team/phoenix/workflows/Build%20SignumJS/badge.svg)](https://github.com/burst-apps-team/phoenix/actions?query=workflow%3A%22Build+BurstJS%22)
[![Known Vulnerabilities](https://snyk.io/test/github/burst-apps-team/phoenix/badge.svg?targetFile=lib%2Fpackage.json)](https://snyk.io/test/github/burst-apps-team/phoenix?targetFile=lib%2Fpackage.json)
[![codecov](https://codecov.io/gh/burst-apps-team/phoenix/branch/develop/graph/badge.svg)](https://codecov.io/gh/burst-apps-team/phoenix)
[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@signumjs/core/badge)](https://www.jsdelivr.com/package/npm/@signumjs/core)

`@signumjs` is a modern library written in Typescript providing common functionalities for _browsers_ and _nodejs_ to interact with the [Signum Network blockchain](https://signum.network/),
an advanced community-driven blockchain technology.
`@signumjs` is a modern SDK written in Typescript providing common functionalities for _browsers_ and _nodejs_ to
interact with the [Signum Network blockchain](https://signum.network/), an advanced community-driven blockchain
technology.

## Packages

The library is separated in the following packages
The SDK is separated in the following packages

- [@signumjs/core](./modules/core.html) The main package providing an extense API for blockchain interaction
- [@signumjs/contracts](./modules/contracts.html) A package providing Signum relevant functions for _smart contracts_
- [@signumjs/crypto](./modules/crypto.html) A package providing Signum relevant crypto functions
- [@signumjs/util](./modules/util.html) A package providing useful functions, e.g. common conversion functions
- [@signumjs/http](./modules/http.html) A package providing a _simplified_ Http layer, with consistent response types, and exception handling
- [@signumjs/monitor](./modules/monitor.html) A package providing a class to execute recurring async operations with de/serialization feature, good for listening to blockchain transactions

- [@signumjs/util](./modules/util.html) A package providing useful functions, e.g. common conversion functions
- [@signumjs/http](./modules/http.html) A package providing a _simplified_ Http layer, with consistent response types,
and exception handling
- [@signumjs/monitor](./modules/monitor.html) A package providing a class to execute recurring async operations with
de/serialization feature, good for listening to blockchain transactions

## Installation

`@signumjs` aims modern browsers and nodejs > v10, but can also be used as bundled JavaScript using `<script>`
`@signumjs` aims modern browsers and nodejs >= v14, but can also be used as bundled JavaScript using `<script>`

### Using with NodeJS and/or modern web frameworks

Expand All @@ -39,9 +39,9 @@ npm install @signumjs/contracts (optional)
npm install @signumjs/crypto (optional)
npm install @signumjs/util (optional)
npm install @signumjs/http (optional)
npm install @signumjs/monitor (optional)
```


or using [yarn](https://yarnpkg.com/):

``` yarn
Expand All @@ -50,15 +50,13 @@ yarn add @signumjs/contracts (optional)
yarn add @signumjs/crypto (optional)
yarn add @signumjs/util (optional)
yarn add @signumjs/http (optional)
yarn add @signumjs/monitor (optional)
```

> Usually, you won't need to install other packages than `@signumjs/core`, which uses the other packages.
### Using in classic `<script>`

Each package is available as bundled standalone library using UMD.
This way _SignumJS_ can be used also within `<script>`-Tags.
This might be useful for Wordpress and/or other PHP applications.
Each package is available as bundled standalone library using UMD. This way _SignumJS_ can be used also
within `<script>`-Tags. This might be useful for Wordpress and/or other PHP applications.

Just import one of the packages using the HTML `<script>` tag.

Expand All @@ -72,8 +70,9 @@ Just import one of the packages using the HTML `<script>` tag.

`<script src='https://cdn.jsdelivr.net/npm/@signumjs/util/dist/signumjs.util.min.js'></script>`

Due to the way a package is imported following global variables are provided
`<script src='https://cdn.jsdelivr.net/npm/@signumjs/monitor/dist/signumjs.monitor.min.js'></script>`

Due to the way a package is imported following global variables are provided

| Package | Variable |
|---------|----------|
Expand All @@ -89,7 +88,7 @@ Examples:
```js
// using core
const api = sig$.composeApi({
nodeHost: "http://testnet.signum.network",
nodeHost: "http://testnet.signum.network",
});

api.network.getBlockchainStatus().then(console.log);
Expand All @@ -111,121 +110,116 @@ console.log(sig$crypto.hashSHA256("test"))
const value = sig$util.Value.fromSigna("1000")
```

```js
```ts
// using http
const client = new sig$http.HttpClientFactory.createHttpClient('https://jsonplaceholder.typicode.com/');
client.get('/todos/1').then(console.log)
```

```js
```ts
// using monitor

// A method that checks if an account exists
// > IMPORTANT: Do not use closures, when you need to serialize the monitor
async function tryFetchAccount() {
const Api = composeApi({nodeHost: 'https://testnet.signum.network:6876/'})
try {
const {account} = await Api.account.getAccount('1234')
return account;
} catch (e) {
// ignore error
return null;
}
}

// A comparing function to check if a certain condition for the returned data from fetch function
// is true. If it's true the monitor stops
function checkIfAccountExists(account) {
return account !== null;
}

// Create your monitor
const monitor = new Monitor < Account > ({
asyncFetcherFn: tryFetchAccount,
compareFn: checkIfAccountExists,
intervalSecs: 10, // polling interval in seconds
key: 'monitor-account',
timeoutSecs: 2 * 240 // when reached timeout the monitor stops
})
.onFulfilled(() => {
// called when `checkIfAccountExists` returns true
console.log('Yay, account active');
})
.onTimeout(() => {
// called when `timeoutSecs` is reached
console.log('Hmm, something went wrong');
}).start();
```

// A method that checks if an account exists
// > IMPORTANT: Do not use closures, when you need to serialize the monitor
async function tryFetchAccount() {
try {
const api = composeApi({nodeHost: 'https://testnet.signum.network:6876/'})
const {account} = await api.account.getAccount('1234')
return account;
} catch (e) {
// ignore error
return null;
}
}

// A comparing function to check if a certain condition for the returned data from fetch function
// is true. If it's true the monitor stops
function checkIfAccountExists(account) {
return account !== null;
}

// Create your monitor
const monitor = new Monitor<Account>({
asyncFetcherFn: tryFetchAccount,
compareFn: checkIfAccountExists,
intervalSecs: 10, // polling interval in seconds
key: 'monitor-account',
timeoutSecs: 2 * 240 // when reached timeout the monitor stops
})
.onFulfilled(() => {
// called when `checkIfAccountExists` returns true
console.log('Yay, account active');
})
.onTimeout(() => {
// called when `timeoutSecs` is reached
console.log('Hmm, something went wrong');
}).start();
```

## Usage

The following example shows how to interact with the blockchain, i.e. getting the balance of a specific account


### ES6/NodeJS style

In a separate file, preferably `index.js` or `main.js` write your entry point like this:

```js
import {composeApi, ApiSettings} from '@signumjs/core'
import {convertNQTStringToNumber} from '@signumjs/util'

const apiSettings = new ApiSettings('http://at-testnet.burst-alliance.org:6876', 'burst');
const api = composeApi(apiSettings);
import {Amount} from '@signumjs/util'

// this self-executing file makes turns this file into a starting point of your app

(async () => {
try{
const {balanceNQT} = await api.account.getAccountBalance('13036514135565182944')
console.log(`Account Balance: ${Value.fromPlanck(balanceNQT).toString()}`)
}
catch(e){ // e is of type HttpError (as part of @signumjs/http)
console.error(`Whooops, something went wrong: ${e.message}`)
}
try {
const api = composeApi({nodeHost: 'https://testnet.burstcoin.network:6876'});
const {balanceNQT} = await api.account.getAccountBalance('13036514135565182944')
console.log(`Account Balance: ${Amount.fromPlanck(balanceNQT).toString()}`)
} catch (e) { // e is of type HttpError (as part of @signumjs/http)
console.error(`Whooops, something went wrong: ${e.message}`)
}
})()

```

### `<script>` style

```js
const apiSettings = new sig$.ApiSettings('http://at-testnet.burst-alliance.org:6876', 'burst');
const api = sig$.composeApi(apiSettings);


const api = sig$.composeApi({nodeHost: 'https://testnet.burstcoin.network:6876'});
api.account.getAccountBalance('13036514135565182944')
.then( balance => {
console.log(`Account Balance: ${sig$util.Value.fromPlanck(balance.balanceNQT).toString()}`)
.then(balance => {
console.log(`Account Balance: ${sig$util.Amount.fromPlanck(balance.balanceNQT).toString()}`)

})
.catch(e => { // e is of type HttpError (as part of @signumjs/http)
console.error(`Whooops, something went wrong: ${e.message}`)
console.error(`Whooops, something went wrong: ${e.message}`)
})

```

## Development

When contributing to the Phoenix wallet and updates in SignumJS are necessary, simply do
Contributors are warmly welcome. To start your local build just hit

```
npm install && npm run bootstrap
npm install
```

That's it!

## Building the packages

The SDK is using [Lerna](https://lerna.js.org/) to manage all subpackages in a developer friendlier way:

## Running Tests

1. Single test run `npm run test`
2. Run in watch mode `npm run test:watch`
3. Run end-to-end test `npm run test:e2e`
| Keep in mind that these tests are slow as they run against true servers. And therefore, it cannot be guaranteed that all E2E tests always work
2. Run in watch mode `npm run test:watch`
3. Run end-to-end test `npm run test:e2e`
| Keep in mind that these tests are slow as they run against true servers. And therefore, it cannot be guaranteed
that all E2E tests always work

## Documentation

- [SignumJS Online Documentation](https://burst-apps-team.github.io/phoenix/)
- [SignumJS Online Documentation](https://signum-network.github.io/signumjs/)
- To generate esdocs: `npm run doc`
- To update the README.md files: `lerna run readme`
Loading

0 comments on commit 7e23d30

Please sign in to comment.