@fairmint/canton-fairmint-sdk 0.0.69 → 0.0.71
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -0
- package/package.json +12 -3
package/README.md
CHANGED
|
@@ -3,3 +3,66 @@
|
|
|
3
3
|
Shared TypeScript utilities for Canton blockchain integration at Fairmint.
|
|
4
4
|
|
|
5
5
|
See the [wiki](https://github.com/fairmint/canton-fairmint-sdk/wiki) for full documentation.
|
|
6
|
+
|
|
7
|
+
## Equity-settlement integration tests
|
|
8
|
+
|
|
9
|
+
Integration tests exercise the `FairmintOcpClient.EquitySettlement` builders against a real Canton
|
|
10
|
+
sandbox (`cn-quickstart` LocalNet) so that contract-level surprises — wrong signatories, malformed
|
|
11
|
+
ExtraArgs, broken disclosed contracts — surface in CI rather than in apps.
|
|
12
|
+
|
|
13
|
+
Run with:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm run localnet:start # one-time per machine: boots cn-quickstart LocalNet
|
|
17
|
+
npm run test:integration # uploads EquityTokens DAR + exercises settlement scenarios
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`npm run localnet:verify` chains setup + start + smoke + tests in one command (used by the CI workflow).
|
|
21
|
+
|
|
22
|
+
### Prerequisites
|
|
23
|
+
|
|
24
|
+
- **Docker** (Docker Desktop on macOS; `docker.io` + `docker-compose-v2` on Linux). LocalNet runs
|
|
25
|
+
~10 containers; ~6 GB RAM headroom recommended.
|
|
26
|
+
- **Daml SDK 3.x** at `$HOME/.daml/bin/daml`. Installed automatically by
|
|
27
|
+
`scripts/localnet/localnet-cloud.sh setup`.
|
|
28
|
+
- **Sibling [`Fairmint/daml`](https://github.com/Fairmint/daml) checkout** at `../daml`, or the
|
|
29
|
+
`FAIRMINT_EQUITY_TOKENS_DAR_PATH` env var pointing at an `EquityTokens.dar`. The CIP-0056
|
|
30
|
+
`EquityTokens` package is not shipped in the `@fairmint/daml-js` npm release.
|
|
31
|
+
|
|
32
|
+
### Auth + endpoints
|
|
33
|
+
|
|
34
|
+
Defaults match cn-quickstart's shared-secret mode (no Keycloak needed):
|
|
35
|
+
|
|
36
|
+
| Variable | Default |
|
|
37
|
+
| --------------------------------- | ------------------------ |
|
|
38
|
+
| `FAIRMINT_TEST_LEDGER_API_URL` | `http://localhost:3975` |
|
|
39
|
+
| `FAIRMINT_TEST_VALIDATOR_API_URL` | `http://localhost:3903` |
|
|
40
|
+
| `FAIRMINT_TEST_SCAN_API_URL` | `http://localhost:4000` |
|
|
41
|
+
| `FAIRMINT_TEST_SHARED_SECRET` | `unsafe` |
|
|
42
|
+
| `FAIRMINT_TEST_PARTY_SUITE_ID` | `eqtest` |
|
|
43
|
+
| `FAIRMINT_EQUITY_TOKENS_DAR_PATH` | sibling `../daml` lookup |
|
|
44
|
+
|
|
45
|
+
The harness allocates `<suite>-issuer`, `<suite>-ta`, `<suite>-seller`, `<suite>-buyer` parties on
|
|
46
|
+
the participant and grants `ledger-api-user` `CanActAs` rights for each so multi-party submissions
|
|
47
|
+
work end-to-end. Parties are reused across runs by hint; bump `FAIRMINT_TEST_PARTY_SUITE_ID` to
|
|
48
|
+
get fresh ones (e.g. on a CI matrix).
|
|
49
|
+
|
|
50
|
+
### Scenarios covered
|
|
51
|
+
|
|
52
|
+
Test file (under `test/integration/equitySettlement/`) → mirrored daml-script scenario(s):
|
|
53
|
+
|
|
54
|
+
| Test file | Scenarios |
|
|
55
|
+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
56
|
+
| `holding.integration.test.ts` | mint, TA admin-transfer, TA burn, double-burn fails, validation guards (zero / negative / empty companyId / empty securityClassId) |
|
|
57
|
+
| `fopTransfer.integration.test.ts` | FOP happy path (`Pending → Update → Completed`), withdraw, multi-input consolidation, wrong-`expectedAdmin` guard, expired `executeBefore` |
|
|
58
|
+
| `dvpAllocation.integration.test.ts` | DvP happy path (`Allocate → ExecuteTransfer`), cancel, withdraw, empty `settlementId`, empty `authPayloadHash`, expired `allocateBefore`, amount mismatch |
|
|
59
|
+
| `authorization.integration.test.ts` | shareholder cannot AdminTransfer / Burn, issuer cannot AdminTransfer / Burn, non-TA cannot drive `TransferInstruction_Update`, non-sender cannot allocate |
|
|
60
|
+
| `preflight.integration.test.ts` | `CONTRACT_NOT_FOUND` on fabricated cid, `CONTRACT_NOT_FOUND` on archived cid, informee / authorization failure on missing actAs |
|
|
61
|
+
| `quickstart.smoke.test.ts` | `/v2/version`, harness initialization |
|
|
62
|
+
|
|
63
|
+
### CI
|
|
64
|
+
|
|
65
|
+
The `.github/workflows/test-equity-settlement-quickstart.yml` workflow boots LocalNet on demand and
|
|
66
|
+
nightly, and on PRs labelled with `equity-localnet`. Standard CI (`.github/workflows/ci.yml`) skips
|
|
67
|
+
integration tests by design — they need Docker + a multi-minute warm-up that would make every PR
|
|
68
|
+
flaky.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fairmint/canton-fairmint-sdk",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.71",
|
|
4
4
|
"description": "Shared SDK utilities for Canton blockchain integration",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
@@ -22,9 +22,16 @@
|
|
|
22
22
|
"test": "npm run -s typecheck && jest",
|
|
23
23
|
"test:ci": "npm run -s typecheck && jest --runInBand",
|
|
24
24
|
"test:coverage": "jest --coverage",
|
|
25
|
-
"test:integration": "npm run -s typecheck && jest -c jest.integration.config.js",
|
|
26
|
-
"test:integration:ci": "npm run -s typecheck && jest -c jest.integration.config.js --runInBand",
|
|
25
|
+
"test:integration": "npm run -s typecheck && jest -c jest.integration.config.js --passWithNoTests",
|
|
26
|
+
"test:integration:ci": "npm run -s typecheck && jest -c jest.integration.config.js --runInBand --passWithNoTests",
|
|
27
27
|
"test:watch": "jest --watch",
|
|
28
|
+
"localnet:setup": "bash scripts/localnet/localnet-cloud.sh setup",
|
|
29
|
+
"localnet:smoke": "bash scripts/localnet/localnet-cloud.sh smoke",
|
|
30
|
+
"localnet:start": "bash scripts/localnet/localnet-cloud.sh start",
|
|
31
|
+
"localnet:status": "bash scripts/localnet/localnet-cloud.sh status",
|
|
32
|
+
"localnet:stop": "bash scripts/localnet/localnet-cloud.sh stop",
|
|
33
|
+
"localnet:test": "bash scripts/localnet/localnet-cloud.sh test",
|
|
34
|
+
"localnet:verify": "bash scripts/localnet/localnet-cloud.sh verify",
|
|
28
35
|
"prepare-release": "ts-node --project scripts/tsconfig.json scripts/prepare-release.ts",
|
|
29
36
|
"prepublishOnly": "npm run clean && npm run build"
|
|
30
37
|
},
|
|
@@ -62,6 +69,7 @@
|
|
|
62
69
|
"@fairmint/open-captable-protocol-daml-js": "0.2.161",
|
|
63
70
|
"@open-captable-protocol/canton": "0.5.3",
|
|
64
71
|
"@types/jest": "30.0.0",
|
|
72
|
+
"@types/jsonwebtoken": "9.0.10",
|
|
65
73
|
"@types/node": "25.6.0",
|
|
66
74
|
"@types/pg": "8.20.0",
|
|
67
75
|
"@typescript-eslint/eslint-plugin": "8.59.0",
|
|
@@ -69,6 +77,7 @@
|
|
|
69
77
|
"eslint": "10.2.1",
|
|
70
78
|
"eslint-plugin-unused-imports": "4.4.1",
|
|
71
79
|
"jest": "30.3.0",
|
|
80
|
+
"jsonwebtoken": "9.0.3",
|
|
72
81
|
"prettier": "3.8.3",
|
|
73
82
|
"ts-jest": "29.4.9",
|
|
74
83
|
"ts-node": "10.9.2",
|