Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
122 lines (93 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

122 lines (93 loc) · 4.15 KB
Raw

Contributing

Thank you for contributing to the Liquid Asset Registry.

Before You Start

  • Search existing issues and pull requests before opening a duplicate.
  • Use an issue to discuss substantial behavior or API changes before investing in an implementation.
  • Report vulnerabilities privately according to SECURITY.md.

Development Setup

The service requires Python 3.11 or newer and PostgreSQL 16. The SDK requires Node.js 18.18 or newer. The locked development and production dependencies are resolved for Python 3.12, which matches the container image and CI, so use Python 3.12 for local development.

Install the Python development dependencies:

python3.12 -m venv .venv
.venv/bin/python -m pip install --require-hashes -r requirements-dev.txt
.venv/bin/python -m pip install --no-deps -e .

requirements.txt is the fully pinned, hash-verified production dependency lock used by the container build. After changing runtime dependencies in pyproject.toml, regenerate it and the development lock with:

uv pip compile pyproject.toml --python-platform x86_64-manylinux_2_28 \
  --generate-hashes --python-version 3.12 --upgrade --output-file requirements.txt
uv pip compile pyproject.toml --extra dev --constraint requirements.txt \
  --python-platform x86_64-manylinux_2_28 --generate-hashes --python-version 3.12 \
  --upgrade --output-file requirements-dev.txt

requirements-dev.txt includes the production pins plus the development tools, with hashes for every dependency. The remote signer example has its own runtime inputs in sdk/examples/remote-signer/requirements.in, used by its container image, and test inputs in requirements-dev.in. Regenerate both locks with:

uv pip compile sdk/examples/remote-signer/requirements.in \
  --python-platform x86_64-manylinux_2_28 --generate-hashes --python-version 3.11 \
  --upgrade --output-file sdk/examples/remote-signer/requirements.txt
uv pip compile sdk/examples/remote-signer/requirements-dev.in \
  --constraint sdk/examples/remote-signer/requirements.txt \
  --python-platform x86_64-manylinux_2_28 --generate-hashes --python-version 3.11 \
  --upgrade --output-file sdk/examples/remote-signer/requirements-dev.txt

Start PostgreSQL and apply migrations:

docker compose up -d postgres
ASSET_REGISTRY_DATABASE_URL=postgresql+psycopg://asset_registry:asset_registry@127.0.0.1:5433/asset_registry \
  .venv/bin/alembic upgrade head

Install SDK dependencies when working under sdk/:

cd sdk
npm ci

Making Changes

  • Keep changes focused and include tests for changed behavior.
  • Use wallycore for supported Liquid transaction, serialization, hashing, signing, and signature-verification primitives.
  • Treat FastAPI and Pydantic as the OpenAPI source of truth. Do not edit openapi.yaml or generated SDK declarations manually.
  • Add database schema changes as Alembic migrations. Keep revision identifiers at most 32 characters.
  • Do not commit credentials, private keys, local environment files, or data containing private information.

After changing routes, schemas, examples, or API metadata, regenerate the OpenAPI snapshot and SDK types:

.venv/bin/python scripts/generate_openapi.py
cd sdk
npm run generate:types

Checks

Run the Python checks from the repository root:

.venv/bin/ruff check registry_api tests
ASSET_REGISTRY_TEST_DATABASE_URL=postgresql+psycopg://asset_registry:asset_registry@127.0.0.1:5433/asset_registry \
  .venv/bin/pytest
.venv/bin/python scripts/generate_openapi.py --check

Run the SDK checks from sdk/:

npm run check
npm run build

The SDK check includes npm audit --audit-level=high. Update and commit the lockfile when a patched transitive dependency is available.

If a check is not applicable or cannot run in your environment, explain that in the pull request.

Pull Requests

Describe the problem, the chosen approach, compatibility or migration effects, and how you tested the change. Update user-facing documentation with behavior changes and keep generated artifacts in sync.

By contributing, you agree that your contributions are licensed under the repository's MIT License.