# Fairmint DAML contracts

This repository contains Fairmint's DAML contract packages and publishes their generated JavaScript
bindings as [`@fairmint/daml-js`](https://www.npmjs.com/package/@fairmint/daml-js).

The package covers:

- Canton payment streams
- OCF reporting contracts
- CIP-0112 equity tokens, OTC settlement, and clearing
- NFT API and reference contracts
- test-token helpers used by integrations

The Open Cap Table Protocol contracts are intentionally separate. Install
[`@fairmint/open-captable-protocol-daml-js`](https://www.npmjs.com/package/@fairmint/open-captable-protocol-daml-js)
for `Fairmint.OpenCapTable` and `OCP_TEMPLATES`; their source is in
[`Fairmint/open-captable-protocol-daml`](https://github.com/Fairmint/open-captable-protocol-daml).

## Developer documentation

- [Fairmint DAML contract map](https://github.com/Fairmint/dev-docs/blob/main/docs/onchain/canton/daml-contracts.md)
- [Developing DAML packages](https://github.com/Fairmint/dev-docs/blob/main/docs/development/daml-packages.md)
- [Releasing and deploying DAML packages](https://github.com/Fairmint/dev-docs/blob/main/operations/daml-package-releases.md)

The GitHub wiki is retired (disabled). Those hubs are canonical.

## Install

```bash
npm install @fairmint/daml-js
```

The package declares the DAML JavaScript runtime versions that its generated bindings use. Keep
`@daml/ledger` and `@daml/types` compatible with the peer dependency versions reported by npm.

## Package surface

The browser-safe root entry point exports generated namespaces including:

```ts
import { CantonPayments, Fairmint, Nft } from '@fairmint/daml-js';

const registryTemplate = Fairmint.EquityTokens.EquityRegistry.EquityRegistry;
const paymentFactoryTemplate =
  CantonPayments.PaymentStream.PaymentStreamFactory.PaymentStreamFactory;
const nftInterface = Nft.Api.V1.Nft.Nft;
```

The exact module names are generated from the DAML source. Let TypeScript discover the available
templates from the installed package instead of copying package IDs into application code.

Deployed singleton IDs are available through stable JSON subpaths:

```ts
import paymentStreamsFactory from '@fairmint/daml-js/paymentStreams-factory-contract-id.json';
import reportsFactory from '@fairmint/daml-js/reports-factory-contract-id.json';
```

Check [`package.json`](./package.json) for the complete export map. The generated package surface is
also enforced by [`scripts/test-imports.ts`](./scripts/test-imports.ts) and
[`scripts/verify-merged-lib-runtime.ts`](./scripts/verify-merged-lib-runtime.ts).

## Repository layout

- `multi-package.yaml` declares the active package build graph.
- Each package's `daml.yaml` is the source of truth for its current name, version, SDK, and DAML
  dependencies.
- `scripts/` contains code generation, package verification, DAR policy, and deployment tooling.
- `dars/` and `dars/dars.lock` retain backed-up DARs and their integrity metadata.
- `generated/` and `lib/` are produced by the build and packaging pipeline; do not treat them as
  hand-maintained documentation.

## Build and validate

Install dependencies and the DAML SDK versions selected by the package manifests:

```bash
npm install
npx canton-dev-tools install-dpm-sdks
```

The normal local validation path is:

```bash
npm run build
npm test
```

When generated bindings or the published npm surface are affected, also run:

```bash
npm run codegen
npm run verify-package
```

See [`package.json`](./package.json) and the selected script's source for specialized checks and the
exact command interface.