PayString Reference Implementation

PayString is a universal payment identifier. This repository serves as the reference implementation server for the PayString Protocol and the PayString API.

It is built using TypeScript, a Node.js HTTP server, and a PostgreSQL database. The implementation provides two distinct API surfaces:

1. Public API: Conforms to the PayString Protocol and is hosted on port 8080 by default.
2. Admin API: A RESTful API for CRUD (Create/Read/Update/Delete) operations to manage PayStrings and associated addresses, hosted on port 8081 by default.

To experiment with the PayString implementation, you can spin up a local environment using Docker. This will start both a PostgreSQL database and the PayString server inside Docker containers.

Run the following command in your terminal:

npm run devEnvUp

To stop and remove the Docker containers created by the development commands, run:

npm run devDown

If you are working directly on the PayString server source code and want to develop against a local database, you can start a PostgreSQL database in a Docker container and run a local PayString server using:

npm run devDbUp

The database schema is modeled using the Account and Address interfaces.

An Account represents a user identity within the system, uniquely identified by a payId.

An Address represents a specific payment destination linked to an Account. Addresses are categorized by a paymentNetwork and can contain either CryptoAddressDetails or FiatAddressDetails within the details field. Addresses can also be associated with an identityKeySignature for verified identities.

To set up and run the PayID server and its required Postgres database locally, use the following commands. This builds the image locally from the provided Dockerfile rather than pulling it from Docker Hub.

export PAYID_DOCKER_IMAGE_VERSION=$(node -p "require('./package.json').version")
docker-compose up -d --build

The nyc.config.js file defines the configuration for code coverage reporting using nyc. Key settings include:

• extension: Specifies the file extensions to be processed (e.g., ['.ts', '.tsx']).
• include: Defines the glob patterns for files to include in coverage (e.g., ['src/**/*.ts']).
• all: When set to true, instruments all files in the project, not just those touched by the test suite.
• watermarks: Sets the thresholds for color highlighting in coverage reports. Values are defined as [low, high]. For example, [80, 95] means coverage between 80% and 95% is yellow, $\ge$ 95% is green, and < 80% is red.

module.exports = {
  extension: ['.ts', '.tsx'],
  include: ['src/**/*.ts'],
  all: true,
  watermarks: {
    lines: [80, 95],
    functions: [80, 95],
    branches: [80, 95],
    statements: [80, 95],
  },
}

The db service (Postgres) uses the following environment variables for configuration:

• POSTGRES_PASSWORD: The mandatory password for the database. If changed, DB_PASSWORD in the payid_server service must be updated to match.
• POSTGRES_DB: The name of the database to create. If changed, DB_NAME in the payid_server service should be updated to match.
• POSTGRES_USER: (Optional) The database user. If changed, DB_USERNAME in the payid_server service must be updated to match. Defaults to postgres.

Use these environment variables to control the network interfaces and API versions for the PayID server.

Application Settings

• PUBLIC_API_PORT: Port for the Public API (default: 8080)
• PRIVATE_API_PORT or ADMIN_API_PORT: Port for the Admin API (default: 8081)
• LOG_LEVEL: Logging verbosity (default: INFO)

API Versions

The server uses the latest available versions defined in the source code:

• PayID Protocol Version: Uses the latest version from payIdServerVersions (currently 1.1).
• Admin API Version: Uses the latest version from adminApiVersions (currently 2020-08-25).

PayID supports reporting metrics to a Prometheus push gateway. Use these variables to manage metric collection and reporting.

Metrics Settings

• PUSH_PAYID_METRICS: Set to true to enable reporting. Defaults to true if unset.
• PAYID_DOMAIN: The domain name operating this PayID server. Required for pushing metrics. If unset, it is dynamically set by incoming requests.
• PUSH_GATEWAY_URL: The URL of the Prometheus push gateway (default: https://push00.mon.payid.tech/).
• PUSH_METRICS_INTERVAL: Frequency in seconds to push metrics to the gateway (default: 15).
• PAYID_COUNT_REFRESH_INTERVAL: Frequency in seconds to refresh PayID Count report data from the database (default: 60).

The payid_server service uses several environment variables to connect to the database. Ensure these are synchronized with the db service settings:

• DB_PASSWORD: Must match the POSTGRES_PASSWORD value in the db service.
• DB_HOSTNAME: The hostname of the database service (defaults to db).
• DB_NAME: (Optional) Uncomment to specify a custom database name if POSTGRES_DB in the db service is changed.
• DB_USERNAME: (Optional) Uncomment to specify a custom database user if POSTGRES_USER in the db service is changed. DB_USERNAME and POSTGRES_USER must have the same values.

Use urlToPayId to convert a PayID represented as an HTTP/HTTPS URL (e.g., https://host.com/user) into its compact user$host string representation.

Requirements:

• The URL must use http:// or https:// protocols.
• The URL must contain only ASCII characters.
• The URL must have exactly one path segment representing the user (e.g., /user). Multiple path segments (e.g., /path/user) are not allowed.

Errors: If the URL is invalid, the function throws a ParseError with ParseErrorType.InvalidPayId.

import { urlToPayId } from './services/urls';

const payId = urlToPayId('https://example.com/alice');
// returns 'alice$example.com'