Nearly Perfect Mediocracy

    This package has been deprecated

    Author message:

    Please use ilp-connector instead

    five-bells-connector

    9.2.1 • Public • Published

    Five Bells Connector npm circle codecov

    A reference implementation of the Five Bells Connector API

    Usage

    You can see the connector in action as part of the five-bells-demo!

    To run the connector as a standalone server, follow these directions.

    Note: You need two five-bells-ledger instances to trade between.

    Step 1: Clone repo

    git clone https://github.com/interledger/five-bells-connector.git
     
    cd five-bells-connector

    Step 2: Install dependencies

    npm install

    Step 3: Run it!

    npm start

    Configuration

    General

    • CONNECTOR_BIND_IP (default: 0.0.0.0) IP that Five Bells Connector will bind to.
    • CONNECTOR_PORT (default: 4000) Port that Five Bells Connector will listen on.
    • CONNECTOR_HOSTNAME (default: [your hostname]) Publicly visible hostname. This is important for things like generating globally unique IDs. Make sure this is a hostname that all your clients will be able to see. The default should be fine for local testing.
    • CONNECTOR_PUBLIC_PORT (default: $PORT) Publicly visible port. You can set this if your public port differs from the listening port, e.g. because the connector is running behind a proxy.
    • CONNECTOR_PUBLIC_HTTPS (default: '') Whether or not the publicly visible instance of Five Bells Connector is using HTTPS.
    • CONNECTOR_LOG_LEVEL (default: info) the allowed levels in order of verbosity are fatal, error, warn, info, debug, and trace

    Trading

    • CONNECTOR_LEDGERS (default: []) Ledgers where this connector has accounts. Used to auto-generate CONNECTOR_PAIRS.
    [
      "USD@example.usd-ledger.",
      "EUR@example.eur-ledger."
    ]
    • CONNECTOR_CREDENTIALS (default: {}) Connector's login credentials for various ledgers, ex.
    {
      // Using Basic Auth
      "<ledger_address>": {
        "account": "...",
        "username": "...",
        "password": "..."
        "ca": "...", // Optional
      },
     
      // Using Client Certificate Auth
      "<ledger_address_2>": {
        "account": "...",
        "username": "...",
        "cert": "...",
        "key": "...",
        "ca": "...", // Optional
      }
    }
    • CONNECTOR_PAIRS (default: [all possible combinations]) Pairs to trade on, ex.
    [
      [
        'USD@example.ledger1.',
        'EUR@example.ledger2.'
      ],[
        'EUR@example.ledger2.',
        'USD@example.ledger1.'
      ]
    ]
    • CONNECTOR_NOTIFICATION_VERIFY (default: 'true' if NODE_ENV=production else false) The connector verifies signatures on notifications.
    • CONNECTOR_NOTIFICATION_KEYS (default: none) The paths to files with the public key in PEM format to verify ledgers' notification signatures. Required if CONNECTOR_NOTICATION_VERIFY='true' ex.
    {
      "<ledger_uri": "<path-to-file>"
    }
    • CONNECTOR_FX_SPREAD (default: 0.002 =.2%) How much of a spread to add on top of the reference exchange rate. This determines the connector's margin.
    • CONNECTOR_SLIPPAGE (default: 0.001 = 0.1%) The ratio for overestimating exchange rates to prevent payment failure if the rate changes.
    • CONNECTOR_MIN_MESSAGE_WINDOW (default: 1) Minimum time the connector wants to budget for getting a message to the ledgers its trading on. In seconds.
    • CONNECTOR_MAX_HOLD_TIME (default: 10) Maximum duration (seconds) the connector is willing to place funds on hold while waiting for the outcome of a transaction.
    • CONNECTOR_AUTH_CLIENT_CERT_ENABLED (default 0) whether or not to enable TLS Client Certificate authentication (requires HTTPS).
    • CONNECTOR_USE_HTTPS (default 0) whether or not to run the server using HTTPS.
    • CONNECTOR_TLS_KEY (default: none) the path to the server private key file. Required if using HTTPS.
    • CONNECTOR_TLS_CERTIFICATE (default: none) the path to the server certificate file. Required if using HTTPS.
    • CONNECTOR_TLS_CRL (default: none) the path to the server certificate revokation list file. Optional if using HTTPS.
    • CONNECTOR_TLS_CA (default: none) the path to a trusted certificate to be used in addition to using the default list. Optional if using HTTPS.
    • CONNECTOR_ROUTE_BROADCAST_ENABLED (default: 1) whether or not to broadcast known routes.
    • CONNECTOR_ROUTE_BROADCAST_INTERVAL (default: 30000) the frequency at which the connector broadcasts its routes to adjacent connectors.
    • CONNECTOR_ROUTE_CLEANUP_INTERVAL (default: 1000) the frequency at which the connector checks for expired routes.
    • CONNECTOR_ROUTE_EXPIRY (default: 45000) the maximum age of a route.

    Running with Docker

    This project can be run in a Docker container.

    docker run -it --rm -e CONNECTOR_PORT=4000 interledger/five-bells-connector

    Breaking down that command:

    • -it Run Five Bells Connector in an interactive terminal.
    • --rm Delete container when it's done running.
    • -e CONNECTOR_PORT=4000 Set the connector's port to 4000. This is just an example for how to set a config option.

    Payments

    The connector will facilitate an interledger payment upon receiving a notification for a transfer in which it is credited. That "source" transfer must have a ilp_header in its credit's memo that specifies the payment's destination and amount. As soon as the source transfer is prepared, the connector will authorize the debits from its account(s) on the destination ledger.

    Install

    npm i five-bells-connector

    DownloadsWeekly Downloads

    3

    Version

    9.2.1

    License

    ISC

    Last publish

    Collaborators

    • interledger