> For the complete documentation index, see [llms.txt](https://docs.investhub.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.investhub.org/guides/liquidation.md).

# Liquidation Management

This guide describes Investhub’s **liquidation management** product: a white-label workflow for bankruptcy and insolvency cases where token holders can verify their **USDC compensation quote**, complete KYC, **sign claim-transfer documents**, deposit tokens on-chain, and receive **USDC payouts**.

The production reference deployment is [**envion.investhub.io**](https://envion.investhub.io/) — built for **Envion AG in Liquidation** (EVN token holders in the Swiss bankruptcy process). Today this runs on the **legacy KYC SaaS stack** (separate repo under `reference-code/kyc-saas/`), not as an **investhubio UI tenant**. The platform goal is to host Envion and other issuers as **UI tenants** on one `investhubio` app under the same ECSP umbrella — see [`docs/planning/MULTI_TENANT_ARCHITECTURE.md`](https://github.com/Equanimity-Blockchain-Holdings-Pte-Ltd/investhubio/blob/main/docs/planning/MULTI_TENANT_ARCHITECTURE.md).

> **Demo:** See the [Envion liquidation walkthrough on YouTube](https://www.youtube.com/watch?v=IEq1fkCRRcA\&t=62s).

***

## Overview

| Step            | What the user does                          | What the platform does                                                            |
| --------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| 1. Quote        | Enters Ethereum wallet address              | Reads on-chain ENV transfers via Etherscan; calculates USDC compensation          |
| 2. Wallet proof | Signs a MetaMask message                    | Confirms wallet ownership; locks receiving address                                |
| 3. KYC          | Completes identity verification             | Liquidation-specific disclaimers and creditor onboarding                          |
| 4. Sign         | E-signs Transfer of Claims PDFs             | SignNow / Skribble; multi-party signature workflow                                |
| 5. Deposit      | Sends ENV tokens to platform holder address | Tracks inbound transfers as `CompensationTracking` records                        |
| 6. Payout       | Waits for compliance approval               | Admin sends **USDC** on Ethereum; tx hash recorded and linked to signed documents |

**Payout currency:** USDC on Ethereum mainnet (`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`, 6 decimals).

**Source token (Envion):** EVN/ENVION ERC-20 on Ethereum (`0xd780ae2bf04cd96e577d3d014762f831d97129d0`).

***

## Where the code lives

Liquidation is implemented in the **KYC SaaS stack** (GraphQL backend + React frontend), not in the main Supabase Edge Function app. In the GitHub repo:

| Layer                                           | Path                                                                                                 |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Backend GraphQL API**                         | `reference-code/kyc-saas/kyc-saas-backend/`                                                          |
| **Liquidation resolvers**                       | `…/src/resolvers/liquidation.js`                                                                     |
| **Liquidation service (rates, amounts)**        | `…/src/service/liquidationService.js`                                                                |
| **Etherscan token history**                     | `…/src/service/etherscanService.js`                                                                  |
| **PDF + e-sign (Transfer of Claims)**           | `…/src/service/pdfService.js`, `…/src/service/signnowService.js`, `…/src/service/skribbleService.js` |
| **GraphQL schema**                              | `…/src/typeDefs/liquidation.js`                                                                      |
| **USDC contract config**                        | `…/src/config/liquidation.js`                                                                        |
| **Frontend**                                    | `reference-code/kyc-saas/kyc-saas-frontend/`                                                         |
| **Quote + wallet UI**                           | `…/src/components/WalletValidationForm.jsx`                                                          |
| **Admin USDC payout button**                    | `…/src/components/SendCompensationButton.jsx`                                                        |
| **Admin compensatable table**                   | `…/src/components/AdminCompensatableTable.jsx`                                                       |
| **Routes (`/transfer-claim`, wallet validate)** | `…/src/routes.jsx`, `…/src/pages/WalletValidate.jsx`                                                 |

The **main Investhub app** (`src/`, Supabase) references Envion in token metadata and supports off-chain liquidation valuations in the portfolio cache, but the full liquidation **quote → sign → USDC** pipeline still runs on the **legacy KYC SaaS** deployment at `envion.investhub.io` until ported to a **UI tenant** on `investhubio`.

Token metadata in the main app: `src/constants/tokenData.ts` (Envion AG, Liquidation Payout 1#/2# children).

***

## Architecture

```mermaid
flowchart TB
  subgraph user [Creditor / token holder]
    W[Ethereum wallet with ENV tokens]
    MM[MetaMask]
  end

  subgraph ui [envion.investhub.io — KYC SaaS frontend]
    WV[WalletValidationForm]
    KYC[KYC + liquidation disclaimers]
    TC[Transfer of Claims e-sign]
  end

  subgraph api [KYC SaaS GraphQL backend]
    Q[checkWalletCompensation]
    CW[confirmLiquidationWallet]
    TR[trackPayoutTransaction]
    SN[signLiquidationForm]
    SP[savePayout]
  end

  subgraph chain [Ethereum mainnet]
    ENV[ENV token contract]
    USDC[USDC contract]
    ES[Etherscan API]
  end

  W --> WV
  MM --> WV
  WV --> Q
  Q --> ES
  ES --> ENV
  WV --> CW
  KYC --> SN
  SN --> TC
  W -->|transfer ENV to holder address| ENV
  ENV --> TR
  TR --> ES
  TC -->|admin approves| SP
  SP --> USDC
  USDC -->|USDC transfer| W
```

***

## Compensation quote

### How the quote is calculated

When a user clicks **Check compensation**, the backend runs `checkWalletCompensation`:

1. Load tenant settings: `liquidation_contract_address`, `liquidation_token_decimal`, `liquidation_holder_addresses`.
2. Call Etherscan `tokentx` for the wallet and ENV contract.
3. Filter transfers **from** the user’s wallet **to** configured holder addresses.
4. Sum token amounts (adjusted for decimals).
5. Multiply by the **compensation rate** from `liquidationService.getCompensationRate()`.

```
compensation_usdc = total_env_tokens × compensation_rate
```

**Default rate:** `0.081` USDC per ENV token (overridable per tenant via `liquidation_compensation_rate`).

**Per-wallet overrides:** `liquidation_specific_compensation_rate` — newline-separated `address,rate` pairs.

**Code:** `reference-code/kyc-saas/kyc-saas-backend/src/resolvers/liquidation.js` (`checkWalletCompensation`), `liquidationService.js`.

### GraphQL

```graphql
query checkWalletCompensation($walletAddress: String!) {
  checkWalletCompensation(walletAddress: $walletAddress)
}
```

**Response shape:**

```json
{
  "token": 12345.67,
  "compensation": 1000.00
}
```

(`compensation` is in USDC.)

***

## Wallet validation and ownership proof

After a positive quote, the user clicks **Use this wallet**:

1. MetaMask connects and signs: *"Please sign this message to confirm the ownership of provided wallet"*.
2. Backend verifies signer address matches the entered wallet.
3. `confirmLiquidationWallet` checks the wallet still holds ENV tokens (via Etherscan).
4. User record updated: `is_valid_liquidation_wallet: true`, `wallet_address` set, wallet change disabled.

User is then redirected to `/application` for KYC.

**Frontend:** `WalletValidationForm.jsx`\
**Backend:** `confirmLiquidationWallet` in `liquidation.js`

***

## KYC and Transfer of Claims signing

For tenants with `token_type = LIQUIDATION`, the KYC flow includes liquidation-specific disclaimers (claim transfer, consent, GDPR).

When a **creditor number** is assigned (`updateCreditorNumber`), the platform generates a **Transfer of Claims** PDF bundle and sends it for e-signature via **SignNow** (and optionally **Skribble**):

| Template flag | Document section                            |
| ------------- | ------------------------------------------- |
| `trado`       | Trado / GDPR addendum                       |
| `envion`      | Envion claim transfer (2 pages)             |
| `gtcm`        | GTCM (non-German)                           |
| `amb`         | AMB (German)                                |
| `contract`    | Contract when no legal protection insurance |

PDF assembly: `pdfService.createSignnowEnvionFormData()` — merges templates from `pdfs/liquidationForm/`.

E-sign workflow: `signnowService.signLiquidationForm()` — two signers:

1. **Signer 1:** Creditor (customer email)
2. **Signer 2:** Compliance / payout approver (tenant `mailgun.from_kyc_approval_email`)

Signature requirements before payout:

* Payout **≥ 5,000 USDC:** full document must be `fulfilled` (both signers).
* Payout **< 5,000 USDC:** creditor signature alone is sufficient.

**Code:** `customerIndividual.js` (`updateCreditorNumber`), `signnowService.js` (`signLiquidationForm`, `createEnvionDocument`).

***

## Token deposit and tracking

After KYC approval, the creditor sends ENV tokens from their wallet to a **platform holder address** (configured in tenant settings).

Each inbound transfer is recorded in **`CompensationTracking`**:

| Field                            | Meaning                         |
| -------------------------------- | ------------------------------- |
| `transactionHash`                | On-chain ENV transfer tx        |
| `amount`                         | Raw token amount (wei-style)    |
| `decimal`                        | Token decimals                  |
| `compensationRateAtConfirmation` | Rate locked at tracking time    |
| `status`                         | `NOT_PAID` → `PENDING` → `PAID` |
| `transferedAt`                   | Block timestamp                 |

Tracking is refreshed via `trackPayoutTransaction()` when KYC status changes — it re-scans Etherscan for new transfers to holder addresses.

***

## USDC payout

### Admin flow

Compliance officers use **AdminCompensatableTable** + **SendCompensationButton**:

1. Review `getUserCompensationTracking` — list of ENV deposits and total USDC due.
2. Confirm `checkLiquidationDocumentHasNeededSignatures` is satisfied.
3. Connect MetaMask wallet funded with USDC.
4. Click **Send compensation** — calls USDC `transfer(recipient, amount)` on Ethereum.
5. On tx success, call `savePayout` with `payoutTxHash` and tracking IDs.

Backend waits for on-chain confirmation, parses USDC amount from tx input, creates `CompensationPayout`, marks tracking rows `PAID`, and prefills the SignNow document with `transaction_hash`.

**USDC transfer (frontend):** `SendCompensationButton.jsx` — encodes `contract.methods.transfer(addressTo, amount * 10^6)`.

**Payout recording (backend):** `savePayout` / `savePayoutForKyc` in `liquidation.js`.

### GraphQL mutations

```graphql
mutation confirmLiquidationWallet($walletAddress: String!) {
  confirmLiquidationWallet(walletAddress: $walletAddress)
}

mutation savePayout($payoutTxHash: String!, $transactionIds: [ID]!, $userId: ID!) {
  savePayout(payoutTxHash: $payoutTxHash, transactionIds: $transactionIds, userId: $userId)
}
```

***

## End-to-end sequence

```mermaid
sequenceDiagram
  participant User
  participant UI as envion.investhub.io
  participant API as KYC GraphQL API
  participant ES as Etherscan
  participant Sign as SignNow
  participant Admin
  participant USDC as USDC contract

  User->>UI: Enter wallet, Check compensation
  UI->>API: checkWalletCompensation(wallet)
  API->>ES: tokentx (ENV contract, wallet → holders)
  ES-->>API: transfer list
  API-->>UI: { token, compensation USDC }

  User->>UI: Sign MetaMask message, Use this wallet
  UI->>API: confirmLiquidationWallet
  API-->>UI: OK → redirect to KYC

  User->>UI: Complete KYC + disclaimers
  Admin->>API: updateCreditorNumber
  API->>Sign: Transfer of Claims PDF invite
  User->>Sign: E-sign as creditor
  Admin->>Sign: E-sign as approver

  User->>User: Send ENV tokens to holder address
  API->>ES: trackPayoutTransaction
  ES-->>API: CompensationTracking NOT_PAID

  Admin->>UI: Send compensation (USDC)
  UI->>USDC: transfer(userWallet, amount)
  USDC-->>UI: txHash
  UI->>API: savePayout(txHash, trackingIds)
  API-->>User: USDC received; status PAID
```

***

## Tenant configuration

Each liquidation tenant (e.g. `envion.investhub.io`) stores these settings:

| Setting                                  | Purpose                                              |
| ---------------------------------------- | ---------------------------------------------------- |
| `token_type`                             | Must be `LIQUIDATION`                                |
| `liquidation_contract_address`           | Source token contract (ENV for Envion)               |
| `liquidation_token_decimal`              | Token decimals for amount math                       |
| `liquidation_holder_addresses`           | Newline-separated addresses that accept ENV deposits |
| `liquidation_compensation_rate`          | Default USDC-per-token rate (e.g. `0.081`)           |
| `liquidation_specific_compensation_rate` | Optional per-wallet overrides: `0xabc...,0.09`       |
| SignNow credentials                      | E-sign for Transfer of Claims                        |

**DNS:** `envion.investhub.io` → CNAME → `app.investhub.io` (tenant resolved at runtime by hostname).

**Code reference:** `reference-code/investhub-gitlab/backend/src/resolvers/tenant.js` (allowed hosts include `envion.investhub.io`).

***

## User-facing routes (KYC SaaS frontend)

| Route                                    | Purpose                                                   |
| ---------------------------------------- | --------------------------------------------------------- |
| `/`                                      | Dashboard; liquidation tenants link to `/transfer-claim`  |
| `/transfer-claim`                        | Main claim transfer entry (Envion-specific UI)            |
| `/transfer-claim/guide`                  | Step-by-step guide                                        |
| `/transfer-claim/claim-with-liquidator`  | Claim via liquidator path                                 |
| `/transfer-claim/claim-with-credit-card` | Alternative claim path                                    |
| `/transfer-claim/claim-with-bitcoin`     | Alternative claim path                                    |
| Wallet validate page                     | Quote calculator + MetaMask confirmation → `/application` |

> **Note:** `TransferClaim` page components are referenced in `routes.jsx` but may not be present in all repo snapshots; the core quote/sign/payout logic is in the components listed above.

***

## Relation to main Investhub platform

| Feature                 | KYC SaaS (liquidation)      | Main app (investhub.io)                                                             |
| ----------------------- | --------------------------- | ----------------------------------------------------------------------------------- |
| Quote from wallet       | ✅ `checkWalletCompensation` | —                                                                                   |
| KYC + e-sign            | ✅ SignNow / Skribble        | SumSub KYC                                                                          |
| USDC payout on-chain    | ✅ `SendCompensationButton`  | Crypto payments via crowdsale contracts                                             |
| Portfolio valuation     | —                           | `get-portfolio-cached` supports `manual_valuation` for off-chain liquidation values |
| Shareholder broadcasts  | —                           | `xmtp-broadcast` supports message type `liquidation`                                |
| Token explorer metadata | —                           | `tokenData.ts` — Envion, Liquidation Payout 1#/2#                                   |

***

## Related GraphQL API (compliance / admin)

| Query / mutation                              | Role                                             | Min rights          |
| --------------------------------------------- | ------------------------------------------------ | ------------------- |
| `getUserCompensationTracking`                 | List ENV deposits + totals                       | COMPLIANCE\_OFFICER |
| `getUserCompensationPayout`                   | Payout history                                   | COMPLIANCE\_OFFICER |
| `checkLiquidationDocumentHasNeededSignatures` | Sign-off gate                                    | COMPLIANCE\_OFFICER |
| `checkBatchCompensate`                        | Batch payout eligibility                         | COMPLIANCE\_OFFICER |
| `getUserCompensationRate`                     | Current rate for logged-in user                  | Auth                |
| `addLiquidationProof`                         | Upload tx hashes or files (lawyer transfer path) | Auth                |
| `savePayoutForKyc`                            | Record payout by KYC id                          | COMPLIANCE\_OFFICER |

Full schema: `reference-code/kyc-saas/kyc-saas-backend/src/typeDefs/liquidation.js`.

***

## Reusing for other liquidations

The same pattern applies to any tokenized bankruptcy:

1. Create a white-label tenant (`*.investhub.io` or custom domain).
2. Set `token_type = LIQUIDATION` and liquidation\_\* settings.
3. Configure holder addresses and compensation rate(s).
4. Customize PDF templates in `pdfs/liquidationForm/`.
5. Fund an admin USDC wallet for payouts.

This is the infrastructure referenced in the ECSP strategy as prior art: **automated creditor onboarding, signed claim transfer, on-chain token receipt, and USDC distribution** — proven at scale with Envion (\~6,000 creditors in related materials).

***

## Further reading

* [Investments guide](/guides/investments.md) — main platform subscription flow
* [White-Label Tenants](/guides/white-label.md) — tenant provisioning on Investhub
* [Envion bankruptcy portal](https://www.envion-konkurs.ch/) — official creditor information
* Envion token on Etherscan: [0xd780ae2bf04cd96e577d3d014762f831d97129d0](https://etherscan.io/token/0xd780ae2bf04cd96e577d3d014762f831d97129d0)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.investhub.org/guides/liquidation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.