interledgerjs / ilp-packet

Moved to monorepo in interledgerjs/interledgerjs

Interledger.js Monorepo

Packages

Payments

Name	Version	Description
@interledger/pay		Send payments over Interledger using STREAM
@interledger/stream-receiver		Simple & composable stateless STREAM receiver

Utilities

Name	Version	Description
ilp-logger		Debug logging utility for Interledger modules
ilp-packet		Serialization/deserialization utility for ILP packets
ilp-plugin		Connect to a local, open BTP server
ilp-plugin-btp		One plugin to rule them all
ilp-protocol-ccp		Serialization/deserialization for the CCP routing protocol
ilp-protocol-ildcp		Fetch asset and account details from a parent
ilp-protocol-stream		Reliably send streams of money and data over ILP
oer-utils		Tools for OER parsing and serialization

Installation

The monorepo is set up to use lerna and pnpm workspaces. To get started run the following:

1. pnpm install - pnpm will install the dependencies and do the necessary linking (no need to run lerna bootstrap).
2. pnpm build
3. pnpm test - This will run the tests in all the packages.

Running script commands

Script commands such as test and lint can be run from the root of the project by running:

# Run tests for all packages
pnpm test

# Run tests for a specific module a package
pnpm test --scope=<package-name>

Or in the package directory:

pnpm test

If you are interested in contributing, please read the contributing guidelines.

For Maintainers

Versioning

Independent versioning is used for this project and releases can only be made from master. You will need to set the GH_TOKEN env variable to your personal GitHub access token. Please make sure that you are up to date with master and that the tests and linting pass. Then use the following to create a release:

# On master
GH_TOKEN=<github-token> lerna version --conventional-commits --create-release github

and follow the command prompts. This will commit the package version changes and create the necessary tags - all of which will be pushed to master. It will also create changelogs and official GitHub releases.

If you want to release an alpha then run

# On master
GH_TOKEN=<github-token> lerna version --conventional-commits --conventional-prerelease --create-release github

This will append -alpha.<alpha-version> to the release name. The alpha release can be graduated (1.0.1-alpha.1 => 1.0.1) by running:

# On master
GH_TOKEN=<github-token> lerna version --conventional-commits --conventional-graduate --create-release github

Adding new packages

All source code is expected to be TypeScript and is placed in the src folder. Tests are put in the test folder. The NPM package will not contain any TypeScript files (*.ts) but will have typings and source maps. A typical project should have the following structure:

|-- src
|-- test
|-- package.json
|-- tsconfig.build.json

The tsconfig.build.json file should have the following

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "baseUrl": ".",
    "rootDir": "src",
    "outDir": "dist",
    "tsBuildInfoFile": "./dist/tsconfig.build.tsbuildinfo"
  },
  "include": [
    "src"
  ]
}

The package.json file should specify the following

{
  "name": "<package-name>",
  "license": "Apache-2.0",
  "publishConfig": {
    "access": "public"
  }
}

In the scripts section of the package.json, be sure to have build, cover (which runs tests with coverage) and codecov. These will be called from the CI pipeline. Please use the following as a guideline:

"scripts": {
  "build": "tsc -p tsconfig.build.json",
  "cover": "...",
  "codecov": "curl -s https://codecov.io/bash | bash -s - -s coverage -F <flagname>"
}

The cover script should run the tests with code coverage and output the coverage results in a format that can be uploaded to codecov. The flagname will be used by codecov to track coverage per package. Please make sure it matches the regex ^[a-z0-9_]{1,45}$.

Importing legacy modules

This process preserves the commit history of the legacy modules.

git clone [email protected]:adrianhopebailie/interledgerjs.git
git clone [email protected]:interledgerjs/legacy-module.git
cd legacy-module
git pull
cd ../interledgerjs
lerna import ../legacy-module --dest=packages --preserve-commit --flatten

You then need to replace the tsconfig.json file with the tsconfig.build.json and update the package.json as described above.

Dependencies

We keep devDependencies that are shared across all packages in the root package.json file. Dependencies can be added to individual packages using Lerna

lerna add <package to install> --scope=<package-name>

# Add dev dependency
lerna add <package to install> --scope=<package-name> --dev

Running script commands

Script commands such as test and lint can be run from the root of the project by running

# All tests in all packages
lerna run test

#Scoping to a package
lerna run test --scope=<package-name>

ilp-packet's Issues

consider moving typeString to a separate static function

for consistency with interledgerjs/btp-packet#4 (comment)

An in-range update of codecov is breaking the build 🚨

The devDependency codecov was updated from 3.1.0 to 3.2.0.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

codecov is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ ci/circleci: test: Your tests failed on CircleCI (Details).

---

Commits

The new version differs by 3 commits.

• e427d90 feat(services): add azure pipelines (#114)
• 023d204 Use small HTTP dependency (#110)
• 500f308 Update Readme

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

The name 'fulfillment' is ambiguous

In #17, a fulfillment packet was introduced, which can be used as a standard representation of the arbitrary transport-layer or application-layer data, that may be passed back from the receiver, along the payment path, to the sender.

However, in other contexts, the term 'fulfillment' is already used to refer to the preimage which unlocks the hashlock of a conditional transfer.

@justmoon Wouldn't 'serializeIlpFulfillmentData' be a better name than 'serializeIlpFulfillment'?

destinationAmount and destinationAccount

It might make more sense to change these fields from amount and account to destinationAmount and destinationAccount. Amount and account are only used in the Ledger Plugin Interface's transfer objects, which describe local transfers. Across all the other interledgerjs code, (quoting, payments, etc.) we use destinationAmount and destinationAccount. It might be clearer if we used the same field names here.

@justmoon @emschwartz

OER encoding of GeneralizedTime

Hi there,

I was looking through the implementation to see how the ASN.1 GeneralizedTime value is encoded for the quotes by liquidity response.
Concrete documentation of the ASN.1 spec seems hard to come by but from various sources it appears that most of the time portion is optional, including time zones
For example, the generalized time entry at wikipedia says

A GeneralizedTime is a time format in the ASN.1 notation. It consists of a string value representing the calendar date, as defined in ISO 8601, a time of day with an optional fractional seconds element and the optional local time differential factor as defined in ISO 8601.

Other documentation describes the format as:

Type GeneralizedTime takes values of the year, month, day, hour, time, minute,second, and second fraction in any of three forms.

• Local time only. ``YYYYMMDDHH[MM[SS[.fff]]]'', where the optional fff is accurate to three decimal places.
• Universal time (UTC time) only. ``YYYYMMDDHH[MM[SS[.fff]]]Z''.
• Difference between local and UTC times. ``YYYYMMDDHH[MM[SS[.fff]]]+-HHMM''.

This is echoed in ASN.1 — Communication Between Heterogeneous Systems (page 201) available at www.oss.com

A value of type GeneralizedTime is a character string of type VisibleString with one of the following lexical restrictions:
a ) a string of the form "AAAAMMJJhh[mm[ss[(.|,)ffff]]]" standing for a local time, four digits for the year, two for the month, two for the day and two for the hour (the value 24 is forbidden), followed by two digits for the minutes and two for the seconds if required, then a dot (or a comma), and a number for the fractions of second (the maximum precision depends on the application); or

b ) a string of a) followed by the letter "Z" (which would denote a UTC time); or

c ) a string of a) followed by a string "(+|-)hh[mm]"

These sources all seem to confirm more or less the same thing

• only YYYY MM DD and HH are mandatory
• the time portions HH SS and .ffff are optional
• the exact length of the fractional second is application specific
• time zone information is optional and could be 'Z' or HH or HHMM

Given all of this, i think the javascript implementation is incorrect, though my javascript is rusty.

It also makes me wonder whether it is preferable to use a more rigid format for date-time information, i will log a question for the RFC separately.

Run integration tests on this repo?

For a certain group of interledgerjs repos, the integration tests make sure that their master branches are always compatible with each other. Breaking changes to e.g. ilp-connector only pass those integration tests if they are done in a named branch, linked to corresponding changes in e.g. ilp-plugin-virtual where necessary.

IIUC, this repo is outside that group of linked repos, and a breaking change was just merged that makes this repo's master branch incompatible with the master branches of our reference stack? Is that intended behavior, or should we maybe configure integration tests on this repo as well?

Add function to parse any packet type

It should return the type and the deserialized contents

Use default values and validate parameters

If you don't specify all of the fields for a packet type when serializing you end up with unhelpful errors. This module should use default values where appropriate and throw specific errors when required fields are undefined.

An in-range update of @types/chai is breaking the build 🚨

The devDependency @types/chai was updated from 4.2.1 to 4.2.2.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

@types/chai is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ ci/circleci: test: Your tests failed on CircleCI (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Add a function to parse the account and amount without the data

Useful for connectors because the data isn't for them anyway, so there's no reason to touch it

GeneralizedTime is not C-OER compliant

Relevant to:
interledger/rfcs#440

See impl:
https://github.com/interledgerjs/ilp-packet/blob/master/src/utils/date.ts#L43

Considering:

> new Date().toISOString()
'2018-07-16T08:37:52.250Z'

Non significant 0s and decimal points should be stripped from the microseconds at the least ? ( at the least meaning I'm not entirely clear about all the rules, but have noticed some by playing briefly with the encoding features of ASN.1 studio from OSS.com )

ILP v1 compatible release

Hi, I cant see any comments on releases that indicate the different levels of compatibility with the various ILP versions? I need a v1 compatible ilp-packet but am not sure which version I should pull. It looks like master is implementing v4. Many thanks.

allow reading and writing extensions

IlpReject incompatible with ASN.1 definition

serializeIlpReject puts triggeredBy before the message, while the ASN.1 definition in interledger/rfcs#361 has the message first. Which one is correct?

Also, it would be useful for IlpPacket to export a separate interface for IlpReject (rather than just using IlpRejection).

should packet.data really be length-prefixed?

https://github.com/interledger/rfcs/blob/master/asn1/InterledgerPacket.asn#L43 says that the InterledgerPacket's data field should be "a length-prefixed header", and that seems to be what https://github.com/interledgerjs/ilp-packet/blob/master/index.ts#L22 does.

But when I read the ASN.1 without reading that comment, my interpretation is that PACKET.type is an ASN.1 OpenType of the PACKET CLASS, and although I couldn't really find a good reference on asn.1, from what I've read, I would expect PACKET.&Type ({PacketSet}{@type}) to just be replaceable with e.g. InterledgerProtocolPayment if typeId is 1?

cc @justmoon

see also interledgerjs/btp-packet#10

An in-range update of @types/node is breaking the build 🚨

The devDependency @types/node was updated from 10.11.0 to 10.11.1.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

@types/node is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ ci/circleci: test: Your tests failed on CircleCI (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

An in-range update of @types/mocha is breaking the build 🚨

The devDependency @types/mocha was updated from 5.2.6 to 5.2.7.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

@types/mocha is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ ci/circleci: test: Your tests failed on CircleCI (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

An in-range update of oer-utils is breaking the build 🚨

The dependency oer-utils was updated from 3.0.1 to 3.1.0.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

oer-utils is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Status Details

• ❌ ci/circleci: test: Your tests failed on CircleCI (Details).

---

Commits

The new version differs by 5 commits.

• 4a0fd30 3.1.0
• e0813c4 fix: reject variable integers of length zero
• 3cdb8ab chore: re-enable code coverage reporting
• c072342 chore: update dependencies
• f3dc629 feat: allow using JS numbers instead of BigNumbers

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Accept and return trailing bytes

Companion to interledgerjs/ilp-connector#405