Merge pull request #104 from pope-h/feat/claimable-balances-40

feat: claimable balances for unregistered employees

Author: Wilfred007

backend/package-lock.json

@@ -22,6 +22,7 @@
   "dependencies": {
     "@sentry/node": "^10.42.0",
     "@sentry/profiling-node": "^10.42.0",
+    "@stellar/stellar-sdk": "^14.3.3",
     "cors": "^2.8.6",
     "dotenv": "^17.3.1",
     "express": "^5.2.1",

backend/package.json

@@ -0,0 +1,71 @@
+import type { Request, Response } from 'express';
+import { z } from 'zod';
+import { ClaimableBalanceService } from '../services/claimableBalanceService.js';
+
+const createForEmployeeSchema = z.object({
+  organizationId: z.number().int().positive(),
+  employeeId: z.number().int().positive(),
+  amount: z.string().min(1),
+  assetIssuer: z.string().length(56),
+});
+
+const listPendingSchema = z.object({
+  organizationId: z.string().regex(/^\d+$/).transform(Number).optional(),
+  walletAddress: z.string().length(56),
+});
+
+export class ClaimableBalanceController {
+  static async createForEmployee(req: Request, res: Response) {
+    try {
+      const { organizationId, employeeId, amount, assetIssuer } = createForEmployeeSchema.parse(
+        req.body
+      );
+
+      const wallet = await ClaimableBalanceService.ensureCustodialWallet({
+        organizationId,
+        employeeId,
+      });
+
+      const claim = await ClaimableBalanceService.createOrgUsdClaimableBalance({
+        organizationId,
+        employeeId,
+        amount,
+        assetIssuer,
+        claimantPublicKey: wallet.publicKey,
+      });
+
+      res.status(201).json({
+        success: true,
+        data: {
+          ...claim,
+          claimantPublicKey: wallet.publicKey,
+          instructions:
+            'A claimable balance was created for your custodial wallet. Add the ORGUSD trustline, then claim the balance using your wallet application.',
+        },
+      });
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return res.status(400).json({ error: 'Validation Error', details: error.issues });
+      }
+      res.status(500).json({ error: (error as Error).message || 'Failed to create claimable balance' });
+    }
+  }
+
+  static async listPendingForWallet(req: Request, res: Response) {
+    try {
+      const { organizationId, walletAddress } = listPendingSchema.parse(req.query);
+
+      const claims = await ClaimableBalanceService.listPendingClaimsForWallet({
+        organizationId: organizationId ?? null,
+        walletAddress,
+      });
+
+      res.json({ success: true, data: claims });
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return res.status(400).json({ error: 'Validation Error', details: error.issues });
+      }
+      res.status(500).json({ error: (error as Error).message || 'Failed to list pending claims' });
+    }
+  }
+}

backend/src/controllers/claimableBalanceController.ts

@@ -0,0 +1,44 @@
+-- =============================================================================
+-- Migration 017: Claimable balances + custodial wallet secrets
+-- Purpose : Track claimable balances for employees who cannot receive ORGUSD
+--           and store custodial wallet secrets (encrypted at rest).
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS custodial_wallet_secrets (
+  wallet_id         UUID PRIMARY KEY REFERENCES wallets(id) ON DELETE CASCADE,
+  encrypted_secret  TEXT NOT NULL,
+  encryption_version INTEGER NOT NULL DEFAULT 1,
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS claimable_balance_claims (
+  id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id  INTEGER NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  employee_id      INTEGER REFERENCES employees(id) ON DELETE SET NULL,
+  claimant_wallet_id UUID REFERENCES wallets(id) ON DELETE SET NULL,
+
+  asset_code       VARCHAR(12) NOT NULL DEFAULT 'ORGUSD',
+  asset_issuer     VARCHAR(56) NOT NULL,
+  amount           DECIMAL(20, 7) NOT NULL CHECK (amount > 0),
+
+  status           VARCHAR(20) NOT NULL DEFAULT 'pending'
+                     CHECK (status IN ('pending', 'claimed', 'expired', 'cancelled')),
+
+  stellar_balance_id VARCHAR(128),
+  create_tx_hash     VARCHAR(64),
+  claim_tx_hash      VARCHAR(64),
+
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  claimed_at       TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS idx_cb_claims_org_id ON claimable_balance_claims(organization_id);
+CREATE INDEX IF NOT EXISTS idx_cb_claims_employee_id ON claimable_balance_claims(employee_id);
+CREATE INDEX IF NOT EXISTS idx_cb_claims_status ON claimable_balance_claims(status);
+CREATE INDEX IF NOT EXISTS idx_cb_claims_balance_id ON claimable_balance_claims(stellar_balance_id);
+
+CREATE TRIGGER update_claimable_balance_claims_updated_at
+  BEFORE UPDATE ON claimable_balance_claims
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at_column();

backend/src/db/migrations/017_create_claimable_balances.sql

@@ -0,0 +1,9 @@
+import { Router } from 'express';
+import { ClaimableBalanceController } from '../controllers/claimableBalanceController.js';
+
+const router = Router();
+
+router.post('/create-for-employee', ClaimableBalanceController.createForEmployee);
+router.get('/pending', ClaimableBalanceController.listPendingForWallet);
+
+export default router;

backend/src/routes/claimableBalanceRoutes.ts

@@ -1,23 +1,24 @@
 import { Router } from 'express';
-import { throttlingMiddleware } from '../../middlewares/throttlingMiddleware';
-import { authRateLimit, apiRateLimit, dataRateLimit } from '../../middlewares/rateLimitMiddleware';
-import searchRoutes from '../searchRoutes';
-import employeeRoutes from '../employeeRoutes';
-import paymentRoutes from '../paymentRoutes';
-import authRoutes from '../authRoutes';
-import assetRoutes from '../assetRoutes';
-import throttlingRoutes from '../throttlingRoutes';
-import payrollBonusRoutes from '../payrollBonusRoutes';
-import payrollAuditRoutes from '../payrollAuditRoutes';
-import auditRoutes from '../auditRoutes';
-import balanceRoutes from '../balanceRoutes';
-import trustlineRoutes from '../trustlineRoutes';
-import payrollRoutes from '../payroll.routes';
-import exportRoutes from '../exportRoutes';
-import taxRoutes from '../taxRoutes';
-import multiSigRoutes from '../multiSigRoutes';
-import rateLimitRoutes from '../rateLimitRoutes';
-import freezeRoutes from '../freezeRoutes';
+import { throttlingMiddleware } from '../../middlewares/throttlingMiddleware.js';
+import { authRateLimit, apiRateLimit, dataRateLimit } from '../../middlewares/rateLimitMiddleware.js';
+import searchRoutes from '../searchRoutes.js';
+import employeeRoutes from '../employeeRoutes.js';
+import paymentRoutes from '../paymentRoutes.js';
+import authRoutes from '../authRoutes.js';
+import assetRoutes from '../assetRoutes.js';
+import throttlingRoutes from '../throttlingRoutes.js';
+import payrollBonusRoutes from '../payrollBonusRoutes.js';
+import payrollAuditRoutes from '../payrollAuditRoutes.js';
+import auditRoutes from '../auditRoutes.js';
+import balanceRoutes from '../balanceRoutes.js';
+import trustlineRoutes from '../trustlineRoutes.js';
+import payrollRoutes from '../payroll.routes.js';
+import exportRoutes from '../exportRoutes.js';
+import taxRoutes from '../taxRoutes.js';
+import multiSigRoutes from '../multiSigRoutes.js';
+import rateLimitRoutes from '../rateLimitRoutes.js';
+import freezeRoutes from '../freezeRoutes.js';
+import claimableBalanceRoutes from '../claimableBalanceRoutes.js';
 
 const router = Router();
 
@@ -38,5 +39,6 @@ router.use('/taxes', dataRateLimit(), taxRoutes);
 router.use('/multisig', apiRateLimit(), multiSigRoutes);
 router.use('/rate-limit', apiRateLimit(), rateLimitRoutes);
 router.use('/freeze', apiRateLimit(), freezeRoutes);
+router.use('/claims', apiRateLimit(), claimableBalanceRoutes);
 
 export default router;