From 4f05ef0886f4bb7344fce87d39d930cbb8b82428 Mon Sep 17 00:00:00 2001 From: OlolaJaco Date: Sun, 19 Jul 2026 21:55:09 +0100 Subject: [PATCH 1/3] docs: add glossary with insurance pool terminology Define Claim, Coverage Cap, Default Protection, Enrollment, Insurance Pool, and Premium with cross-references to related docs and frontend integration points. Link the glossary from the README's documentation section. --- README.md | 1 + docs/glossary.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/glossary.md diff --git a/README.md b/README.md index 4d00dcf..7724277 100644 --- a/README.md +++ b/README.md @@ -210,6 +210,7 @@ A central marketplace listing all active open invoices waiting for funding, deta - **Getting Started Guide**: Refer to the [Quick Start](#-quick-start) section. - **Component Library (Storybook)**: Browse the full component library with interactive controls, variants, and a11y checks at the [published Storybook](https://invoice-liquidity-network.github.io/ILN-Frontend) (deployed from `main`). - **Frontend Architecture Overview**: Learn about our architecture design and libraries in [docs/architecture.md](docs/architecture.md). +- **Glossary**: Protocol and DeFi terminology (insurance pool, premiums, claims, and more) in [docs/glossary.md](docs/glossary.md). - **Contribution Guidelines**: Read [CONTRIBUTING.md](CONTRIBUTING.md) for comprehensive setup instructions, testing standards, code style guidelines, Stellar-specific setup, and development workflow. - **Visual Regression Testing**: Learn about baseline configurations in [docs/VISUAL_REGRESSION_WORKFLOW.md](docs/VISUAL_REGRESSION_WORKFLOW.md). - **Design System Blueprint**: Deep dive into "The Fiscal Atelier" aesthetic rules in [DESIGN.md](DESIGN.md). diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..fc64803 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,48 @@ +# Glossary + +Definitions of protocol and DeFi terminology used across the Invoice Liquidity Network (ILN) documentation and codebase. Terms are listed alphabetically. Cross-references to other glossary entries appear in **bold**; links point to the relevant documentation or source files. + +--- + +## Insurance + +### Claim + +The process of requesting compensation from the **Insurance Pool** after an invoice defaults. Only the pool admin (the liquidity contract) can file claims on behalf of affected LPs; payouts are limited by the pool's **Coverage Cap**. + +*See also:* **Coverage Cap**, **Default Protection**, **Insurance Pool** +*Frontend integration:* `claimInsurance()` in [`src/utils/soroban.ts`](../src/utils/soroban.ts) + +### Coverage Cap + +The maximum flat amount the **Insurance Pool** will pay out per **Claim**. Configured once at pool initialization and applied uniformly to every claim regardless of the size of the defaulted invoice. + +*See also:* **Claim**, **Insurance Pool** + +### Default Protection + +Insurance coverage that compensates liquidity providers (LPs) for losses caused by invoice defaults. LPs obtain default protection by completing **Enrollment** in the **Insurance Pool** and paying a **Premium**; when an invoice they funded defaults, the pool compensates them via a **Claim**. + +*See also:* **Claim**, **Enrollment**, **Insurance Pool**, **Premium** +*Frontend integration:* the LP dashboard's insurance panel ([`src/components/InsurancePoolPanel.tsx`](../src/components/InsurancePoolPanel.tsx)), gated by the `NEXT_PUBLIC_INSURANCE_POOL_ENABLED` flag (see [README — Environment Variables](../README.md)) + +### Enrollment + +The act of registering an LP in the insurance program, making them eligible for **Default Protection**. Enrollment is optional and is completed by depositing a **Premium** into the **Insurance Pool**; an LP's enrollment status can be queried on-chain. + +*See also:* **Default Protection**, **Insurance Pool**, **Premium** +*Frontend integration:* `getLPInsuranceStatus()` in [`src/utils/soroban.ts`](../src/utils/soroban.ts) and the [`useInsurance`](../src/hooks/useInsurance.ts) hook + +### Insurance Pool + +A smart contract that provides **Default Protection** for liquidity providers. LPs opt in voluntarily by paying **Premiums**; when an invoice they funded defaults, the pool compensates them through a **Claim**, up to the **Coverage Cap**. The contract lives in the ILN contracts repository under `contracts/insurance_pool/`. + +*See also:* **Claim**, **Coverage Cap**, **Default Protection**, **Enrollment**, **Premium** +*Frontend integration:* `getInsurancePoolInfo()` in [`src/utils/soroban.ts`](../src/utils/soroban.ts); UI in [`src/components/InsurancePoolPanel.tsx`](../src/components/InsurancePoolPanel.tsx). See the [Architecture Overview](./architecture.md) for how frontend hooks reach Soroban contracts. + +### Premium + +A payment made by an LP to the **Insurance Pool** to obtain **Default Protection** coverage. Premiums are currently tracked as an accounting balance inside the pool contract (actual token transfers are a planned follow-up). The pool's premium rate is expressed in basis points (bps). + +*See also:* **Default Protection**, **Enrollment**, **Insurance Pool** +*Frontend integration:* `depositPremium()` in [`src/utils/soroban.ts`](../src/utils/soroban.ts) From e9d78a0ce7808df166cafbca4ddf6aa7de912826 Mon Sep 17 00:00:00 2001 From: OlolaJaco Date: Sun, 19 Jul 2026 23:28:44 +0100 Subject: [PATCH 2/3] ci: migrate remaining workflows from npm to pnpm The pnpm migration only updated ci.yml, leaving seven workflows running 'npm ci' with npm caching against the removed package-lock.json. Add pnpm/action-setup, switch setup-node caching to pnpm, and replace npm commands with pnpm equivalents, matching the pattern in ci.yml. --- .github/workflows/accessibility-tests.yml | 12 ++++++++---- .github/workflows/accessibility.yml | 7 ++++++- .github/workflows/contract-tests.yml | 7 ++++++- .github/workflows/e2e-tests.yml | 9 +++++++-- .github/workflows/lighthouse.yml | 9 +++++++-- .github/workflows/storybook-deploy.yml | 10 +++++++--- .github/workflows/visual-regression.yml | 9 +++++++-- 7 files changed, 48 insertions(+), 15 deletions(-) diff --git a/.github/workflows/accessibility-tests.yml b/.github/workflows/accessibility-tests.yml index d37de60..a7fd12a 100644 --- a/.github/workflows/accessibility-tests.yml +++ b/.github/workflows/accessibility-tests.yml @@ -17,20 +17,24 @@ jobs: steps: - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} - cache: "npm" + cache: "pnpm" - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Run accessibility tests - run: npm run test -- __tests__/accessibility.test.tsx + run: pnpm run test -- __tests__/accessibility.test.tsx - name: Run all tests - run: npm test + run: pnpm test - name: Upload coverage if: always() diff --git a/.github/workflows/accessibility.yml b/.github/workflows/accessibility.yml index 991117b..d733671 100644 --- a/.github/workflows/accessibility.yml +++ b/.github/workflows/accessibility.yml @@ -13,13 +13,18 @@ jobs: steps: - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' + cache: 'pnpm' - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Run accessibility tests run: npx vitest run __tests__/accessibility --reporter=verbose diff --git a/.github/workflows/contract-tests.yml b/.github/workflows/contract-tests.yml index 7871ebf..9a0203f 100644 --- a/.github/workflows/contract-tests.yml +++ b/.github/workflows/contract-tests.yml @@ -13,13 +13,18 @@ jobs: steps: - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' + cache: 'pnpm' - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Run contract integration tests with coverage run: npx vitest run __tests__/contract --reporter=verbose --coverage diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml index c96a5be..7138a98 100644 --- a/.github/workflows/e2e-tests.yml +++ b/.github/workflows/e2e-tests.yml @@ -13,18 +13,23 @@ jobs: steps: - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - uses: actions/setup-node@v4 with: node-version: "22" + cache: "pnpm" - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Install Playwright browsers run: npx playwright install --with-deps - name: Run Playwright tests - run: npm run test:e2e + run: pnpm run test:e2e env: NEXT_PUBLIC_API_MOCKING: "enabled" diff --git a/.github/workflows/lighthouse.yml b/.github/workflows/lighthouse.yml index 5a3aba0..0feaaf4 100644 --- a/.github/workflows/lighthouse.yml +++ b/.github/workflows/lighthouse.yml @@ -13,16 +13,21 @@ jobs: steps: - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' + cache: 'pnpm' - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Build Next.js app - run: npm run build + run: pnpm run build env: CI: true NEXT_PUBLIC_STELLAR_NETWORK: testnet diff --git a/.github/workflows/storybook-deploy.yml b/.github/workflows/storybook-deploy.yml index 5d25846..4cf8471 100644 --- a/.github/workflows/storybook-deploy.yml +++ b/.github/workflows/storybook-deploy.yml @@ -24,14 +24,18 @@ jobs: steps: - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - uses: actions/setup-node@v4 with: node-version: 20 - cache: npm + cache: pnpm - - run: npm ci + - run: pnpm install --frozen-lockfile - - run: npm run build-storybook + - run: pnpm run build-storybook - uses: actions/upload-pages-artifact@v3 with: diff --git a/.github/workflows/visual-regression.yml b/.github/workflows/visual-regression.yml index 27c866a..272c9c5 100644 --- a/.github/workflows/visual-regression.yml +++ b/.github/workflows/visual-regression.yml @@ -16,16 +16,21 @@ jobs: with: fetch-depth: 0 + - uses: pnpm/action-setup@v4 + with: + version: '9.0.0' + - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' + cache: 'pnpm' - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Build Storybook - run: npm run build-storybook + run: pnpm run build-storybook env: NODE_OPTIONS: '--max_old_space_size=4096' From 1e957814eb54bc54d3b5111735dd0c95bd139a55 Mon Sep 17 00:00:00 2001 From: OlolaJaco Date: Sun, 19 Jul 2026 23:31:53 +0100 Subject: [PATCH 3/3] ci: drop Node 18 from accessibility test matrix Vitest 4 (rolldown) requires util.styleText, added in Node 20.12, so the 18.x leg fails at startup. Node 18 is also EOL and being removed from GitHub runners. Test on 20.x and 22.x instead, matching the versions used by the other workflows. --- .github/workflows/accessibility-tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/accessibility-tests.yml b/.github/workflows/accessibility-tests.yml index a7fd12a..c5d963c 100644 --- a/.github/workflows/accessibility-tests.yml +++ b/.github/workflows/accessibility-tests.yml @@ -12,7 +12,7 @@ jobs: strategy: matrix: - node-version: [18.x, 20.x] + node-version: [20.x, 22.x] steps: - uses: actions/checkout@v4