+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| src | +
+
+ |
+ 81.81% | +9/11 | +0% | +0/6 | +50% | +1/2 | +81.81% | +9/11 | +
| src/api/routes | +
+
+ |
+ 99.3% | +142/143 | +78.12% | +50/64 | +100% | +18/18 | +100% | +140/140 | +
| src/database | +
+
+ |
+ 8.33% | +1/12 | +0% | +0/4 | +25% | +1/4 | +8.33% | +1/12 | +
| src/services | +
+
+ |
+ 87.09% | +27/31 | +86.2% | +25/29 | +83.33% | +5/6 | +87.09% | +27/31 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 | + + + + + + + + + + + + + + + +42x + +42x +5x +5x +5x +5x +5x + +5x +1x +1x + + +4x +4x + +4x +1x +1x +1x +1x + + +4x + + +4x + + + + + +4x +4x + + +4x + + + + + + + +4x + +6x + + + + + + + + +4x + + + + + + + +42x + + | import { Router } from 'express';
+import type Database from 'better-sqlite3';
+
+interface EventRow {
+ id: number;
+ invoice_id: number;
+ event_type: string;
+ ledger: number;
+ timestamp: number;
+ data: string;
+ freelancer: string;
+ payer: string;
+ funder: string | null;
+}
+
+export function createEventsRouter(db: Database.Database): Router {
+ const router = Router();
+
+ router.get('/events', (req, res) => {
+ const address = req.query.address as string;
+ const typesStr = req.query.types as string | undefined;
+ const page = Math.max(1, parseInt(req.query.page as string || '1', 10));
+ const pageSize = Math.max(1, parseInt(req.query.pageSize as string || '20', 10));
+ const offset = (page - 1) * pageSize;
+
+ if (!address) {
+ res.status(400).json({ error: 'Address parameter is required' });
+ return;
+ }
+
+ const conditions: string[] = ['(i.freelancer = ? OR i.payer = ? OR i.funder = ?)'];
+ const params: any[] = [address, address, address];
+
+ if (typesStr) {
+ const types = typesStr.split(',');
+ const placeHolders = types.map(() => '?').join(',');
+ conditions.push(`e.event_type IN (${placeHolders})`);
+ params.push(...types);
+ }
+
+ const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+ // Count query
+ const countQuery = `
+ SELECT COUNT(*) as total
+ FROM events e
+ JOIN invoices i ON e.invoice_id = i.id
+ ${whereClause}
+ `;
+ const totalRow = db.prepare(countQuery).get(...params) as { total: number };
+ const total = totalRow ? totalRow.total : 0;
+
+ // Select query
+ const selectQuery = `
+ SELECT e.*, i.freelancer, i.payer, i.funder
+ FROM events e
+ JOIN invoices i ON e.invoice_id = i.id
+ ${whereClause}
+ ORDER BY e.timestamp DESC, e.id DESC
+ LIMIT ? OFFSET ?
+ `;
+ const rows = db.prepare(selectQuery).all(...params, pageSize, offset) as EventRow[];
+
+ const events = rows.map(r => ({
+ id: r.id,
+ invoiceId: r.invoice_id,
+ type: r.event_type,
+ ledger: r.ledger,
+ timestamp: r.timestamp,
+ data: JSON.parse(r.data || '{}'),
+ }));
+
+ res.json({
+ events,
+ total,
+ page,
+ pageSize
+ });
+ });
+
+ return router;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| events.ts | +
+
+ |
+ 100% | +28/28 | +75% | +9/12 | +100% | +4/4 | +100% | +26/26 | +
| invoices.ts | +
+
+ |
+ 98.48% | +65/66 | +72.22% | +26/36 | +100% | +6/6 | +100% | +65/65 | +
| leaderboard.ts | +
+
+ |
+ 100% | +14/14 | +100% | +4/4 | +100% | +2/2 | +100% | +14/14 | +
| reputation.ts | +
+
+ |
+ 100% | +23/23 | +100% | +9/9 | +100% | +3/3 | +100% | +23/23 | +
| stats.ts | +
+
+ |
+ 100% | +12/12 | +66.66% | +2/3 | +100% | +3/3 | +100% | +12/12 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +12x +12x +12x +12x +12x + + + +42x + +42x +10x +10x +1x +1x + + +9x + + + +9x +1x +1x + + +8x + + + +8x + + + + +8x +8x + +8x + +8x +8x + + + + +8x + + + + + + + + + + + + + + + + + + +4x + + + + + + + +8x + + +42x +3x + +3x +3x +3x + +3x +3x +3x + +3x +3x + +3x + + + + + + +3x +3x + +3x +3x + +3x +1x +1x + +3x +1x +1x + +3x +1x +1x + + +3x + +3x +3x +3x + +3x + + + + + +3x + +3x +4x + + + +4x +4x + +4x +4x +4x + + + + +4x + + + + + + + + + + + + + + + + + + + + + +3x + + + + + + + +42x + + | import { Router } from 'express';
+import type Database from 'better-sqlite3';
+
+interface InvoiceRow {
+ id: number;
+ freelancer: string;
+ payer: string;
+ token: string;
+ amount: string;
+ due_date: number;
+ discount_rate: number;
+ status: string;
+ funder: string | null;
+ funded_at: number | null;
+ amount_funded: string;
+ amount_paid: string;
+ referral_code: string | null;
+ submitter_reputation: number;
+ created_at: number;
+}
+
+interface EventRow {
+ event_type: string;
+ ledger: number;
+ timestamp: number;
+ data: string;
+}
+
+interface InvoiceResponse {
+ id: number;
+ freelancer: string;
+ payer: string;
+ token: string;
+ amount: string;
+ dueDate: number;
+ discountRate: number;
+ status: string;
+ funder: string | null;
+ fundedAt: number | null;
+ amountFunded: string;
+ amountPaid: string;
+ referralCode: string | null;
+ submitterReputation: number;
+ createdAt: number;
+ effectiveYieldBps: number;
+ remainingBalance: string;
+ daysUntilExpiry: number;
+ events: Array<{
+ type: string;
+ ledger: number;
+ timestamp: number;
+ data: Record<string, unknown>;
+ }>;
+}
+
+function computeEffectiveYieldBps(discountRate: number, dueDate: number): number {
+ const now = Math.floor(Date.now() / 1000);
+ const secondsToExpiry = dueDate - now;
+ Iif (secondsToExpiry <= 0) return 0;
+ const daysToExpiry = secondsToExpiry / (24 * 60 * 60);
+ return Math.round((discountRate * daysToExpiry) / 365);
+}
+
+export function createInvoicesRouter(db: Database.Database): Router {
+ const router = Router();
+
+ router.get('/invoices/:id', (req, res) => {
+ const invoiceId = parseInt(req.params.id, 10);
+ if (isNaN(invoiceId)) {
+ res.status(400).json({ error: 'Invalid invoice ID' });
+ return;
+ }
+
+ const invoice = db
+ .prepare('SELECT * FROM invoices WHERE id = ?')
+ .get(invoiceId) as InvoiceRow | undefined;
+
+ if (!invoice) {
+ res.status(404).json({ error: 'Invoice not found' });
+ return;
+ }
+
+ const eventRows = db
+ .prepare('SELECT * FROM events WHERE invoice_id = ? ORDER BY timestamp ASC')
+ .all(invoiceId) as EventRow[];
+
+ const effectiveYieldBps = computeEffectiveYieldBps(
+ invoice.discount_rate,
+ invoice.due_date
+ );
+
+ const amountFunded = BigInt(invoice.amount_funded || '0');
+ const amountPaid = BigInt(invoice.amount_paid || '0');
+ const remainingBalance =
+ amountPaid > amountFunded ? '0' : String(amountFunded - amountPaid);
+
+ const now = Math.floor(Date.now() / 1000);
+ const daysUntilExpiry = Math.max(
+ 0,
+ Math.ceil((invoice.due_date - now) / (24 * 60 * 60))
+ );
+
+ const response: InvoiceResponse = {
+ id: invoice.id,
+ freelancer: invoice.freelancer,
+ payer: invoice.payer,
+ token: invoice.token,
+ amount: invoice.amount,
+ dueDate: invoice.due_date,
+ discountRate: invoice.discount_rate,
+ status: invoice.status,
+ funder: invoice.funder,
+ fundedAt: invoice.funded_at,
+ amountFunded: invoice.amount_funded,
+ amountPaid: invoice.amount_paid,
+ referralCode: invoice.referral_code,
+ submitterReputation: invoice.submitter_reputation,
+ createdAt: invoice.created_at,
+ effectiveYieldBps,
+ remainingBalance,
+ daysUntilExpiry,
+ events: eventRows.map((e) => ({
+ type: e.event_type,
+ ledger: e.ledger,
+ timestamp: e.timestamp,
+ data: JSON.parse(e.data || '{}'),
+ })),
+ };
+
+ res.json(response);
+ });
+
+ router.get('/invoices', (req, res) => {
+ res.setHeader('Cache-Control', 'max-age=10');
+
+ const state = req.query.state as string | undefined;
+ const token = req.query.token as string | undefined;
+ const submitter = req.query.submitter as string | undefined;
+
+ const page = Math.max(1, parseInt(req.query.page as string || '1', 10));
+ const pageSize = Math.max(1, parseInt(req.query.pageSize as string || '20', 10));
+ const offset = (page - 1) * pageSize;
+
+ const sortByParam = req.query.sortBy as string || 'createdAt';
+ const sortOrderParam = (req.query.sortOrder as string || 'desc').toLowerCase();
+
+ const sortFieldMap: Record<string, string> = {
+ createdAt: 'created_at',
+ dueDate: 'due_date',
+ amount: 'CAST(amount AS REAL)',
+ discountRate: 'discount_rate'
+ };
+
+ const orderBy = sortFieldMap[sortByParam] || 'created_at';
+ const order = sortOrderParam === 'asc' ? 'ASC' : 'DESC';
+
+ const conditions: string[] = [];
+ const params: any[] = [];
+
+ if (state) {
+ conditions.push('status = ?');
+ params.push(state);
+ }
+ if (token) {
+ conditions.push('token = ?');
+ params.push(token);
+ }
+ if (submitter) {
+ conditions.push('freelancer = ?');
+ params.push(submitter);
+ }
+
+ const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+ const countQuery = `SELECT COUNT(*) as total FROM invoices ${whereClause}`;
+ const totalRow = db.prepare(countQuery).get(...params) as { total: number };
+ const total = totalRow ? totalRow.total : 0;
+
+ const selectQuery = `
+ SELECT * FROM invoices
+ ${whereClause}
+ ORDER BY ${orderBy} ${order}
+ LIMIT ? OFFSET ?
+ `;
+ const rows = db.prepare(selectQuery).all(...params, pageSize, offset) as InvoiceRow[];
+
+ const invoices = rows.map((invoice) => {
+ const effectiveYieldBps = computeEffectiveYieldBps(
+ invoice.discount_rate,
+ invoice.due_date
+ );
+ const amountFunded = BigInt(invoice.amount_funded || '0');
+ const amountPaid = BigInt(invoice.amount_paid || '0');
+ const remainingBalance =
+ amountPaid > amountFunded ? '0' : String(amountFunded - amountPaid);
+ const now = Math.floor(Date.now() / 1000);
+ const daysUntilExpiry = Math.max(
+ 0,
+ Math.ceil((invoice.due_date - now) / (24 * 60 * 60))
+ );
+
+ return {
+ id: invoice.id,
+ freelancer: invoice.freelancer,
+ payer: invoice.payer,
+ token: invoice.token,
+ amount: invoice.amount,
+ dueDate: invoice.due_date,
+ discountRate: invoice.discount_rate,
+ status: invoice.status,
+ funder: invoice.funder,
+ fundedAt: invoice.funded_at,
+ amountFunded: invoice.amount_funded,
+ amountPaid: invoice.amount_paid,
+ referralCode: invoice.referral_code,
+ submitterReputation: invoice.submitter_reputation,
+ createdAt: invoice.created_at,
+ effectiveYieldBps,
+ remainingBalance,
+ daysUntilExpiry,
+ };
+ });
+
+ res.json({
+ invoices,
+ total,
+ page,
+ pageSize
+ });
+ });
+
+ return router;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 | + + + + +42x + +42x +8x +8x + +8x +8x +3x +3x +1x +1x + +2x + + +7x +7x + + +42x + + | import { Router } from 'express';
+import type Database from 'better-sqlite3';
+import { getLeaderboard, type LeaderboardEntry } from '../../services/leaderboardService.js';
+
+export function createLeaderboardRouter(db: Database.Database): Router {
+ const router = Router();
+
+ router.get('/leaderboard', (req, res) => {
+ const limitParam = req.query.limit;
+ const token = req.query.token as string | undefined;
+
+ let limit = 50;
+ if (limitParam !== undefined) {
+ const parsed = parseInt(limitParam as string, 10);
+ if (isNaN(parsed) || parsed < 1) {
+ res.status(400).json({ error: 'Invalid limit parameter' });
+ return;
+ }
+ limit = Math.min(parsed, 100);
+ }
+
+ const entries: LeaderboardEntry[] = getLeaderboard(db, limit, token);
+ res.json(entries);
+ });
+
+ return router;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +42x + +42x +9x +9x + +9x + + + + + + + + + + + +9x +1x + + + + + + + +1x + + +8x +8x +1x +7x +1x + + +8x +8x +1x +7x +1x + + +8x + + + + + + + + + + + + + + + +8x + + + + + +13x + + + + + + + +8x + + +42x + + | import { Router } from 'express';
+import type Database from 'better-sqlite3';
+
+interface ReputationUpdateRow {
+ new_score: number;
+ invoices_submitted: number;
+ invoices_paid: number;
+ invoices_defaulted: number;
+ ledger: number;
+ timestamp: number;
+ event_type: string;
+}
+
+interface HistoryEntry {
+ ledger: number;
+ score: number;
+ eventType: string;
+ timestamp: number;
+}
+
+interface ReputationResponse {
+ score: number;
+ invoicesPaid: number;
+ invoicesDefaulted: number;
+ invoicesSubmitted: number;
+ lastActivityLedger: number;
+ history: HistoryEntry[];
+}
+
+export function createReputationRouter(db: Database.Database): Router {
+ const router = Router();
+
+ router.get('/reputation/:address', (req, res) => {
+ const { address } = req.params;
+ const historyPeriod = (req.query.historyPeriod as string) || 'all';
+
+ const latestRow = db
+ .prepare(
+ `
+ SELECT new_score, invoices_submitted, invoices_paid, invoices_defaulted, ledger
+ FROM reputation_updates
+ WHERE address = ?
+ ORDER BY id DESC
+ LIMIT 1
+ `
+ )
+ .get(address) as ReputationUpdateRow | undefined;
+
+ if (!latestRow) {
+ res.json({
+ score: 0,
+ invoicesPaid: 0,
+ invoicesDefaulted: 0,
+ invoicesSubmitted: 0,
+ lastActivityLedger: 0,
+ history: [],
+ });
+ return;
+ }
+
+ let dateFilter = '';
+ if (historyPeriod === '30d') {
+ dateFilter = 'AND timestamp >= ?';
+ } else if (historyPeriod === '90d') {
+ dateFilter = 'AND timestamp >= ?';
+ }
+
+ let historyParams: (string | number)[] = [address];
+ if (historyPeriod === '30d') {
+ historyParams.push(Math.floor(Date.now() / 1000) - 30 * 24 * 60 * 60);
+ } else if (historyPeriod === '90d') {
+ historyParams.push(Math.floor(Date.now() / 1000) - 90 * 24 * 60 * 60);
+ }
+
+ const historyRows = db
+ .prepare(
+ `
+ SELECT new_score, ledger, event_type, timestamp
+ FROM reputation_updates
+ WHERE address = ? ${dateFilter}
+ ORDER BY timestamp ASC
+ `
+ )
+ .all(...historyParams) as Array<{
+ new_score: number;
+ ledger: number;
+ event_type: string;
+ timestamp: number;
+ }>;
+
+ const response: ReputationResponse = {
+ score: latestRow.new_score,
+ invoicesPaid: latestRow.invoices_paid,
+ invoicesDefaulted: latestRow.invoices_defaulted,
+ invoicesSubmitted: latestRow.invoices_submitted,
+ lastActivityLedger: latestRow.ledger,
+ history: historyRows.map((row) => ({
+ ledger: row.ledger,
+ score: row.new_score,
+ eventType: row.event_type,
+ timestamp: row.timestamp,
+ })),
+ };
+
+ res.json(response);
+ });
+
+ return router;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 | + + + + + + + + + +42x + +42x +7x +7x + + +42x +3x +3x +1x +1x + +2x +2x + + +42x + + | import { Router } from 'express';
+import type Database from 'better-sqlite3';
+import {
+ getProtocolStats,
+ getStatsHistory,
+ type ProtocolStats,
+ type StatsHistoryEntry,
+} from '../../services/statsService.js';
+
+export function createStatsRouter(db: Database.Database): Router {
+ const router = Router();
+
+ router.get('/stats', (_req, res) => {
+ const stats: ProtocolStats = getProtocolStats(db);
+ res.json(stats);
+ });
+
+ router.get('/stats/history', (req, res) => {
+ const period = (req.query.period as string) || '30d';
+ if (!['30d', '90d', 'all'].includes(period)) {
+ res.status(400).json({ error: 'Invalid period. Use 30d, 90d, or all' });
+ return;
+ }
+ const history: StatsHistoryEntry[] = getStatsHistory(db, period as '30d' | '90d' | 'all');
+ res.json(history);
+ });
+
+ return router;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 | + + + + + + + + +42x + +42x + +42x +42x +42x +42x +42x + +42x + + + +42x + + | import express from 'express';
+import type Database from 'better-sqlite3';
+import { createLeaderboardRouter } from './api/routes/leaderboard.js';
+import { createReputationRouter } from './api/routes/reputation.js';
+import { createStatsRouter } from './api/routes/stats.js';
+import { createInvoicesRouter } from './api/routes/invoices.js';
+import { createEventsRouter } from './api/routes/events.js';
+
+export function createApp(db: Database.Database): express.Express {
+ const app = express();
+
+ app.use(express.json());
+
+ app.use(createLeaderboardRouter(db));
+ app.use(createReputationRouter(db));
+ app.use(createStatsRouter(db));
+ app.use(createInvoicesRouter(db));
+ app.use(createEventsRouter(db));
+
+ app.get('/health', (_req, res) => {
+ res.json({ status: 'ok' });
+ });
+
+ return app;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 | + + + + + + + | export const config = {
+ port: parseInt(process.env.PORT || '3001', 10),
+ dbPath: process.env.DB_PATH || './indexer.db',
+ cacheTtlMs: parseInt(process.env.CACHE_TTL_MS || '60000', 10),
+ maxLeaderboardLimit: 100,
+ defaultLeaderboardLimit: 50,
+};
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 | + + + + + + + + + + + + + + + + + + + + + + + + + | import Database from 'better-sqlite3';
+import { initializeSchema } from './schema.js';
+
+let db: Database.Database | null = null;
+
+export function getDb(dbPath?: string): Database.Database {
+ Iif (!db) {
+ db = new Database(dbPath || ':memory:');
+ db.pragma('journal_mode = WAL');
+ db.pragma('foreign_keys = ON');
+ initializeSchema(db);
+ }
+ return db;
+}
+
+export function closeDb(): void {
+ Iif (db) {
+ db.close();
+ db = null;
+ }
+}
+
+export function resetDb(): void {
+ closeDb();
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ ++ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 | + + +42x + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | import type Database from 'better-sqlite3';
+
+export function initializeSchema(db: Database.Database): void {
+ db.exec(`
+ CREATE TABLE IF NOT EXISTS invoices (
+ id INTEGER PRIMARY KEY,
+ freelancer TEXT NOT NULL,
+ payer TEXT NOT NULL,
+ token TEXT NOT NULL,
+ amount TEXT NOT NULL,
+ due_date INTEGER NOT NULL,
+ discount_rate INTEGER NOT NULL,
+ status TEXT NOT NULL DEFAULT 'Pending',
+ funder TEXT,
+ funded_at INTEGER,
+ amount_funded TEXT NOT NULL DEFAULT '0',
+ amount_paid TEXT NOT NULL DEFAULT '0',
+ referral_code TEXT,
+ submitter_reputation INTEGER NOT NULL DEFAULT 0,
+ created_at INTEGER NOT NULL
+ );
+
+ CREATE TABLE IF NOT EXISTS events (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ invoice_id INTEGER NOT NULL,
+ event_type TEXT NOT NULL,
+ ledger INTEGER NOT NULL,
+ timestamp INTEGER NOT NULL,
+ data TEXT NOT NULL DEFAULT '{}',
+ FOREIGN KEY (invoice_id) REFERENCES invoices(id)
+ );
+
+ CREATE TABLE IF NOT EXISTS reputation_updates (
+ id INTEGER PRIMARY KEY,
+ address TEXT NOT NULL,
+ event_type TEXT NOT NULL DEFAULT 'reputation_updated',
+ old_score INTEGER NOT NULL DEFAULT 0,
+ new_score INTEGER NOT NULL DEFAULT 0,
+ invoices_submitted INTEGER NOT NULL DEFAULT 0,
+ invoices_paid INTEGER NOT NULL DEFAULT 0,
+ invoices_defaulted INTEGER NOT NULL DEFAULT 0,
+ ledger INTEGER NOT NULL,
+ timestamp INTEGER NOT NULL
+ );
+
+ CREATE TABLE IF NOT EXISTS stats_snapshots (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ total_invoices INTEGER NOT NULL DEFAULT 0,
+ total_funded INTEGER NOT NULL DEFAULT 0,
+ total_paid INTEGER NOT NULL DEFAULT 0,
+ total_cancelled INTEGER NOT NULL DEFAULT 0,
+ total_expired INTEGER NOT NULL DEFAULT 0,
+ total_disputed INTEGER NOT NULL DEFAULT 0,
+ volume_by_token TEXT NOT NULL DEFAULT '{}',
+ avg_discount_rate_bps REAL NOT NULL DEFAULT 0,
+ dispute_rate REAL NOT NULL DEFAULT 0,
+ last_updated_at INTEGER NOT NULL
+ );
+
+ CREATE TABLE IF NOT EXISTS stats_history (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ date TEXT NOT NULL,
+ total_invoices INTEGER NOT NULL DEFAULT 0,
+ total_funded INTEGER NOT NULL DEFAULT 0,
+ total_paid INTEGER NOT NULL DEFAULT 0,
+ total_volume TEXT NOT NULL DEFAULT '0',
+ avg_discount_rate_bps REAL NOT NULL DEFAULT 0
+ );
+
+ CREATE INDEX IF NOT EXISTS idx_events_invoice_id ON events(invoice_id);
+ CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
+ CREATE INDEX IF NOT EXISTS idx_reputation_address ON reputation_updates(address);
+ CREATE INDEX IF NOT EXISTS idx_reputation_timestamp ON reputation_updates(timestamp);
+ CREATE INDEX IF NOT EXISTS idx_invoices_status ON invoices(status);
+ CREATE INDEX IF NOT EXISTS idx_stats_history_date ON stats_history(date);
+ CREATE INDEX IF NOT EXISTS idx_invoices_freelancer ON invoices(freelancer);
+ CREATE INDEX IF NOT EXISTS idx_invoices_payer ON invoices(payer);
+ CREATE INDEX IF NOT EXISTS idx_invoices_funder ON invoices(funder);
+ `);
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ ++ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| leaderboardService.ts | +
+
+ |
+ 87.5% | +7/8 | +60% | +3/5 | +100% | +2/2 | +87.5% | +7/8 | +
| statsService.ts | +
+
+ |
+ 86.95% | +20/23 | +91.66% | +22/24 | +75% | +3/4 | +86.95% | +20/23 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 | + + + + + + + + + + + + + + + + + + + + + + +7x + + + +7x + + + + + + + + + + + + + + + + + + + + + +7x + + + + + + + + + + + + + + + + + + +7x + + + + + + + +7x +16x +16x + + + + + + + + + + | import type Database from 'better-sqlite3';
+
+export interface LeaderboardEntry {
+ rank: number;
+ address: string;
+ score: number;
+ invoicesPaid: number;
+ invoicesDefaulted: number;
+ totalVolume: string;
+}
+
+interface ReputationRow {
+ address: string;
+ new_score: number;
+ invoices_paid: number;
+ invoices_defaulted: number;
+}
+
+export function getLeaderboard(
+ db: Database.Database,
+ limit: number = 50,
+ token?: string
+): LeaderboardEntry[] {
+ const safeLimit = Math.min(Math.max(1, limit), 100);
+
+ let rows: ReputationRow[];
+
+ Iif (token) {
+ rows = db
+ .prepare(
+ `
+ SELECT
+ r.address,
+ r.new_score,
+ r.invoices_paid,
+ r.invoices_defaulted
+ FROM reputation_updates r
+ WHERE r.id IN (
+ SELECT MAX(id) FROM reputation_updates GROUP BY address
+ )
+ AND r.address IN (
+ SELECT DISTINCT payer FROM invoices WHERE token = ?
+ )
+ ORDER BY r.new_score DESC
+ LIMIT ?
+ `
+ )
+ .all(token, safeLimit) as ReputationRow[];
+ } else {
+ rows = db
+ .prepare(
+ `
+ SELECT
+ r.address,
+ r.new_score,
+ r.invoices_paid,
+ r.invoices_defaulted
+ FROM reputation_updates r
+ WHERE r.id IN (
+ SELECT MAX(id) FROM reputation_updates GROUP BY address
+ )
+ ORDER BY r.new_score DESC
+ LIMIT ?
+ `
+ )
+ .all(safeLimit) as ReputationRow[];
+ }
+
+ const volumeStmt = db.prepare(
+ `SELECT COALESCE(SUM(CAST(amount_paid AS INTEGER)), 0) as vol
+ FROM events e
+ JOIN invoices i ON e.invoice_id = i.id
+ WHERE e.event_type = 'paid' AND e.data LIKE '%"payer":"%'
+ AND json_extract(e.data, '$.payer') = ?`
+ );
+
+ return rows.map((row, idx) => {
+ const volResult = volumeStmt.get(row.address) as { vol: number } | undefined;
+ return {
+ rank: idx + 1,
+ address: row.address,
+ score: row.new_score,
+ invoicesPaid: row.invoices_paid,
+ invoicesDefaulted: row.invoices_defaulted,
+ totalVolume: String(volResult?.vol || 0),
+ };
+ });
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + +5x + + + + + +7x + +7x +1x + + +6x + + + + + + + + + + + + + + + + + + + + + + + +6x + + + + + + + + + + +6x +6x +6x + + +6x + +6x + + + + + + + + + + + + +6x +6x + + + + + + +2x +2x +1x +1x + + + +2x + + + + + + + + + + + + + + + + +2x + + + + + + + + +9x + + | import type Database from 'better-sqlite3';
+
+export interface ProtocolStats {
+ totalInvoices: number;
+ totalFunded: number;
+ totalPaid: number;
+ totalCancelled: number;
+ totalExpired: number;
+ totalDisputed: number;
+ volumeByToken: Record<string, string>;
+ avgDiscountRateBps: number;
+ disputeRate: number;
+ lastUpdatedAt: number;
+}
+
+export interface StatsHistoryEntry {
+ date: string;
+ totalInvoices: number;
+ totalFunded: number;
+ totalPaid: number;
+ totalVolume: string;
+ avgDiscountRateBps: number;
+}
+
+interface CachedStats {
+ stats: ProtocolStats;
+ cachedAt: number;
+}
+
+let cachedStats: CachedStats | null = null;
+
+export function getProtocolStats(
+ db: Database.Database,
+ cacheTtlMs: number = 60000
+): ProtocolStats {
+ const now = Date.now();
+
+ if (cachedStats && now - cachedStats.cachedAt < cacheTtlMs) {
+ return cachedStats.stats;
+ }
+
+ const counts = db
+ .prepare(
+ `
+ SELECT
+ COUNT(*) as total,
+ SUM(CASE WHEN status = 'Funded' OR status = 'Paid' OR status = 'Defaulted' THEN 1 ELSE 0 END) as funded,
+ SUM(CASE WHEN status = 'Paid' THEN 1 ELSE 0 END) as paid,
+ SUM(CASE WHEN status = 'Cancelled' THEN 1 ELSE 0 END) as cancelled,
+ SUM(CASE WHEN status = 'Expired' THEN 1 ELSE 0 END) as expired,
+ SUM(CASE WHEN status = 'Disputed' THEN 1 ELSE 0 END) as disputed,
+ AVG(CAST(discount_rate AS REAL)) as avg_discount
+ FROM invoices
+ `
+ )
+ .get() as {
+ total: number;
+ funded: number;
+ paid: number;
+ cancelled: number;
+ expired: number;
+ disputed: number;
+ avg_discount: number;
+ };
+
+ const tokenVolumes = db
+ .prepare(
+ `
+ SELECT token, COALESCE(SUM(CAST(amount_paid AS INTEGER)), 0) as volume
+ FROM invoices
+ WHERE CAST(amount_paid AS INTEGER) > 0
+ GROUP BY token
+ `
+ )
+ .all() as Array<{ token: string; volume: number }>;
+
+ const volumeByToken: Record<string, string> = {};
+ for (const row of tokenVolumes) {
+ volumeByToken[row.token] = String(row.volume);
+ }
+
+ const disputeRate = counts.total > 0 ? counts.disputed / counts.total : 0;
+
+ const stats: ProtocolStats = {
+ totalInvoices: counts.total || 0,
+ totalFunded: counts.funded || 0,
+ totalPaid: counts.paid || 0,
+ totalCancelled: counts.cancelled || 0,
+ totalExpired: counts.expired || 0,
+ totalDisputed: counts.disputed || 0,
+ volumeByToken,
+ avgDiscountRateBps: Math.round(counts.avg_discount || 0),
+ disputeRate: Math.round(disputeRate * 10000) / 10000,
+ lastUpdatedAt: now,
+ };
+
+ cachedStats = { stats, cachedAt: now };
+ return stats;
+}
+
+export function getStatsHistory(
+ db: Database.Database,
+ period: '30d' | '90d' | 'all' = '30d'
+): StatsHistoryEntry[] {
+ let dateFilter = '';
+ if (period === '30d') {
+ dateFilter = "WHERE date >= date('now', '-30 days')";
+ } else Iif (period === '90d') {
+ dateFilter = "WHERE date >= date('now', '-90 days')";
+ }
+
+ const rows = db
+ .prepare(
+ `
+ SELECT
+ date,
+ total_invoices,
+ total_funded,
+ total_paid,
+ total_volume,
+ avg_discount_rate_bps
+ FROM stats_history
+ ${dateFilter}
+ ORDER BY date ASC
+ `
+ )
+ .all() as StatsHistoryEntry[];
+
+ return rows;
+}
+
+export function refreshStats(db: Database.Database): ProtocolStats {
+ cachedStats = null;
+ return getProtocolStats(db);
+}
+
+export function clearStatsCache(): void {
+ cachedStats = null;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| src | +
+
+ |
+ 0% | +0/149 | +0% | +0/89 | +0% | +0/53 | +0% | +0/109 | +
| src/events | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| src/methods | +
+
+ |
+ 0% | +0/71 | +0% | +0/69 | +0% | +0/8 | +0% | +0/71 | +
| src/signers | +
+
+ |
+ 0% | +0/90 | +0% | +0/45 | +0% | +0/23 | +0% | +0/88 | +
| src/types | +
+
+ |
+ 0% | +0/12 | +0% | +0/4 | +0% | +0/2 | +0% | +0/12 | +
| src/utils | +
+
+ |
+ 0% | +0/75 | +0% | +0/42 | +0% | +0/14 | +0% | +0/74 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * ILNClient — entry point for the Invoice Liquidity Network SDK.
+ *
+ * Provides factory methods for common environments so integrators can
+ * get started with a one-liner:
+ *
+ * ```ts
+ * import { ILNClient } from "@iln/sdk";
+ *
+ * const client = ILNClient.testnet(signer);
+ * const reputation = await client.getReputation("G...");
+ * ```
+ *
+ * ## Architecture
+ *
+ * `ILNClient` is a thin wrapper around the SDK's free functions. It holds
+ * the RPC server, network passphrase, contract address, and signer so
+ * every method call uses the same configuration automatically.
+ */
+import { SorobanRpc } from "@stellar/stellar-sdk";
+import type { ISigner } from "./signers/ISigner.js";
+/**
+ * Public Soroban RPC endpoint for Stellar Testnet.
+ */
+export declare const TESTNET_RPC_URL = "https://soroban-testnet.stellar.org";
+/**
+ * Public Soroban RPC endpoint for Stellar Mainnet (Pubnet).
+ */
+export declare const MAINNET_RPC_URL = "https://soroban.stellar.org";
+/** Full configuration for a custom ILNClient. */
+export interface ILNClientConfig {
+ /** Soroban RPC endpoint URL. */
+ rpcUrl: string;
+ /** Stellar network passphrase (e.g. `Networks.TESTNET`). */
+ networkPassphrase: string;
+ /** Deployed invoice-liquidity contract address. */
+ contractId: string;
+ /**
+ * Optional signer for methods that require authentication (e.g. fundInvoice).
+ * Read-only methods like getReputation work without a signer.
+ */
+ signer?: ISigner;
+}
+/**
+ * Configured SDK client bound to a specific network and contract.
+ *
+ * @example
+ * ```ts
+ * // Testnet
+ * const client = ILNClient.testnet(mySigner);
+ *
+ * // Custom RPC (e.g. local validator node)
+ * const client = ILNClient.custom({
+ * rpcUrl: "http://localhost:8000/soroban/rpc",
+ * networkPassphrase: Networks.STANDALONE,
+ * contractId: "CDEPLOYED...",
+ * signer: mySigner,
+ * });
+ * ```
+ */
+export declare class ILNClient {
+ /** Soroban RPC server instance. */
+ readonly rpc: SorobanRpc.Server;
+ /** Stellar network passphrase. */
+ readonly networkPassphrase: string;
+ /** Deployed invoice-liquidity contract address. */
+ readonly contractId: string;
+ /** Optional signer for authenticated methods. */
+ readonly signer?: ISigner;
+ private _getReputation?;
+ private _getContractStats?;
+ constructor(config: ILNClientConfig);
+ /**
+ * Create a client pre-configured for Stellar Testnet.
+ *
+ * @param signer - Optional signer for authenticated methods
+ * @param options - Override defaults (rpcUrl, contractId)
+ *
+ * @example
+ * ```ts
+ * const client = ILNClient.testnet(freighterSigner);
+ * ```
+ */
+ static testnet(signer?: ISigner, options?: {
+ rpcUrl?: string;
+ contractId?: string;
+ }): ILNClient;
+ /**
+ * Create a client pre-configured for Stellar Mainnet (Pubnet).
+ *
+ * @param signer - Optional signer for authenticated methods
+ * @param options - Override defaults (rpcUrl, contractId)
+ *
+ * @example
+ * ```ts
+ * const client = ILNClient.mainnet(freighterSigner);
+ * ```
+ */
+ static mainnet(signer?: ISigner, options?: {
+ rpcUrl?: string;
+ contractId?: string;
+ }): ILNClient;
+ /**
+ * Create a client with fully custom configuration.
+ *
+ * Use this for local development (standalone network), Futurenet, or
+ * private Stellar deployments.
+ *
+ * @param config - Full ILNClientConfig
+ */
+ static custom(config: ILNClientConfig): ILNClient;
+ /**
+ * Fetch the detailed reputation profile for an address.
+ *
+ * Read-only; does not require a signer.
+ *
+ * @param address - Stellar G… address to query
+ * @returns ReputationProfile (zeroed for unknown addresses)
+ */
+ getReputation(address: string): Promise<import("./methods/reputation.js").ReputationProfile>;
+ /**
+ * Fetch protocol-wide statistics.
+ *
+ * Read-only; does not require a signer.
+ *
+ * @returns ContractStats
+ */
+ getContractStats(): Promise<import("./methods/stats.js").ContractStats>;
+}
+/**
+ * Default ILNClient singleton.
+ *
+ * Must be initialised via `iln.configure(...)` before use.
+ *
+ * @example
+ * ```ts
+ * import { iln } from "@iln/sdk";
+ *
+ * iln.configure({ rpcUrl: "...", networkPassphrase: Networks.TESTNET, contractId: "..." });
+ * await iln.getReputation("G...");
+ * ```
+ */
+declare class ILNSingleton {
+ private _client;
+ configure(config: ILNClientConfig): void;
+ /** Access the underlying client. Throws if not configured. */
+ get client(): ILNClient;
+ getReputation(address: string): Promise<import("./methods/reputation.js").ReputationProfile>;
+ getContractStats(): Promise<import("./methods/stats.js").ContractStats>;
+}
+export declare const iln: ILNSingleton;
+export {};
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 | + + + + + + + | /**
+ * Tests for ILNClient — covers:
+ * - testnet / mainnet / custom factory methods
+ * - singleton iln.configure / iln.getReputation / iln.getContractStats
+ * - Preset defaults (RPC URL, network passphrase, contract ID)
+ */
+export {};
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * ILNClient — entry point for the Invoice Liquidity Network SDK.
+ *
+ * Provides factory methods for common environments so integrators can
+ * get started with a one-liner:
+ *
+ * ```ts
+ * import { ILNClient } from "@iln/sdk";
+ *
+ * const client = ILNClient.testnet(signer);
+ * const reputation = await client.getReputation("G...");
+ * ```
+ *
+ * ## Architecture
+ *
+ * `ILNClient` is a thin wrapper around the SDK's free functions. It holds
+ * the RPC server, network passphrase, contract address, and signer so
+ * every method call uses the same configuration automatically.
+ */
+
+import { SorobanRpc } from "@stellar/stellar-sdk";
+import type { ISigner } from "./signers/ISigner.js";
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+/**
+ * Public Soroban RPC endpoint for Stellar Testnet.
+ */
+export const TESTNET_RPC_URL = "https://soroban-testnet.stellar.org";
+
+/**
+ * Public Soroban RPC endpoint for Stellar Mainnet (Pubnet).
+ */
+export const MAINNET_RPC_URL = "https://soroban.stellar.org";
+
+// ---------------------------------------------------------------------------
+// Configuration types
+// ---------------------------------------------------------------------------
+
+/** Full configuration for a custom ILNClient. */
+export interface ILNClientConfig {
+ /** Soroban RPC endpoint URL. */
+ rpcUrl: string;
+ /** Stellar network passphrase (e.g. `Networks.TESTNET`). */
+ networkPassphrase: string;
+ /** Deployed invoice-liquidity contract address. */
+ contractId: string;
+ /**
+ * Optional signer for methods that require authentication (e.g. fundInvoice).
+ * Read-only methods like getReputation work without a signer.
+ */
+ signer?: ISigner;
+}
+
+// ---------------------------------------------------------------------------
+// ILNClient
+// ---------------------------------------------------------------------------
+
+/**
+ * Configured SDK client bound to a specific network and contract.
+ *
+ * @example
+ * ```ts
+ * // Testnet
+ * const client = ILNClient.testnet(mySigner);
+ *
+ * // Custom RPC (e.g. local validator node)
+ * const client = ILNClient.custom({
+ * rpcUrl: "http://localhost:8000/soroban/rpc",
+ * networkPassphrase: Networks.STANDALONE,
+ * contractId: "CDEPLOYED...",
+ * signer: mySigner,
+ * });
+ * ```
+ */
+export class ILNClient {
+ /** Soroban RPC server instance. */
+ readonly rpc: SorobanRpc.Server;
+ /** Stellar network passphrase. */
+ readonly networkPassphrase: string;
+ /** Deployed invoice-liquidity contract address. */
+ readonly contractId: string;
+ /** Optional signer for authenticated methods. */
+ readonly signer?: ISigner;
+
+ // Cached imports (lazy-loaded for tree-shaking)
+ private _getReputation?: typeof import("./methods/reputation.js").getReputation;
+ private _getContractStats?: typeof import("./methods/stats.js").getContractStats;
+
+ constructor(config: ILNClientConfig) {
+ this.rpc = new SorobanRpc.Server(config.rpcUrl);
+ this.networkPassphrase = config.networkPassphrase;
+ this.contractId = config.contractId;
+ this.signer = config.signer;
+ }
+
+ // --------------------------------------------------------------------------
+ // Factory methods
+ // --------------------------------------------------------------------------
+
+ /**
+ * Create a client pre-configured for Stellar Testnet.
+ *
+ * @param signer - Optional signer for authenticated methods
+ * @param options - Override defaults (rpcUrl, contractId)
+ *
+ * @example
+ * ```ts
+ * const client = ILNClient.testnet(freighterSigner);
+ * ```
+ */
+ static testnet(
+ signer?: ISigner,
+ options?: { rpcUrl?: string; contractId?: string }
+ ): ILNClient {
+ return new ILNClient({
+ rpcUrl: options?.rpcUrl ?? TESTNET_RPC_URL,
+ networkPassphrase: "Test SDF Network ; September 2015",
+ contractId:
+ options?.contractId ??
+ // Published testnet deployment: the canonical contract ID from
+ // the latest testnet CI/CD deployment. Update here when redeploying.
+ // TODO: replace with actual testnet contract ID once deployed
+ "CD2Q6M76VFLHNHDNROENMX7PJ5OBYBMVPM73S4M6XAJXN3NKCBJQPLUC",
+ signer,
+ });
+ }
+
+ /**
+ * Create a client pre-configured for Stellar Mainnet (Pubnet).
+ *
+ * @param signer - Optional signer for authenticated methods
+ * @param options - Override defaults (rpcUrl, contractId)
+ *
+ * @example
+ * ```ts
+ * const client = ILNClient.mainnet(freighterSigner);
+ * ```
+ */
+ static mainnet(
+ signer?: ISigner,
+ options?: { rpcUrl?: string; contractId?: string }
+ ): ILNClient {
+ // Future-proof: we allow configuring mainnet ahead of deployment
+ // so integrators can test their integration code against the API shape.
+ return new ILNClient({
+ rpcUrl: options?.rpcUrl ?? MAINNET_RPC_URL,
+ networkPassphrase: "Public Global Stellar Network ; September 2015",
+ contractId:
+ options?.contractId ??
+ // TODO: replace with actual mainnet contract ID after mainnet deployment
+ "",
+ signer,
+ });
+ }
+
+ /**
+ * Create a client with fully custom configuration.
+ *
+ * Use this for local development (standalone network), Futurenet, or
+ * private Stellar deployments.
+ *
+ * @param config - Full ILNClientConfig
+ */
+ static custom(config: ILNClientConfig): ILNClient {
+ return new ILNClient(config);
+ }
+
+ // --------------------------------------------------------------------------
+ // Methods
+ // --------------------------------------------------------------------------
+
+ /**
+ * Fetch the detailed reputation profile for an address.
+ *
+ * Read-only; does not require a signer.
+ *
+ * @param address - Stellar G… address to query
+ * @returns ReputationProfile (zeroed for unknown addresses)
+ */
+ async getReputation(
+ address: string
+ ): Promise<import("./methods/reputation.js").ReputationProfile> {
+ Iif (!this._getReputation) {
+ this._getReputation = (await import("./methods/reputation.js"))
+ .getReputation;
+ }
+ return this._getReputation(this.rpc, this.contractId, address, this.networkPassphrase);
+ }
+
+ /**
+ * Fetch protocol-wide statistics.
+ *
+ * Read-only; does not require a signer.
+ *
+ * @returns ContractStats
+ */
+ async getContractStats(): Promise<
+ import("./methods/stats.js").ContractStats
+ > {
+ Iif (!this._getContractStats) {
+ this._getContractStats = (await import("./methods/stats.js"))
+ .getContractStats;
+ }
+ return this._getContractStats(this.rpc, this.contractId, this.networkPassphrase);
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+
+/**
+ * Default ILNClient singleton.
+ *
+ * Must be initialised via `iln.configure(...)` before use.
+ *
+ * @example
+ * ```ts
+ * import { iln } from "@iln/sdk";
+ *
+ * iln.configure({ rpcUrl: "...", networkPassphrase: Networks.TESTNET, contractId: "..." });
+ * await iln.getReputation("G...");
+ * ```
+ */
+class ILNSingleton {
+ private _client: ILNClient | null = null;
+
+ configure(config: ILNClientConfig): void {
+ this._client = new ILNClient(config);
+ }
+
+ /** Access the underlying client. Throws if not configured. */
+ get client(): ILNClient {
+ Iif (!this._client) {
+ throw new Error(
+ "ILN singleton not configured. Call iln.configure({...}) first."
+ );
+ }
+ return this._client;
+ }
+
+ async getReputation(address: string) {
+ return this.client.getReputation(address);
+ }
+
+ async getContractStats() {
+ return this.client.getContractStats();
+ }
+}
+
+export const iln = new ILNSingleton();
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | export class ILNError extends Error {
+ constructor(message: string, public readonly code?: number) {
+ super(message);
+ this.name = this.constructor.name;
+ }
+
+ static InvoiceNotFound = class extends ILNError { constructor(msg = "Invoice not found") { super(msg, 1); } };
+ static AlreadyFunded = class extends ILNError { constructor(msg = "Invoice already funded") { super(msg, 2); } };
+ static AlreadyPaid = class extends ILNError { constructor(msg = "Invoice already paid") { super(msg, 3); } };
+ static NotFunded = class extends ILNError { constructor(msg = "Invoice not funded") { super(msg, 4); } };
+ static Unauthorized = class extends ILNError { constructor(msg = "Unauthorized") { super(msg, 5); } };
+ static InvalidAmount = class extends ILNError { constructor(msg = "Invalid amount") { super(msg, 6); } };
+ static InvalidDiscountRate = class extends ILNError { constructor(msg = "Invalid discount rate") { super(msg, 7); } };
+ static InvalidDueDate = class extends ILNError { constructor(msg = "Invalid due date") { super(msg, 8); } };
+ static InvoiceDefaulted = class extends ILNError { constructor(msg = "Invoice defaulted") { super(msg, 9); } };
+ static NothingToClaim = class extends ILNError { constructor(msg = "Nothing to claim") { super(msg, 10); } };
+ static NotYetDefaulted = class extends ILNError { constructor(msg = "Not yet defaulted") { super(msg, 11); } };
+ static OverfundingRejected = class extends ILNError { constructor(msg = "Overfunding rejected") { super(msg, 12); } };
+ static InvoiceExpired = class extends ILNError { constructor(msg = "Invoice expired") { super(msg, 13); } };
+ static BatchTooLarge = class extends ILNError { constructor(msg = "Batch too large") { super(msg, 14); } };
+ static AlreadyCancelled = class extends ILNError { constructor(msg = "Already cancelled") { super(msg, 15); } };
+ static AlreadyInitialized = class extends ILNError { constructor(msg = "Already initialized") { super(msg, 16); } };
+ static AlreadyAppealed = class extends ILNError { constructor(msg = "Already appealed") { super(msg, 17); } };
+ static AppealWindowClosed = class extends ILNError { constructor(msg = "Appeal window closed") { super(msg, 18); } };
+ static NotDefaulted = class extends ILNError { constructor(msg = "Not defaulted") { super(msg, 19); } };
+ static AlreadyInQueue = class extends ILNError { constructor(msg = "Already in queue") { super(msg, 20); } };
+ static NotApprovedFunder = class extends ILNError { constructor(msg = "Not approved funder") { super(msg, 21); } };
+ static InvoiceAppealed = class extends ILNError { constructor(msg = "Invoice appealed") { super(msg, 22); } };
+ static AlreadyDisputed = class extends ILNError { constructor(msg = "Already disputed") { super(msg, 23); } };
+ static NotDisputed = class extends ILNError { constructor(msg = "Not disputed") { super(msg, 24); } };
+ static InvoiceDisputed = class extends ILNError { constructor(msg = "Invoice disputed") { super(msg, 25); } };
+ static ContractPaused = class extends ILNError { constructor(msg = "Contract paused") { super(msg, 26); } };
+ static DueDateTooSoon = class extends ILNError { constructor(msg = "Due date too soon") { super(msg, 27); } };
+ static DueDateTooFar = class extends ILNError { constructor(msg = "Due date too far") { super(msg, 28); } };
+ static SelfInvoice = class extends ILNError { constructor(msg = "Self invoice") { super(msg, 29); } };
+ static OverpaymentRejected = class extends ILNError { constructor(msg = "Overpayment rejected") { super(msg, 30); } };
+ static PayerReputationTooLow = class extends ILNError { constructor(msg = "Payer reputation too low") { super(msg, 31); } };
+ static ArithmeticOverflow = class extends ILNError { constructor(msg = "Arithmetic overflow") { super(msg, 32); } };
+ static FeeOnTransferToken = class extends ILNError { constructor(msg = "Fee on transfer token") { super(msg, 33); } };
+ static PayerUnverified = class extends ILNError { constructor(msg = "Payer unverified") { super(msg, 34); } };
+ static OracleDataStale = class extends ILNError { constructor(msg = "Oracle data stale") { super(msg, 35); } };
+ static AmountTooSmall = class extends ILNError { constructor(msg = "Amount too small") { super(msg, 36); } };
+ static InvoiceNotCancellable = class extends ILNError { constructor(msg = "Invoice not cancellable") { super(msg, 37); } };
+ static InvalidAddress = class extends ILNError { constructor(msg = "Invalid address") { super(msg, 38); } };
+ static InvalidTransfer = class extends ILNError { constructor(msg = "Invalid transfer") { super(msg, 39); } };
+ static InsufficientAmount = class extends ILNError { constructor(msg = "Insufficient amount") { super(msg, 999); } };
+
+ static fromError(error: any): Error {
+ const errorString = String(error);
+ const match = errorString.match(/Error\(Contract, (\d+)\)/);
+ Iif (match) {
+ const code = parseInt(match[1], 10);
+ switch (code) {
+ case 1: return new ILNError.InvoiceNotFound();
+ case 2: return new ILNError.AlreadyFunded();
+ case 3: return new ILNError.AlreadyPaid();
+ case 4: return new ILNError.NotFunded();
+ case 5: return new ILNError.Unauthorized();
+ case 6: return new ILNError.InvalidAmount();
+ case 7: return new ILNError.InvalidDiscountRate();
+ case 8: return new ILNError.InvalidDueDate();
+ case 9: return new ILNError.InvoiceDefaulted();
+ case 10: return new ILNError.NothingToClaim();
+ case 11: return new ILNError.NotYetDefaulted();
+ case 12: return new ILNError.OverfundingRejected();
+ case 13: return new ILNError.InvoiceExpired();
+ case 14: return new ILNError.BatchTooLarge();
+ case 15: return new ILNError.AlreadyCancelled();
+ case 16: return new ILNError.AlreadyInitialized();
+ case 17: return new ILNError.AlreadyAppealed();
+ case 18: return new ILNError.AppealWindowClosed();
+ case 19: return new ILNError.NotDefaulted();
+ case 20: return new ILNError.AlreadyInQueue();
+ case 21: return new ILNError.NotApprovedFunder();
+ case 22: return new ILNError.InvoiceAppealed();
+ case 23: return new ILNError.AlreadyDisputed();
+ case 24: return new ILNError.NotDisputed();
+ case 25: return new ILNError.InvoiceDisputed();
+ case 26: return new ILNError.ContractPaused();
+ case 27: return new ILNError.DueDateTooSoon();
+ case 28: return new ILNError.DueDateTooFar();
+ case 29: return new ILNError.SelfInvoice();
+ case 30: return new ILNError.OverpaymentRejected();
+ case 31: return new ILNError.PayerReputationTooLow();
+ case 32: return new ILNError.ArithmeticOverflow();
+ case 33: return new ILNError.FeeOnTransferToken();
+ case 34: return new ILNError.PayerUnverified();
+ case 35: return new ILNError.OracleDataStale();
+ case 36: return new ILNError.AmountTooSmall();
+ case 37: return new ILNError.InvoiceNotCancellable();
+ }
+ }
+ return new Error(errorString);
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| subscribe.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| types.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Real-time ILN contract event subscription backed by Horizon's SSE
+ * `/effects` + `/contract-events` streaming endpoint.
+ *
+ * Features
+ * --------
+ * - Typed discriminated-union events (ILNEvent)
+ * - Client-side filtering by event type, invoiceId, and address
+ * - Transparent reconnection with exponential back-off on stream errors
+ * - Clean `Unsubscribe` tear-down function returned to the caller
+ */
+import { Server as HorizonServer } from "@stellar/stellar-sdk/lib/horizon/index.js";
+import type { EventFilter, ILNEvent, Unsubscribe } from "./types.js";
+interface HorizonContractEvent {
+ type: string;
+ /** Array of base-64 XDR ScVal strings representing the topics. */
+ topic: string[];
+ /** Base-64 XDR ScVal string for the event body / value. */
+ value: string;
+ contractId?: string;
+ ledger?: number;
+ ledgerClosedAt?: string;
+ txHash?: string;
+ id?: string;
+}
+/**
+ * Parse a raw Horizon contract-event record into a typed ILNEvent.
+ *
+ * Returns `null` when the event cannot be decoded or is not a known ILN type.
+ */
+export declare function parseContractEvent(raw: HorizonContractEvent): ILNEvent | null;
+/**
+ * Returns true when the parsed event satisfies the caller's EventFilter.
+ */
+export declare function matchesFilter(event: ILNEvent, filter: EventFilter): boolean;
+/**
+ * Subscribe to real-time ILN contract events via Horizon's SSE stream.
+ *
+ * Handles stream disconnection with exponential back-off (500 ms → 30 s).
+ * The returned `Unsubscribe` function closes the stream and cancels any
+ * pending reconnection timer.
+ *
+ * @param horizon - Horizon server instance (use `new Server(horizonUrl)`)
+ * @param contractId - Deployed invoice-liquidity contract address
+ * @param filter - Optional criteria; empty object matches all events
+ * @param handler - Called once per matching decoded event
+ * @param onError - Optional error callback for logging / monitoring
+ * @returns Unsubscribe - Call to stop the stream
+ *
+ * @example
+ * ```ts
+ * const unsub = subscribe(horizon, CONTRACT_ID, { types: ["funded", "paid"] },
+ * (event) => console.log(event));
+ * // later…
+ * unsub();
+ * ```
+ */
+export declare function subscribe(horizon: HorizonServer, contractId: string, filter: EventFilter, handler: (event: ILNEvent) => void, onError?: (err: unknown) => void): Unsubscribe;
+export {};
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Typed event union for the Invoice Liquidity Network contract.
+ *
+ * Every event emitted on-chain has a `type` discriminant that matches the
+ * Soroban contract-event topic string, plus the decoded data fields.
+ */
+export type ILNEventType = "submitted" | "funded" | "paid" | "partially_paid" | "defaulted" | "appealed" | "appeal_resolved" | "disputed" | "dispute_resolved" | "token_added" | "token_removed" | "parameter_updated" | "transferred" | "cancelled" | "paused" | "unpaused" | "upgraded" | "admin_changed" | "fund_requested" | "fund_queue_resolved";
+export interface InvoiceSubmittedEvent {
+ type: "submitted";
+ invoiceId: bigint;
+ freelancer: string;
+ payer: string;
+ token: string;
+ amount: bigint;
+ dueDate: bigint;
+ discountRate: number;
+ status: string;
+ timestamp: bigint;
+}
+export interface InvoiceFundedEvent {
+ type: "funded";
+ invoiceId: bigint;
+ funder: string;
+ freelancer: string;
+ payer: string;
+ token: string;
+ fundAmount: bigint;
+ amountFunded: bigint;
+ invoiceAmount: bigint;
+ dueDate: bigint;
+ discountRate: number;
+ fundedAt: bigint | null;
+ status: string;
+ lp: string;
+ effectiveYieldBps: number;
+ timestamp: bigint;
+}
+export interface InvoicePaidEvent {
+ type: "paid";
+ invoiceId: bigint;
+ payer: string;
+ lp: string;
+ freelancer: string;
+ token: string;
+ amountPaid: bigint;
+ lpEarned: bigint;
+ lpPayout: bigint;
+ settlementTimestamp: bigint;
+ paidOnTime: boolean;
+ status: string;
+}
+export interface InvoicePartiallyPaidEvent {
+ type: "partially_paid";
+ invoiceId: bigint;
+ payer: string;
+ amountPaidNow: bigint;
+ totalAmountPaid: bigint;
+ remainingAmount: bigint;
+}
+export interface InvoiceDefaultedEvent {
+ type: "defaulted";
+ invoiceId: bigint;
+ funder: string;
+ freelancer: string;
+ payer: string;
+ token: string;
+ amount: bigint;
+ dueDate: bigint;
+ defaultedAt: bigint;
+ discountAmount: bigint;
+ status: string;
+}
+export interface DefaultAppealedEvent {
+ type: "appealed";
+ invoiceId: bigint;
+ payer: string;
+ evidenceHash: string;
+ appealedAt: bigint;
+}
+export interface AppealResolvedEvent {
+ type: "appeal_resolved";
+ invoiceId: bigint;
+ payer: string;
+ upheld: boolean;
+ resolvedAt: bigint;
+}
+export interface InvoiceDisputedEvent {
+ type: "disputed";
+ invoiceId: bigint;
+ payer: string;
+ reasonHash: string;
+ disputedAt: bigint;
+}
+export interface DisputeResolvedEvent {
+ type: "dispute_resolved";
+ invoiceId: bigint;
+ resolutionHash: string;
+ resolution: number;
+ resolvedAt: bigint;
+}
+export interface TokenAddedEvent {
+ type: "token_added";
+ token: string;
+ decimals: number;
+}
+export interface TokenRemovedEvent {
+ type: "token_removed";
+ token: string;
+}
+export interface ParameterUpdatedEvent {
+ type: "parameter_updated";
+ paramName: string;
+ oldValue: bigint;
+ newValue: bigint;
+ updatedBy: string;
+}
+export interface InvoiceTransferredEvent {
+ type: "transferred";
+ invoiceId: bigint;
+ oldFreelancer: string;
+ newFreelancer: string;
+ status: string;
+}
+export interface InvoiceCancelledEvent {
+ type: "cancelled";
+ invoiceId: bigint;
+ freelancer: string;
+ status: string;
+}
+export interface ContractPausedEvent {
+ type: "paused";
+ timestamp: bigint;
+}
+export interface ContractUnpausedEvent {
+ type: "unpaused";
+ timestamp: bigint;
+}
+export interface ContractUpgradedEvent {
+ type: "upgraded";
+ admin: string;
+ newWasmHash: string;
+ timestamp: bigint;
+}
+export interface AdminChangedEvent {
+ type: "admin_changed";
+ oldAdmin: string;
+ newAdmin: string;
+ timestamp: bigint;
+}
+export interface FundRequestedEvent {
+ type: "fund_requested";
+ invoiceId: bigint;
+ lp: string;
+ score: number;
+}
+export interface FundQueueResolvedEvent {
+ type: "fund_queue_resolved";
+ invoiceId: bigint;
+ approvedLp: string;
+ score: number;
+}
+export type ILNEvent = InvoiceSubmittedEvent | InvoiceFundedEvent | InvoicePaidEvent | InvoicePartiallyPaidEvent | InvoiceDefaultedEvent | DefaultAppealedEvent | AppealResolvedEvent | InvoiceDisputedEvent | DisputeResolvedEvent | TokenAddedEvent | TokenRemovedEvent | ParameterUpdatedEvent | InvoiceTransferredEvent | InvoiceCancelledEvent | ContractPausedEvent | ContractUnpausedEvent | ContractUpgradedEvent | AdminChangedEvent | FundRequestedEvent | FundQueueResolvedEvent;
+/**
+ * Criteria used to narrow the event stream. All fields are optional; an
+ * empty filter matches every ILN contract event.
+ */
+export interface EventFilter {
+ /** Only emit events whose `type` is in this list. */
+ types?: ILNEventType[];
+ /** Only emit events that mention this invoice ID (in a topic). */
+ invoiceId?: bigint;
+ /**
+ * Only emit events that mention this Stellar address in any topic
+ * (freelancer, payer, LP, admin, token …).
+ */
+ address?: string;
+}
+/** Call to stop the subscription and close the underlying stream. */
+export type Unsubscribe = () => void;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * @iln/sdk — Invoice Liquidity Network TypeScript SDK
+ *
+ * Public surface area re-exported from this entry point.
+ */
+export { fundInvoice, computeEffectiveYieldBps } from "./methods/fundInvoice.js";
+export { getReputation } from "./methods/reputation.js";
+export { getContractStats } from "./methods/stats.js";
+export { getAllowance, buildApproveTransaction, isAllowanceSufficient, } from "./utils/allowance.js";
+export { validateGAddress, validateContractId, validateAmount, validateDiscountRate, validateDueDate, } from "./utils/validate.js";
+export { KeypairSigner } from "./signers/KeypairSigner.js";
+export { FreighterSigner, ILNError, ILNErrorCode } from "./signers/FreighterSigner.js";
+export { subscribe, parseContractEvent, matchesFilter } from "./events/subscribe.js";
+export { ILNClient, iln } from "./client.js";
+export type { ISigner } from "./signers/ISigner.js";
+export type { ILNClientConfig } from "./client.js";
+export type { ReputationProfile } from "./methods/reputation.js";
+export type { ContractStats } from "./methods/stats.js";
+export type { FundOptions, FundResult, InvoiceView, AllowanceParams, AllowanceResult, } from "./types.js";
+export type { ILNEvent, ILNEventType, EventFilter, Unsubscribe, } from "./events/types.js";
+export { getInvoice, listInvoicesBySubmitter, listInvoicesByLP } from "./methods/queries.js";
+export { submitInvoice } from "./methods/submitInvoice.js";
+export { transferLPPosition } from "./methods/transferLPPosition.js";
+export { cancelInvoice } from "./methods/cancelInvoice.js";
+export { markPaid } from "./methods/markPaid.js";
+export { createProposal, castVote, executeProposal, getProposal, listProposals, } from "./methods/governance.js";
+export { ProposalAction, ProposalStatus, } from "./types/governance.js";
+export type { Proposal, ProposalFilter, CreateProposalResult, } from "./types/governance.js";
+export { ILNError } from "./errors.js";
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| client.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| client.test.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| client.ts | +
+
+ |
+ 0% | +0/23 | +0% | +0/11 | +0% | +0/11 | +0% | +0/23 | +
| errors.ts | +
+
+ |
+ 0% | +0/126 | +0% | +0/78 | +0% | +0/42 | +0% | +0/86 | +
| index.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| types.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 | + + + + + + + + + + + + + + + + + + + + + + | import { SorobanRpc, Account, Transaction } from "@stellar/stellar-sdk";
+/**
+ * Cancel a pending invoice.
+ * @param server Soroban RPC server
+ * @param contractAddress Contract address
+ * @param invoiceId The ID of the invoice to cancel
+ * @param sourceAccount The account of the freelancer/submitter
+ * @param signTransaction A function to sign the transaction (e.g. Freighter or Keypair)
+ * @param networkPassphrase The network passphrase
+ * @returns Object containing txHash
+ * @throws {ILNError.InvoiceNotCancellable} When the invoice is not in a Pending state
+ * @throws {ILNError.Unauthorized} When caller is not the invoice submitter
+ * @throws {ILNError} When simulation or execution fails
+ * @example
+ * ```ts
+ * const { txHash } = await cancelInvoice(server, contractAddress, 42n, sourceAccount, signTx, Networks.TESTNET);
+ * console.log(txHash);
+ * ```
+ */
+export declare function cancelInvoice(server: SorobanRpc.Server, contractAddress: string, invoiceId: bigint, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<{
+ txHash: string;
+}>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * fundInvoice — LP-facing SDK method for the Invoice Liquidity Network.
+ *
+ * Handles the full two-step allowance + funding flow automatically:
+ * 1. Fetch the invoice to determine the token and amount required.
+ * 2. Query the LP's current token allowance for the contract.
+ * 3. If insufficient, build, sign and submit an `approve` transaction.
+ * 4. Build, sign and submit the `fund_invoice` contract call.
+ * 5. Return `{ txHash, effectiveYieldBps }`.
+ *
+ * Progress is surfaced via optional callbacks on FundOptions so integrators
+ * can update UI without polling.
+ */
+import { SorobanRpc, Keypair } from "@stellar/stellar-sdk";
+import type { FundOptions, FundResult } from "../types.js";
+/**
+ * Compute the annualised effective yield in basis points for an LP position.
+ *
+ * effectiveYieldBps = discountRate × daysToMaturity / 365
+ *
+ * Returns `0` when the due date is already in the past.
+ *
+ * @param discountRateBps - Invoice discount rate in basis points (e.g. 300 = 3%)
+ * @param dueDateUnix - Invoice due date as Unix timestamp (seconds)
+ * @param nowUnix - Current time as Unix timestamp; defaults to Date.now()
+ */
+export declare function computeEffectiveYieldBps(discountRateBps: number, dueDateUnix: number, nowUnix?: number): number;
+/**
+ * Fund an invoice as a liquidity provider.
+ *
+ * Automatically manages the token allowance before calling `fund_invoice`
+ * on-chain. When an `approve` transaction is needed, `onApprovalRequired`
+ * fires first (so the UI can show a prompt), and `onApprovalSent` fires
+ * after the approval is submitted. `onFunded` fires once the fund transaction
+ * is sent.
+ *
+ * @param server - Soroban RPC server connected to the target network
+ * @param contractAddress - Deployed invoice-liquidity contract address
+ * @param lpKeypair - Keypair of the liquidity provider (signs all txs)
+ * @param invoiceId - ID of the invoice to fund
+ * @param options - Optional configuration and progress callbacks:
+ * - `requireOracleVerification` — reject if the contract has no price oracle
+ * - `onApprovalRequired` — fired before the approve tx is built
+ * - `onApprovalSent` — fired after the approve tx is submitted
+ * - `onFunded` — fired after the fund tx is submitted
+ * @param networkPassphrase - Stellar network passphrase (default: TESTNET)
+ *
+ * @returns `{ txHash, effectiveYieldBps }` on success
+ *
+ * @throws When the invoice is not fundable (wrong status, not found, etc.)
+ * @throws When the approve or fund transaction is rejected by the network
+ * @throws When oracle verification is required but fails
+ *
+ * @example
+ * ```ts
+ * const result = await fundInvoice(server, CONTRACT_ID, lpKeypair, 42n, {
+ * onApprovalRequired: ({ requiredAmount, currentAllowance }) =>
+ * console.log(`Need to approve ${requiredAmount}, have ${currentAllowance}`),
+ * onApprovalSent: ({ approveTxHash }) =>
+ * console.log(`Approval submitted: ${approveTxHash}`),
+ * onFunded: ({ effectiveYieldBps, invoiceId }) =>
+ * console.log(`Invoice ${invoiceId} funded! Yield: ${effectiveYieldBps} bps`),
+ * });
+ * ```
+ */
+export declare function fundInvoice(server: SorobanRpc.Server, contractAddress: string, lpKeypair: Keypair, invoiceId: bigint, options?: FundOptions, networkPassphrase?: string): Promise<FundResult>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | import { SorobanRpc, Account, Transaction } from "@stellar/stellar-sdk";
+import { ProposalAction, type Proposal, type ProposalFilter, type CreateProposalResult } from "../types/governance.js";
+/**
+ * Create a new governance proposal.
+ *
+ * @param server Soroban RPC server
+ * @param contractAddress Governance contract address
+ * @param action The parameter-changing action to propose
+ * @param proposedValue The proposed new value for the action's parameter
+ * @param descriptionHash Hex-encoded 32-byte hash of the off-chain description
+ * @param sourceAccount The proposer's account
+ * @param signTransaction A function to sign the transaction
+ * @param networkPassphrase The network passphrase
+ * @returns The new proposalId and txHash
+ * @throws {ILNError} When simulation or execution fails
+ */
+export declare function createProposal(server: SorobanRpc.Server, contractAddress: string, action: ProposalAction, proposedValue: bigint, descriptionHash: string, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<CreateProposalResult>;
+/**
+ * Cast a vote on an active proposal.
+ *
+ * @param support `true` to vote for, `false` to vote against.
+ */
+export declare function castVote(server: SorobanRpc.Server, contractAddress: string, proposalId: bigint, support: boolean, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<{
+ txHash: string;
+}>;
+/**
+ * Execute a proposal that has passed its vote.
+ */
+export declare function executeProposal(server: SorobanRpc.Server, contractAddress: string, proposalId: bigint, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<{
+ txHash: string;
+}>;
+/**
+ * Fetch a single proposal by ID (read-only; no signer required).
+ */
+export declare function getProposal(server: SorobanRpc.Server, contractAddress: string, id: bigint, sourceAccount: Account, networkPassphrase: string): Promise<Proposal>;
+/**
+ * List proposals, optionally filtered by status and/or proposer (read-only).
+ */
+export declare function listProposals(server: SorobanRpc.Server, contractAddress: string, sourceAccount: Account, networkPassphrase: string, filter?: ProposalFilter): Promise<Proposal[]>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| cancelInvoice.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| fundInvoice.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| governance.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| markPaid.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| queries.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| queries.ts | +
+
+ |
+ 0% | +0/40 | +0% | +0/37 | +0% | +0/5 | +0% | +0/40 | +
| reputation.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| reputation.ts | +
+
+ |
+ 0% | +0/15 | +0% | +0/14 | +0% | +0/2 | +0% | +0/15 | +
| stats.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| stats.ts | +
+
+ |
+ 0% | +0/16 | +0% | +0/18 | +0% | +0/1 | +0% | +0/16 | +
| submitInvoice.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| transferLPPosition.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 | + + + + + + + + + + + + + + + + + + + + + | import { SorobanRpc, Account, Transaction } from "@stellar/stellar-sdk";
+import type { MarkPaidResult } from "../types/params.js";
+/**
+ * Mark an invoice as paid (supports partial payments).
+ * @param server Soroban RPC server
+ * @param contractAddress Contract address
+ * @param invoiceId The invoice ID
+ * @param amount Optional amount to pay. If omitted, pays the full remaining balance.
+ * @param sourceAccount The account of the payer
+ * @param signTransaction A function to sign the transaction
+ * @param networkPassphrase The network passphrase
+ * @returns Object with txHash, remainingBalance and fullySettled flag
+ * @throws {ILNError.InsufficientAmount} If payment amount is <= 0 or exceeds outstanding balance
+ * @throws {ILNError} When simulation or execution fails
+ * @example
+ * ```ts
+ * const result = await markPaid(server, contractAddress, 42n, 100n, sourceAccount, signTx, Networks.TESTNET);
+ * console.log(`Remaining balance: ${result.remainingBalance}`);
+ * ```
+ */
+export declare function markPaid(server: SorobanRpc.Server, contractAddress: string, invoiceId: bigint, amount: bigint | undefined, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<MarkPaidResult>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | import { SorobanRpc, Account } from "@stellar/stellar-sdk";
+import type { Invoice } from "../types/invoice.js";
+/**
+ * Fetch a single invoice by its ID.
+ * @param server Soroban RPC server instance
+ * @param contractAddress The contract's address
+ * @param invoiceId The invoice ID
+ * @param sourceAccount Account used for simulation (does not consume sequence or fees)
+ * @param networkPassphrase The network passphrase
+ * @returns The invoice data including computed yield
+ * @throws {ILNError.InvoiceNotFound} If the invoice does not exist
+ * @throws {ILNError} On other simulation errors
+ * @example
+ * ```ts
+ * const invoice = await getInvoice(server, contractAddress, 42n, sourceAccount, Networks.TESTNET);
+ * console.log(`Invoice status: ${invoice.status}`);
+ * ```
+ */
+export declare function getInvoice(server: SorobanRpc.Server, contractAddress: string, invoiceId: bigint, sourceAccount: Account, networkPassphrase: string): Promise<Invoice>;
+/**
+ * List invoices submitted by a specific freelancer address.
+ * @param server Soroban RPC server instance
+ * @param contractAddress The contract's address
+ * @param submitter The freelancer's address
+ * @param sourceAccount Account used for simulation
+ * @param networkPassphrase The network passphrase
+ * @param page The page number (0-indexed)
+ * @param pageSize The number of items per page
+ * @returns Array of invoices
+ * @throws {ILNError} On simulation errors
+ * @example
+ * ```ts
+ * const invoices = await listInvoicesBySubmitter(server, contractAddress, "G...", sourceAccount, Networks.TESTNET, 0, 10);
+ * ```
+ */
+export declare function listInvoicesBySubmitter(server: SorobanRpc.Server, contractAddress: string, submitter: string, sourceAccount: Account, networkPassphrase: string, page?: number, pageSize?: number): Promise<Invoice[]>;
+/**
+ * List invoices funded by a specific LP address.
+ * @param server Soroban RPC server instance
+ * @param contractAddress The contract's address
+ * @param lp The liquidity provider's address
+ * @param sourceAccount Account used for simulation
+ * @param networkPassphrase The network passphrase
+ * @param page The page number (0-indexed)
+ * @param pageSize The number of items per page
+ * @returns Array of invoices
+ * @throws {ILNError} On simulation errors
+ * @example
+ * ```ts
+ * const invoices = await listInvoicesByLP(server, contractAddress, "G...", sourceAccount, Networks.TESTNET, 0, 10);
+ * ```
+ */
+export declare function listInvoicesByLP(server: SorobanRpc.Server, contractAddress: string, lp: string, sourceAccount: Account, networkPassphrase: string, page?: number, pageSize?: number): Promise<Invoice[]>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | import {
+ Contract,
+ SorobanRpc,
+ TransactionBuilder,
+ BASE_FEE,
+ scValToNative,
+ nativeToScVal,
+ Account,
+} from "@stellar/stellar-sdk";
+import type { Invoice } from "../types/invoice.js";
+import { ILNError } from "../errors.js";
+import { computeEffectiveYieldBps } from "./fundInvoice.js";
+
+/**
+ * Fetch a single invoice by its ID.
+ * @param server Soroban RPC server instance
+ * @param contractAddress The contract's address
+ * @param invoiceId The invoice ID
+ * @param sourceAccount Account used for simulation (does not consume sequence or fees)
+ * @param networkPassphrase The network passphrase
+ * @returns The invoice data including computed yield
+ * @throws {ILNError.InvoiceNotFound} If the invoice does not exist
+ * @throws {ILNError} On other simulation errors
+ * @example
+ * ```ts
+ * const invoice = await getInvoice(server, contractAddress, 42n, sourceAccount, Networks.TESTNET);
+ * console.log(`Invoice status: ${invoice.status}`);
+ * ```
+ */
+export async function getInvoice(
+ server: SorobanRpc.Server,
+ contractAddress: string,
+ invoiceId: bigint,
+ sourceAccount: Account,
+ networkPassphrase: string
+): Promise<Invoice> {
+ const contract = new Contract(contractAddress);
+ const op = contract.call(
+ "get_invoice",
+ nativeToScVal(invoiceId, { type: "u64" })
+ );
+
+ const tx = new TransactionBuilder(sourceAccount, {
+ fee: BASE_FEE,
+ networkPassphrase,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const sim = await server.simulateTransaction(tx);
+
+ Iif (SorobanRpc.Api.isSimulationError(sim)) {
+ Iif (String(sim.error).includes("NotFound") || String(sim.error).includes("Error(Contract, 1)")) {
+ throw new ILNError.InvoiceNotFound(`Invoice ${invoiceId} not found`);
+ }
+ throw ILNError.fromError(sim.error);
+ }
+ Iif (!sim.result?.retval) {
+ throw new ILNError.InvoiceNotFound(`Invoice ${invoiceId} not found`);
+ }
+
+ const raw = scValToNative(sim.result.retval) as Record<string, unknown>;
+ const dueDate = Number(raw["due_date"]);
+ const discountRate = Number(raw["discount_rate"]);
+
+ return {
+ id: BigInt(String(raw["id"])),
+ freelancer: String(raw["freelancer"]),
+ payer: String(raw["payer"]),
+ token: String(raw["token"]),
+ amount: BigInt(String(raw["amount"])),
+ dueDate,
+ discountRate,
+ status: (raw["status"] as any)?.tag || String(raw["status"]) as any, // handle scval enum
+ funder: raw["funder"] ? String(raw["funder"]) : undefined,
+ fundedAt: raw["funded_at"] ? Number(raw["funded_at"]) : undefined,
+ amountFunded: BigInt(String(raw["amount_funded"])),
+ amountPaid: BigInt(String(raw["amount_paid"])),
+ referralCode: raw["referral_code"] ? Buffer.from(raw["referral_code"] as any).toString('hex') : undefined,
+ submitterReputation: Number(raw["submitter_reputation"]),
+ effectiveYieldBps: computeEffectiveYieldBps(discountRate, dueDate),
+ };
+}
+
+/**
+ * List invoices submitted by a specific freelancer address.
+ * @param server Soroban RPC server instance
+ * @param contractAddress The contract's address
+ * @param submitter The freelancer's address
+ * @param sourceAccount Account used for simulation
+ * @param networkPassphrase The network passphrase
+ * @param page The page number (0-indexed)
+ * @param pageSize The number of items per page
+ * @returns Array of invoices
+ * @throws {ILNError} On simulation errors
+ * @example
+ * ```ts
+ * const invoices = await listInvoicesBySubmitter(server, contractAddress, "G...", sourceAccount, Networks.TESTNET, 0, 10);
+ * ```
+ */
+export async function listInvoicesBySubmitter(
+ server: SorobanRpc.Server,
+ contractAddress: string,
+ submitter: string,
+ sourceAccount: Account,
+ networkPassphrase: string,
+ page: number = 0,
+ pageSize: number = 50
+): Promise<Invoice[]> {
+ const contract = new Contract(contractAddress);
+ const op = contract.call(
+ "list_invoices_by_submitter",
+ nativeToScVal(submitter, { type: "address" }),
+ nativeToScVal(page, { type: "u32" }),
+ nativeToScVal(pageSize, { type: "u32" })
+ );
+
+ const tx = new TransactionBuilder(sourceAccount, {
+ fee: BASE_FEE,
+ networkPassphrase,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const sim = await server.simulateTransaction(tx);
+
+ Iif (SorobanRpc.Api.isSimulationError(sim)) {
+ throw ILNError.fromError(sim.error);
+ }
+ Iif (!sim.result?.retval) {
+ return [];
+ }
+
+ const rawArr = scValToNative(sim.result.retval) as Record<string, unknown>[];
+ return rawArr.map(raw => {
+ const dueDate = Number(raw["due_date"]);
+ const discountRate = Number(raw["discount_rate"]);
+ return {
+ id: BigInt(String(raw["id"])),
+ freelancer: String(raw["freelancer"]),
+ payer: String(raw["payer"]),
+ token: String(raw["token"]),
+ amount: BigInt(String(raw["amount"])),
+ dueDate,
+ discountRate,
+ status: (raw["status"] as any)?.tag || String(raw["status"]) as any,
+ funder: raw["funder"] ? String(raw["funder"]) : undefined,
+ fundedAt: raw["funded_at"] ? Number(raw["funded_at"]) : undefined,
+ amountFunded: BigInt(String(raw["amount_funded"])),
+ amountPaid: BigInt(String(raw["amount_paid"])),
+ referralCode: raw["referral_code"] ? Buffer.from(raw["referral_code"] as any).toString('hex') : undefined,
+ submitterReputation: Number(raw["submitter_reputation"]),
+ effectiveYieldBps: computeEffectiveYieldBps(discountRate, dueDate),
+ };
+ });
+}
+
+/**
+ * List invoices funded by a specific LP address.
+ * @param server Soroban RPC server instance
+ * @param contractAddress The contract's address
+ * @param lp The liquidity provider's address
+ * @param sourceAccount Account used for simulation
+ * @param networkPassphrase The network passphrase
+ * @param page The page number (0-indexed)
+ * @param pageSize The number of items per page
+ * @returns Array of invoices
+ * @throws {ILNError} On simulation errors
+ * @example
+ * ```ts
+ * const invoices = await listInvoicesByLP(server, contractAddress, "G...", sourceAccount, Networks.TESTNET, 0, 10);
+ * ```
+ */
+export async function listInvoicesByLP(
+ server: SorobanRpc.Server,
+ contractAddress: string,
+ lp: string,
+ sourceAccount: Account,
+ networkPassphrase: string,
+ page: number = 0,
+ pageSize: number = 50
+): Promise<Invoice[]> {
+ const contract = new Contract(contractAddress);
+ const op = contract.call(
+ "list_invoices_by_lp",
+ nativeToScVal(lp, { type: "address" }),
+ nativeToScVal(page, { type: "u32" }),
+ nativeToScVal(pageSize, { type: "u32" })
+ );
+
+ const tx = new TransactionBuilder(sourceAccount, {
+ fee: BASE_FEE,
+ networkPassphrase,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const sim = await server.simulateTransaction(tx);
+
+ Iif (SorobanRpc.Api.isSimulationError(sim)) {
+ throw ILNError.fromError(sim.error);
+ }
+ Iif (!sim.result?.retval) {
+ return [];
+ }
+
+ const rawArr = scValToNative(sim.result.retval) as Record<string, unknown>[];
+ return rawArr.map(raw => {
+ const dueDate = Number(raw["due_date"]);
+ const discountRate = Number(raw["discount_rate"]);
+ return {
+ id: BigInt(String(raw["id"])),
+ freelancer: String(raw["freelancer"]),
+ payer: String(raw["payer"]),
+ token: String(raw["token"]),
+ amount: BigInt(String(raw["amount"])),
+ dueDate,
+ discountRate,
+ status: (raw["status"] as any)?.tag || String(raw["status"]) as any,
+ funder: raw["funder"] ? String(raw["funder"]) : undefined,
+ fundedAt: raw["funded_at"] ? Number(raw["funded_at"]) : undefined,
+ amountFunded: BigInt(String(raw["amount_funded"])),
+ amountPaid: BigInt(String(raw["amount_paid"])),
+ referralCode: raw["referral_code"] ? Buffer.from(raw["referral_code"] as any).toString('hex') : undefined,
+ submitterReputation: Number(raw["submitter_reputation"]),
+ effectiveYieldBps: computeEffectiveYieldBps(discountRate, dueDate),
+ };
+ });
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * getReputation — read an address's detailed reputation profile from
+ * the on-chain invoice-liquidity contract.
+ *
+ * Wraps the `get_reputation(address)` view function. Unknown addresses
+ * return a zeroed profile (matching the contract's lazy-init behaviour).
+ */
+import { SorobanRpc } from "@stellar/stellar-sdk";
+/**
+ * An address's on-chain reputation profile.
+ *
+ * Mirrors `ReputationProfile` in the Rust contract (`invoice.rs`).
+ * Unknown addresses return every field as zero.
+ */
+export interface ReputationProfile {
+ /** Stellar G… address that was queried. */
+ address: string;
+ /** Current reputation score (0–100). */
+ score: number;
+ /** Total invoices submitted by this address. */
+ invoicesSubmitted: number;
+ /** Total invoices paid by this address (as payer). */
+ invoicesPaid: number;
+ /** Total invoices defaulted by this address. */
+ invoicesDefaulted: number;
+}
+/**
+ * Query the reputation profile for a Stellar address.
+ *
+ * Performs a read-only Soroban simulation — no on-chain mutation, no
+ * transaction fees, and no signer required.
+ *
+ * @param server - Soroban RPC server for the target network
+ * @param contractId - Deployed invoice-liquidity contract address
+ * @param address - Stellar G… address to look up
+ * @param networkPassphrase - Stellar network passphrase (default: TESTNET)
+ * @returns ReputationProfile (zeroed for unknown / never-active addresses)
+ *
+ * @throws When `address` is not a valid Stellar G-address
+ * @throws When the Soroban simulation fails (RPC unreachable, contract not found)
+ *
+ * @example
+ * ```ts
+ * const rep = await getReputation(server, CONTRACT_ID, "GAA...");
+ * console.log(`Score: ${rep.score}, Submitted: ${rep.invoicesSubmitted}`);
+ * ```
+ */
+export declare function getReputation(server: SorobanRpc.Server, contractId: string, address: string, networkPassphrase?: string): Promise<ReputationProfile>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * getReputation — read an address's detailed reputation profile from
+ * the on-chain invoice-liquidity contract.
+ *
+ * Wraps the `get_reputation(address)` view function. Unknown addresses
+ * return a zeroed profile (matching the contract's lazy-init behaviour).
+ */
+
+import {
+ Contract,
+ SorobanRpc,
+ TransactionBuilder,
+ Account,
+ BASE_FEE,
+ scValToNative,
+ Address,
+ Networks,
+} from "@stellar/stellar-sdk";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * An address's on-chain reputation profile.
+ *
+ * Mirrors `ReputationProfile` in the Rust contract (`invoice.rs`).
+ * Unknown addresses return every field as zero.
+ */
+export interface ReputationProfile {
+ /** Stellar G… address that was queried. */
+ address: string;
+ /** Current reputation score (0–100). */
+ score: number;
+ /** Total invoices submitted by this address. */
+ invoicesSubmitted: number;
+ /** Total invoices paid by this address (as payer). */
+ invoicesPaid: number;
+ /** Total invoices defaulted by this address. */
+ invoicesDefaulted: number;
+}
+
+// ---------------------------------------------------------------------------
+// G-address validation
+// ---------------------------------------------------------------------------
+
+const G_ADDRESS_RE = /^G[A-Z2-7]{55}$/;
+
+function isValidGAddress(address: string): boolean {
+ return G_ADDRESS_RE.test(address);
+}
+
+// ---------------------------------------------------------------------------
+// getReputation
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the reputation profile for a Stellar address.
+ *
+ * Performs a read-only Soroban simulation — no on-chain mutation, no
+ * transaction fees, and no signer required.
+ *
+ * @param server - Soroban RPC server for the target network
+ * @param contractId - Deployed invoice-liquidity contract address
+ * @param address - Stellar G… address to look up
+ * @param networkPassphrase - Stellar network passphrase (default: TESTNET)
+ * @returns ReputationProfile (zeroed for unknown / never-active addresses)
+ *
+ * @throws When `address` is not a valid Stellar G-address
+ * @throws When the Soroban simulation fails (RPC unreachable, contract not found)
+ *
+ * @example
+ * ```ts
+ * const rep = await getReputation(server, CONTRACT_ID, "GAA...");
+ * console.log(`Score: ${rep.score}, Submitted: ${rep.invoicesSubmitted}`);
+ * ```
+ */
+export async function getReputation(
+ server: SorobanRpc.Server,
+ contractId: string,
+ address: string,
+ networkPassphrase: string = Networks.TESTNET
+): Promise<ReputationProfile> {
+ Iif (!isValidGAddress(address)) {
+ throw new Error(
+ `Invalid Stellar address: "${address}". Must be a G… public key.`
+ );
+ }
+
+ const contract = new Contract(contractId);
+ const op = contract.call(
+ "get_reputation",
+ new Address(address).toScVal()
+ );
+
+ const sourceAccount = new Account(
+ "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
+ "0"
+ );
+
+ const simTx = new TransactionBuilder(sourceAccount, {
+ fee: BASE_FEE,
+ networkPassphrase,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const sim = await server.simulateTransaction(simTx);
+
+ Iif (SorobanRpc.Api.isSimulationError(sim)) {
+ throw new Error(`get_reputation simulation failed: ${sim.error}`);
+ }
+
+ // The contract returns a zeroed ReputationProfile for unknown addresses
+ Iif (!sim.result?.retval) {
+ return {
+ address,
+ score: 0,
+ invoicesSubmitted: 0,
+ invoicesPaid: 0,
+ invoicesDefaulted: 0,
+ };
+ }
+
+ const raw = scValToNative(sim.result.retval) as Record<string, unknown>;
+
+ return {
+ address: String(raw["address"] ?? address),
+ score: Number(raw["score"] ?? 0),
+ invoicesSubmitted: Number(raw["invoices_submitted"] ?? 0),
+ invoicesPaid: Number(raw["invoices_paid"] ?? 0),
+ invoicesDefaulted: Number(raw["invoices_defaulted"] ?? 0),
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * getContractStats — fetch protocol-wide statistics from the contract.
+ *
+ * Reads the single `get_contract_stats()` view call. No signer or
+ * transaction fees required (read-only simulation).
+ */
+import { SorobanRpc } from "@stellar/stellar-sdk";
+/**
+ * Protocol-wide statistics returned by `get_contract_stats()`.
+ *
+ * Mirrors `ContractStats` in the Rust contract.
+ */
+export interface ContractStats {
+ /** Total number of invoices ever created. */
+ totalInvoices: bigint;
+ /** Cumulative number of fully-funded invoices. */
+ totalFunded: bigint;
+ /** Cumulative number of paid invoices. */
+ totalPaid: bigint;
+ /** Total USDC volume (in stroops, 6 decimals). */
+ totalVolumeUsdc: bigint;
+ /** Total EURC volume (in stroops, 6 decimals). */
+ totalVolumeEurc: bigint;
+ /** Total XLM volume (in stroops, 7 decimals). */
+ totalVolumeXlm: bigint;
+ /** Per-token volume map: token address → volume. */
+ volumeByToken: Record<string, bigint>;
+ /** Total volume normalized to USD (depends on oracle price feed). */
+ totalVolumeUsdNormalized: bigint;
+}
+/**
+ * Query protocol-wide statistics from the contract.
+ *
+ * Read-only — no signer, no fees, no on-chain mutation.
+ *
+ * @param server - Soroban RPC server for the target network
+ * @param contractId - Deployed invoice-liquidity contract address
+ * @param networkPassphrase - Stellar network passphrase (default: TESTNET)
+ * @returns ContractStats
+ *
+ * @throws When the Soroban simulation fails (RPC unreachable, contract not found)
+ *
+ * @example
+ * ```ts
+ * const stats = await getContractStats(server, CONTRACT_ID);
+ * console.log(`Total invoices: ${stats.totalInvoices}`);
+ * console.log(`USDC volume: ${stats.totalVolumeUsdc}`);
+ * ```
+ */
+export declare function getContractStats(server: SorobanRpc.Server, contractId: string, networkPassphrase?: string): Promise<ContractStats>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * getContractStats — fetch protocol-wide statistics from the contract.
+ *
+ * Reads the single `get_contract_stats()` view call. No signer or
+ * transaction fees required (read-only simulation).
+ */
+
+import {
+ Contract,
+ SorobanRpc,
+ TransactionBuilder,
+ Account,
+ BASE_FEE,
+ scValToNative,
+ Networks,
+} from "@stellar/stellar-sdk";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Protocol-wide statistics returned by `get_contract_stats()`.
+ *
+ * Mirrors `ContractStats` in the Rust contract.
+ */
+export interface ContractStats {
+ /** Total number of invoices ever created. */
+ totalInvoices: bigint;
+ /** Cumulative number of fully-funded invoices. */
+ totalFunded: bigint;
+ /** Cumulative number of paid invoices. */
+ totalPaid: bigint;
+ /** Total USDC volume (in stroops, 6 decimals). */
+ totalVolumeUsdc: bigint;
+ /** Total EURC volume (in stroops, 6 decimals). */
+ totalVolumeEurc: bigint;
+ /** Total XLM volume (in stroops, 7 decimals). */
+ totalVolumeXlm: bigint;
+ /** Per-token volume map: token address → volume. */
+ volumeByToken: Record<string, bigint>;
+ /** Total volume normalized to USD (depends on oracle price feed). */
+ totalVolumeUsdNormalized: bigint;
+}
+
+// ---------------------------------------------------------------------------
+// getContractStats
+// ---------------------------------------------------------------------------
+
+/**
+ * Query protocol-wide statistics from the contract.
+ *
+ * Read-only — no signer, no fees, no on-chain mutation.
+ *
+ * @param server - Soroban RPC server for the target network
+ * @param contractId - Deployed invoice-liquidity contract address
+ * @param networkPassphrase - Stellar network passphrase (default: TESTNET)
+ * @returns ContractStats
+ *
+ * @throws When the Soroban simulation fails (RPC unreachable, contract not found)
+ *
+ * @example
+ * ```ts
+ * const stats = await getContractStats(server, CONTRACT_ID);
+ * console.log(`Total invoices: ${stats.totalInvoices}`);
+ * console.log(`USDC volume: ${stats.totalVolumeUsdc}`);
+ * ```
+ */
+export async function getContractStats(
+ server: SorobanRpc.Server,
+ contractId: string,
+ networkPassphrase: string = Networks.TESTNET
+): Promise<ContractStats> {
+ const contract = new Contract(contractId);
+ const op = contract.call("get_contract_stats");
+
+ const sourceAccount = new Account(
+ "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
+ "0"
+ );
+
+ const simTx = new TransactionBuilder(sourceAccount, {
+ fee: BASE_FEE,
+ networkPassphrase,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const sim = await server.simulateTransaction(simTx);
+
+ Iif (SorobanRpc.Api.isSimulationError(sim)) {
+ throw new Error(`get_contract_stats simulation failed: ${sim.error}`);
+ }
+
+ Iif (!sim.result?.retval) {
+ return {
+ totalInvoices: 0n,
+ totalFunded: 0n,
+ totalPaid: 0n,
+ totalVolumeUsdc: 0n,
+ totalVolumeEurc: 0n,
+ totalVolumeXlm: 0n,
+ volumeByToken: {},
+ totalVolumeUsdNormalized: 0n,
+ };
+ }
+
+ const raw = scValToNative(sim.result.retval) as Record<string, unknown>;
+
+ // Parse per-token volumes: the contract returns a Vec<(Address, i128)>
+ const volumeByToken: Record<string, bigint> = {};
+ const rawTokenVolumes = raw["token_volumes"] as Array<[string, string]> | undefined;
+ Iif (Array.isArray(rawTokenVolumes)) {
+ for (const [token, volume] of rawTokenVolumes) {
+ volumeByToken[token] = BigInt(volume);
+ }
+ }
+
+ return {
+ totalInvoices: BigInt(String(raw["total_invoices"] ?? "0")),
+ totalFunded: BigInt(String(raw["total_funded"] ?? "0")),
+ totalPaid: BigInt(String(raw["total_paid"] ?? "0")),
+ totalVolumeUsdc: BigInt(String(raw["total_volume_usdc"] ?? "0")),
+ totalVolumeEurc: BigInt(String(raw["total_volume_eurc"] ?? "0")),
+ totalVolumeXlm: BigInt(String(raw["total_volume_xlm"] ?? "0")),
+ volumeByToken,
+ totalVolumeUsdNormalized: BigInt(
+ String(raw["total_volume_usd_normalized"] ?? "0")
+ ),
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 | + + + + + + + + + + + + + + + + + + + + + + + + | import { SorobanRpc, Account, Transaction } from "@stellar/stellar-sdk";
+import type { SubmitInvoiceParams, SubmitInvoiceResult } from "../types/params.js";
+/**
+ * Submit a new invoice to the contract.
+ * @param server Soroban RPC server
+ * @param contractAddress Contract address
+ * @param params Invoice parameters
+ * @param sourceAccount The account of the freelancer/submitter
+ * @param signTransaction A function to sign the transaction (e.g. Freighter or Keypair)
+ * @param networkPassphrase The network passphrase
+ * @returns Object containing invoiceId and txHash
+ * @throws {ILNError.InvalidAmount} If amount is <= 0
+ * @throws {ILNError.InvalidDiscountRate} If discount rate is not between 1 and 5000 bps
+ * @throws {ILNError.DueDateTooSoon} If due date is < 24h
+ * @throws {ILNError.DueDateTooFar} If due date is > 365 days
+ * @throws {ILNError} If payer address is invalid or transaction fails
+ * @example
+ * ```ts
+ * const { invoiceId, txHash } = await submitInvoice(server, contractAddress, {
+ * payer: "G...", amount: 1000n, dueDate: Date.now() / 1000 + 86400 * 30, discountRate: 300, token: "C..."
+ * }, sourceAccount, signTx, Networks.TESTNET);
+ * ```
+ */
+export declare function submitInvoice(server: SorobanRpc.Server, contractAddress: string, params: SubmitInvoiceParams, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<SubmitInvoiceResult>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 | + + + + + + + + + + + + + + + + + + + + + + + + + + + | import { SorobanRpc, Account, Transaction } from "@stellar/stellar-sdk";
+/**
+ * Transfer a funded LP position to another address.
+ *
+ * Allows a liquidity provider to exit a position they have funded by handing
+ * it to a new LP, without unwinding the underlying invoice. The caller
+ * (`sourceAccount`) must be the current LP of the position.
+ *
+ * @param server Soroban RPC server
+ * @param contractAddress Contract address
+ * @param invoiceId The ID of the funded invoice whose position is transferred
+ * @param newLP The G-address of the LP receiving the position
+ * @param sourceAccount The account of the current LP
+ * @param signTransaction A function to sign the transaction (e.g. Freighter or Keypair)
+ * @param networkPassphrase The network passphrase
+ * @returns Object containing txHash
+ * @throws {ILNError.InvalidAddress} If newLP is not a valid Stellar G-address
+ * @throws {ILNError.InvalidTransfer} If newLP is the same as the current LP
+ * @throws {ILNError} When simulation or execution fails
+ * @example
+ * ```ts
+ * const { txHash } = await transferLPPosition(server, contractAddress, 42n, "G...", sourceAccount, signTx, Networks.TESTNET);
+ * ```
+ */
+export declare function transferLPPosition(server: SorobanRpc.Server, contractAddress: string, invoiceId: bigint, newLP: string, sourceAccount: Account, signTransaction: (tx: Transaction) => Promise<Transaction> | Transaction, networkPassphrase: string): Promise<{
+ txHash: string;
+}>;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * FreighterSigner — ISigner adapter for the Freighter browser extension.
+ *
+ * Intended for browser-based dApps where a Stellar wallet extension is
+ * available. Detects whether Freighter is installed, requests network
+ * access on first use, and delegates transaction signing to the wallet.
+ *
+ * ## Flow
+ *
+ * 1. `constructor` — stores configuration; does NOT touch the wallet.
+ * 2. `publicKey` getter — triggers detection + access request, then caches
+ * the public key for the session.
+ * 3. `signTransaction()` — hands the prepared XDR envelope to Freighter
+ * and returns the signed envelope as a base-64 string.
+ *
+ * ## Error handling
+ *
+ * - `ILNError.WalletNotInstalled` — `window.freighterApi` is undefined
+ * - `ILNError.UserRejected` — the user dismissed the Freighter prompt
+ * - `ILNError.NetworkMismatch` — the wallet network differs from the
+ * configured network (e.g. wallet on mainnet but SDK on testnet)
+ *
+ * ## Network-mismatch detection
+ *
+ * Freighter returns the active network via `getNetwork()` (or
+ * `getNetworkDetails()`). Before signing we compare it against the
+ * configured `networkPassphrase` and throw `NetworkMismatch` when they
+ * differ, avoiding hard-to-debug simulation failures downstream.
+ */
+import { SorobanRpc } from "@stellar/stellar-sdk";
+import type { ISigner } from "./ISigner.js";
+import type { Transaction } from "@stellar/stellar-sdk";
+interface FreighterApi {
+ isConnected(): Promise<boolean>;
+ getPublicKey(): Promise<string>;
+ getNetwork(): Promise<string>;
+ signTransaction(xdr: string, opts?: {
+ network?: string;
+ networkPassphrase?: string;
+ }): Promise<string>;
+}
+declare global {
+ interface Window {
+ freighterApi?: FreighterApi;
+ }
+}
+/** SDK-level error with a machine-readable code. */
+export declare class ILNError extends Error {
+ readonly code: ILNErrorCode;
+ constructor(code: ILNErrorCode, message: string);
+ static WalletNotInstalled(): ILNError;
+ static UserRejected(): ILNError;
+ static NetworkMismatch(expected: string, actual: string): ILNError;
+ static NotConnected(): ILNError;
+}
+/** Error codes for programmatic handling. */
+export declare enum ILNErrorCode {
+ WalletNotInstalled = "WALLET_NOT_INSTALLED",
+ UserRejected = "USER_REJECTED",
+ NetworkMismatch = "NETWORK_MISMATCH",
+ NotConnected = "NOT_CONNECTED",
+ SigningFailed = "SIGNING_FAILED"
+}
+/**
+ * Browser wallet signer backed by the Freighter extension.
+ *
+ * @example
+ * ```ts
+ * // Testnet
+ * const signer = new FreighterSigner({ networkPassphrase: Networks.TESTNET });
+ * console.log(signer.publicKey); // triggers Freighter access prompt
+ *
+ * // Mainnet
+ * const signer = new FreighterSigner({ networkPassphrase: Networks.PUBLIC });
+ *
+ * // Sign a transaction
+ * const signedXdr = await signer.signTransaction(tx, rpcServer);
+ * ```
+ */
+export declare class FreighterSigner implements ISigner {
+ private readonly _networkPassphrase;
+ private _publicKey;
+ private _accessRequested;
+ /**
+ * @param opts.networkPassphrase - Stellar network passphrase the SDK is
+ * targeting (e.g. `Networks.TESTNET`). Used to verify Freighter's active
+ * network before signing.
+ */
+ constructor(opts: {
+ networkPassphrase: string;
+ });
+ /**
+ * The Freighter account's G… public key.
+ *
+ * Returns an empty string `""` until `connect()` has been called
+ * successfully. Use `isConnected` to check whether the public key is
+ * available, or call `connect()` early (e.g. on page load) so the
+ * key is populated before it's needed.
+ */
+ get publicKey(): string;
+ /**
+ * Explicitly connect to Freighter, request access, and cache the public key.
+ *
+ * Call this early (e.g. on page load) so `publicKey` is available
+ * synchronously afterwards.
+ *
+ * @returns The public key (G…)
+ * @throws {ILNError} WalletNotInstalled | NotConnected | UserRejected | NetworkMismatch
+ */
+ connect(): Promise<string>;
+ /**
+ * Simulate the transaction, then sign with Freighter and return the
+ * signed XDR envelope.
+ *
+ * Steps:
+ * 1. `server.prepareTransaction(tx)` — attaches Soroban footprint
+ * 2. Serialize to base-64 XDR
+ * 3. Pass to Freighter's `signTransaction`
+ * 4. Return the signed XDR
+ *
+ * @param tx - Unsigned transaction with Soroban operations
+ * @param server - Soroban RPC server for simulation
+ * @returns Signed base-64 XDR envelope
+ * @throws {ILNError} WalletNotInstalled | NotConnected | UserRejected | NetworkMismatch
+ */
+ signTransaction(tx: Transaction, server: SorobanRpc.Server): Promise<string>;
+ /** The configured network passphrase. */
+ get networkPassphrase(): string;
+ /** True once `connect()` has succeeded. */
+ get isConnected(): boolean;
+ /** Throw if the Freighter extension isn't installed. */
+ private _ensureInstalled;
+ /** Return the Freighter API object (asserts it's installed). */
+ private _api;
+ /**
+ * Compare the wallet's active network against the configured passphrase.
+ * Throws `NetworkMismatch` when they diverge.
+ */
+ private _verifyNetwork;
+ /** Classify a raw error from Freighter into a typed ILNError. */
+ private _classifySignError;
+}
+export {};
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * FreighterSigner — ISigner adapter for the Freighter browser extension.
+ *
+ * Intended for browser-based dApps where a Stellar wallet extension is
+ * available. Detects whether Freighter is installed, requests network
+ * access on first use, and delegates transaction signing to the wallet.
+ *
+ * ## Flow
+ *
+ * 1. `constructor` — stores configuration; does NOT touch the wallet.
+ * 2. `publicKey` getter — triggers detection + access request, then caches
+ * the public key for the session.
+ * 3. `signTransaction()` — hands the prepared XDR envelope to Freighter
+ * and returns the signed envelope as a base-64 string.
+ *
+ * ## Error handling
+ *
+ * - `ILNError.WalletNotInstalled` — `window.freighterApi` is undefined
+ * - `ILNError.UserRejected` — the user dismissed the Freighter prompt
+ * - `ILNError.NetworkMismatch` — the wallet network differs from the
+ * configured network (e.g. wallet on mainnet but SDK on testnet)
+ *
+ * ## Network-mismatch detection
+ *
+ * Freighter returns the active network via `getNetwork()` (or
+ * `getNetworkDetails()`). Before signing we compare it against the
+ * configured `networkPassphrase` and throw `NetworkMismatch` when they
+ * differ, avoiding hard-to-debug simulation failures downstream.
+ */
+
+import { Networks, SorobanRpc } from "@stellar/stellar-sdk";
+import type { ISigner } from "./ISigner.js";
+import type { Transaction } from "@stellar/stellar-sdk";
+
+// ---------------------------------------------------------------------------
+// Freighter browser API (subset of @stellar/freighter-api)
+// ---------------------------------------------------------------------------
+
+interface FreighterApi {
+ isConnected(): Promise<boolean>;
+ getPublicKey(): Promise<string>;
+ getNetwork(): Promise<string>;
+ signTransaction(
+ xdr: string,
+ opts?: { network?: string; networkPassphrase?: string }
+ ): Promise<string>;
+}
+
+declare global {
+ interface Window {
+ freighterApi?: FreighterApi;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// ILNError
+// ---------------------------------------------------------------------------
+
+/** SDK-level error with a machine-readable code. */
+export class ILNError extends Error {
+ public readonly code: ILNErrorCode;
+
+ constructor(code: ILNErrorCode, message: string) {
+ super(message);
+ this.name = "ILNError";
+ this.code = code;
+ }
+
+ static WalletNotInstalled(): ILNError {
+ return new ILNError(
+ ILNErrorCode.WalletNotInstalled,
+ "Freighter is not installed. Please install the Freighter browser extension."
+ );
+ }
+
+ static UserRejected(): ILNError {
+ return new ILNError(
+ ILNErrorCode.UserRejected,
+ "The user rejected the Freighter request."
+ );
+ }
+
+ static NetworkMismatch(expected: string, actual: string): ILNError {
+ return new ILNError(
+ ILNErrorCode.NetworkMismatch,
+ `Network mismatch: SDK expects "${expected}" but Freighter is on "${actual}". Please switch your wallet network.`
+ );
+ }
+
+ static NotConnected(): ILNError {
+ return new ILNError(
+ ILNErrorCode.NotConnected,
+ "Freighter is locked or not connected. Please unlock the extension."
+ );
+ }
+}
+
+/** Error codes for programmatic handling. */
+export enum ILNErrorCode {
+ WalletNotInstalled = "WALLET_NOT_INSTALLED",
+ UserRejected = "USER_REJECTED",
+ NetworkMismatch = "NETWORK_MISMATCH",
+ NotConnected = "NOT_CONNECTED",
+ SigningFailed = "SIGNING_FAILED",
+}
+
+// ---------------------------------------------------------------------------
+// Network passphrase ↔ Freighter network name mapping
+// ---------------------------------------------------------------------------
+
+const PASSPHRASE_TO_FREIGHTER: Record<string, string> = {
+ [Networks.PUBLIC]: "PUBLIC",
+ [Networks.TESTNET]: "TESTNET",
+};
+
+const FREIGHTER_TO_PASSPHRASE: Record<string, string> = {
+ PUBLIC: Networks.PUBLIC,
+ TESTNET: Networks.TESTNET,
+ FUTURENET: "Test SDF Future Network ; October 2022",
+};
+
+// ---------------------------------------------------------------------------
+// FreighterSigner
+// ---------------------------------------------------------------------------
+
+/**
+ * Browser wallet signer backed by the Freighter extension.
+ *
+ * @example
+ * ```ts
+ * // Testnet
+ * const signer = new FreighterSigner({ networkPassphrase: Networks.TESTNET });
+ * console.log(signer.publicKey); // triggers Freighter access prompt
+ *
+ * // Mainnet
+ * const signer = new FreighterSigner({ networkPassphrase: Networks.PUBLIC });
+ *
+ * // Sign a transaction
+ * const signedXdr = await signer.signTransaction(tx, rpcServer);
+ * ```
+ */
+export class FreighterSigner implements ISigner {
+ private readonly _networkPassphrase: string;
+ private _publicKey: string | null = null;
+ private _accessRequested = false;
+
+ /**
+ * @param opts.networkPassphrase - Stellar network passphrase the SDK is
+ * targeting (e.g. `Networks.TESTNET`). Used to verify Freighter's active
+ * network before signing.
+ */
+ constructor(opts: { networkPassphrase: string }) {
+ this._networkPassphrase = opts.networkPassphrase;
+ }
+
+ // --------------------------------------------------------------------------
+ // ISigner
+ // --------------------------------------------------------------------------
+
+ /**
+ * The Freighter account's G… public key.
+ *
+ * Returns an empty string `""` until `connect()` has been called
+ * successfully. Use `isConnected` to check whether the public key is
+ * available, or call `connect()` early (e.g. on page load) so the
+ * key is populated before it's needed.
+ */
+ get publicKey(): string {
+ return this._publicKey ?? "";
+ }
+
+ /**
+ * Explicitly connect to Freighter, request access, and cache the public key.
+ *
+ * Call this early (e.g. on page load) so `publicKey` is available
+ * synchronously afterwards.
+ *
+ * @returns The public key (G…)
+ * @throws {ILNError} WalletNotInstalled | NotConnected | UserRejected | NetworkMismatch
+ */
+ async connect(): Promise<string> {
+ this._ensureInstalled();
+
+ Iif (!(await this._api().isConnected())) {
+ // Freighter is installed but locked / not connected
+ throw ILNError.NotConnected();
+ }
+
+ // Request access (shows Freighter prompt). Freighter's getPublicKey also
+ // triggers the access prompt if not yet granted.
+ const pk = await this._api().getPublicKey();
+
+ Iif (!pk || pk.length === 0) {
+ throw ILNError.UserRejected();
+ }
+
+ // Verify network
+ await this._verifyNetwork();
+
+ this._publicKey = pk;
+ this._accessRequested = true;
+ return pk;
+ }
+
+ /**
+ * Simulate the transaction, then sign with Freighter and return the
+ * signed XDR envelope.
+ *
+ * Steps:
+ * 1. `server.prepareTransaction(tx)` — attaches Soroban footprint
+ * 2. Serialize to base-64 XDR
+ * 3. Pass to Freighter's `signTransaction`
+ * 4. Return the signed XDR
+ *
+ * @param tx - Unsigned transaction with Soroban operations
+ * @param server - Soroban RPC server for simulation
+ * @returns Signed base-64 XDR envelope
+ * @throws {ILNError} WalletNotInstalled | NotConnected | UserRejected | NetworkMismatch
+ */
+ async signTransaction(
+ tx: Transaction,
+ server: SorobanRpc.Server
+ ): Promise<string> {
+ // Ensure we are connected
+ Iif (!this._publicKey) {
+ await this.connect();
+ }
+
+ // Step 1: simulate to get the footprint
+ const preparedTx = await server.prepareTransaction(tx);
+
+ Iif (SorobanRpc.Api.isSimulationError(preparedTx as any)) {
+ throw new Error(
+ `Soroban simulation failed: ${(preparedTx as any).error}`
+ );
+ }
+
+ // Step 2: serialise to base-64 XDR
+ const envelopeXdr = (preparedTx as any)
+ .toEnvelope()
+ .toXDR("base64") as string;
+
+ // Step 3: ask Freighter to sign
+ const freighterNetwork = PASSPHRASE_TO_FREIGHTER[this._networkPassphrase];
+ Iif (!freighterNetwork) {
+ throw new Error(
+ `Unknown network passphrase: ${this._networkPassphrase}`
+ );
+ }
+
+ let signedXdr: string;
+ try {
+ signedXdr = await this._api().signTransaction(envelopeXdr, {
+ network: freighterNetwork,
+ });
+ } catch (err: unknown) {
+ throw this._classifySignError(err);
+ }
+
+ Iif (!signedXdr || signedXdr.length === 0) {
+ throw ILNError.UserRejected();
+ }
+
+ return signedXdr;
+ }
+
+ // --------------------------------------------------------------------------
+ // Accessors
+ // --------------------------------------------------------------------------
+
+ /** The configured network passphrase. */
+ get networkPassphrase(): string {
+ return this._networkPassphrase;
+ }
+
+ /** True once `connect()` has succeeded. */
+ get isConnected(): boolean {
+ return this._accessRequested && this._publicKey !== null;
+ }
+
+ // --------------------------------------------------------------------------
+ // Internals
+ // --------------------------------------------------------------------------
+
+ /** Throw if the Freighter extension isn't installed. */
+ private _ensureInstalled(): void {
+ // Use a two-step type assertion to safely access the browser global.
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const g = globalThis as any;
+ Iif (typeof g.window === "undefined" || !g.window.freighterApi) {
+ throw ILNError.WalletNotInstalled();
+ }
+ }
+
+ /** Return the Freighter API object (asserts it's installed). */
+ private _api(): FreighterApi {
+ this._ensureInstalled();
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion
+ return (globalThis as any).window.freighterApi!;
+ }
+
+ /**
+ * Compare the wallet's active network against the configured passphrase.
+ * Throws `NetworkMismatch` when they diverge.
+ */
+ private async _verifyNetwork(): Promise<void> {
+ let walletNetwork: string;
+ try {
+ walletNetwork = await this._api().getNetwork();
+ } catch {
+ // Some older Freighter versions don't support getNetwork; skip check
+ return;
+ }
+
+ const expectedPassphrase = FREIGHTER_TO_PASSPHRASE[walletNetwork];
+ Iif (!expectedPassphrase) return; // unknown network; skip
+
+ Iif (expectedPassphrase !== this._networkPassphrase) {
+ throw ILNError.NetworkMismatch(
+ this._networkPassphrase,
+ expectedPassphrase
+ );
+ }
+ }
+
+ /** Classify a raw error from Freighter into a typed ILNError. */
+ private _classifySignError(err: unknown): ILNError {
+ const msg = typeof err === "string" ? err : (err as Error)?.message ?? "";
+
+ const lowered = msg.toLowerCase();
+
+ Iif (
+ lowered.includes("rejected") ||
+ lowered.includes("denied") ||
+ lowered.includes("cancelled") ||
+ lowered.includes("canceled")
+ ) {
+ return ILNError.UserRejected();
+ }
+
+ Iif (
+ lowered.includes("network mismatch") ||
+ (lowered.includes("network") && lowered.includes("switch"))
+ ) {
+ return ILNError.NetworkMismatch(this._networkPassphrase, "unknown");
+ }
+
+ return new ILNError(ILNErrorCode.SigningFailed, msg || "Freighter signing failed");
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 | + + + + + + + + + + + + + + + + + + + + + + + + + + | import type { Transaction, SorobanRpc } from "@stellar/stellar-sdk";
+/**
+ * Common signer interface for all SDK signing adapters.
+ *
+ * Implement this interface to plug in browser wallets (Freighter, Albedo)
+ * or server-side signers (KeypairSigner) without changing call-site code.
+ */
+export interface ISigner {
+ /** Stellar public key (G…) of the signing account. */
+ readonly publicKey: string;
+ /**
+ * Simulate the transaction against a Soroban RPC node to obtain the
+ * Soroban footprint, then sign the prepared transaction and return the
+ * signed XDR envelope as a base-64 string.
+ *
+ * Implementations must:
+ * 1. Call `server.prepareTransaction(tx)` to attach the footprint.
+ * 2. Sign the prepared transaction with the underlying credentials.
+ * 3. Return `signedTx.toEnvelope().toXDR("base64")`.
+ *
+ * @param tx - Unsigned Stellar transaction (already has operations)
+ * @param server - Soroban RPC server used for simulation
+ * @returns Base-64 XDR of the signed transaction envelope
+ */
+ signTransaction(tx: Transaction, server: SorobanRpc.Server): Promise<string>;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * KeypairSigner — ISigner adapter for raw Stellar keypairs.
+ *
+ * Intended for Node.js scripts, CLI tools, and bots where a browser wallet
+ * is not available. Accepts either a `Keypair` instance or a secret-key
+ * string (S…).
+ *
+ * Two-step flow on every `signTransaction()` call:
+ * 1. Simulate the transaction via `server.prepareTransaction()` to fetch
+ * the Soroban footprint (ledger entries, auth entries, resource limits).
+ * 2. Sign the *prepared* transaction and return the signed XDR envelope.
+ *
+ * Security notice
+ * ---------------
+ * Hard-coding secret keys in source files is dangerous. KeypairSigner emits
+ * a `console.warn` when it detects that the process is not running inside a
+ * test environment (`NODE_ENV !== "test"`) **and** the secret was supplied as
+ * a plain string literal. Pass the secret via an environment variable instead:
+ *
+ * ```ts
+ * const signer = new KeypairSigner(process.env.LP_SECRET_KEY!);
+ * ```
+ */
+import { Keypair, SorobanRpc, Transaction } from "@stellar/stellar-sdk";
+import type { ISigner } from "./ISigner.js";
+/**
+ * Server-side ISigner backed by a Stellar keypair.
+ *
+ * @example
+ * ```ts
+ * // From environment variable (recommended)
+ * const signer = new KeypairSigner(process.env.LP_SECRET!);
+ *
+ * // From an existing Keypair instance
+ * const kp = Keypair.fromSecret(process.env.LP_SECRET!);
+ * const signer = new KeypairSigner(kp);
+ *
+ * // Sign a transaction
+ * const signedXdr = await signer.signTransaction(tx, rpcServer);
+ * ```
+ */
+export declare class KeypairSigner implements ISigner {
+ private readonly _keypair;
+ /**
+ * @param keypairOrSecret - A `Keypair` instance **or** a Stellar secret key
+ * string starting with `S`. When a plain string is supplied outside of a
+ * test environment a security warning is emitted.
+ */
+ constructor(keypairOrSecret: Keypair | string);
+ /** Stellar G… public key of this signer. */
+ get publicKey(): string;
+ /**
+ * Simulate the transaction to obtain the Soroban footprint, sign the
+ * prepared transaction, and return the signed XDR envelope as base-64.
+ *
+ * Steps:
+ * 1. `server.prepareTransaction(tx)` — attaches footprint + auth entries.
+ * 2. `preparedTx.sign(keypair)` — ECDSA/Ed25519 signature applied.
+ * 3. Returns `preparedTx.toEnvelope().toXDR("base64")`.
+ *
+ * @param tx - Unsigned transaction with at least one Soroban operation
+ * @param server - Soroban RPC server used for simulation
+ * @returns Signed base-64 XDR envelope ready for `server.sendTransaction()`
+ *
+ * @throws {Error} When Soroban simulation fails (contract error, bad auth,
+ * resource limit exceeded, etc.)
+ */
+ signTransaction(tx: Transaction, server: SorobanRpc.Server): Promise<string>;
+ /**
+ * Expose the underlying keypair for use-cases that need raw sign/verify
+ * access (e.g. building multi-sig transactions).
+ *
+ * Treat the returned keypair as read-only; do not call `keypair.sign()`
+ * directly on transaction envelopes — use `signTransaction()` so the
+ * simulation step is always executed.
+ */
+ get keypair(): Keypair;
+ /**
+ * Create a KeypairSigner from a secret key stored in an environment
+ * variable.
+ *
+ * ```ts
+ * const signer = KeypairSigner.fromEnv("LP_SECRET_KEY");
+ * ```
+ *
+ * @param envVar - Name of the environment variable holding the secret key
+ * @throws {Error} When the environment variable is not set
+ */
+ static fromEnv(envVar: string): KeypairSigner;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * KeypairSigner — ISigner adapter for raw Stellar keypairs.
+ *
+ * Intended for Node.js scripts, CLI tools, and bots where a browser wallet
+ * is not available. Accepts either a `Keypair` instance or a secret-key
+ * string (S…).
+ *
+ * Two-step flow on every `signTransaction()` call:
+ * 1. Simulate the transaction via `server.prepareTransaction()` to fetch
+ * the Soroban footprint (ledger entries, auth entries, resource limits).
+ * 2. Sign the *prepared* transaction and return the signed XDR envelope.
+ *
+ * Security notice
+ * ---------------
+ * Hard-coding secret keys in source files is dangerous. KeypairSigner emits
+ * a `console.warn` when it detects that the process is not running inside a
+ * test environment (`NODE_ENV !== "test"`) **and** the secret was supplied as
+ * a plain string literal. Pass the secret via an environment variable instead:
+ *
+ * ```ts
+ * const signer = new KeypairSigner(process.env.LP_SECRET_KEY!);
+ * ```
+ */
+
+import { Keypair, SorobanRpc, Transaction } from "@stellar/stellar-sdk";
+import type { ISigner } from "./ISigner.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Detect a test environment heuristically. */
+function isTestEnvironment(): boolean {
+ return (
+ process.env["NODE_ENV"] === "test" ||
+ process.env["JEST_WORKER_ID"] !== undefined ||
+ process.env["VITEST"] !== undefined
+ );
+}
+
+/**
+ * Heuristic: a secret key that looks like it was pasted literally into source
+ * rather than read from the environment. We flag when the value is a
+ * hardcoded default / example key or when it begins with `S` and
+ * `SECRET`/`PRIVATE` are not in the source call-stack (impossible to detect
+ * reliably, so we only warn, never block).
+ */
+function warnIfHardcodedSecret(secret: string): void {
+ Iif (isTestEnvironment()) return;
+
+ // Well-known example keys used in docs / tutorials
+ const knownExamples = new Set([
+ "SCZANGBA5RLAZ7IQVXSRQD5KXJLJPNWZPWHSB4TWJNSC2DL5CGFJ6Y2",
+ "SDASDASDASDASDASDASDASDASDASDASDASDASDASDASDASDASDA",
+ ]);
+
+ Iif (knownExamples.has(secret)) {
+ console.warn(
+ "[KeypairSigner] WARNING: You appear to be using a well-known example " +
+ "secret key. Never use example keys in production."
+ );
+ return;
+ }
+
+ // Generic warning: secret supplied as a string literal rather than via env
+ console.warn(
+ "[KeypairSigner] WARNING: Passing a secret key as a plain string is " +
+ "risky. Load it from an environment variable instead: " +
+ "new KeypairSigner(process.env.SECRET_KEY!)"
+ );
+}
+
+// ---------------------------------------------------------------------------
+// KeypairSigner
+// ---------------------------------------------------------------------------
+
+/**
+ * Server-side ISigner backed by a Stellar keypair.
+ *
+ * @example
+ * ```ts
+ * // From environment variable (recommended)
+ * const signer = new KeypairSigner(process.env.LP_SECRET!);
+ *
+ * // From an existing Keypair instance
+ * const kp = Keypair.fromSecret(process.env.LP_SECRET!);
+ * const signer = new KeypairSigner(kp);
+ *
+ * // Sign a transaction
+ * const signedXdr = await signer.signTransaction(tx, rpcServer);
+ * ```
+ */
+export class KeypairSigner implements ISigner {
+ private readonly _keypair: Keypair;
+
+ /**
+ * @param keypairOrSecret - A `Keypair` instance **or** a Stellar secret key
+ * string starting with `S`. When a plain string is supplied outside of a
+ * test environment a security warning is emitted.
+ */
+ constructor(keypairOrSecret: Keypair | string) {
+ if (typeof keypairOrSecret === "string") {
+ warnIfHardcodedSecret(keypairOrSecret);
+ this._keypair = Keypair.fromSecret(keypairOrSecret);
+ } else {
+ this._keypair = keypairOrSecret;
+ }
+ }
+
+ // --------------------------------------------------------------------------
+ // ISigner
+ // --------------------------------------------------------------------------
+
+ /** Stellar G… public key of this signer. */
+ get publicKey(): string {
+ return this._keypair.publicKey();
+ }
+
+ /**
+ * Simulate the transaction to obtain the Soroban footprint, sign the
+ * prepared transaction, and return the signed XDR envelope as base-64.
+ *
+ * Steps:
+ * 1. `server.prepareTransaction(tx)` — attaches footprint + auth entries.
+ * 2. `preparedTx.sign(keypair)` — ECDSA/Ed25519 signature applied.
+ * 3. Returns `preparedTx.toEnvelope().toXDR("base64")`.
+ *
+ * @param tx - Unsigned transaction with at least one Soroban operation
+ * @param server - Soroban RPC server used for simulation
+ * @returns Signed base-64 XDR envelope ready for `server.sendTransaction()`
+ *
+ * @throws {Error} When Soroban simulation fails (contract error, bad auth,
+ * resource limit exceeded, etc.)
+ */
+ async signTransaction(
+ tx: Transaction,
+ server: SorobanRpc.Server
+ ): Promise<string> {
+ // Step 1: simulate → get footprint
+ const preparedTx = await server.prepareTransaction(tx);
+
+ Iif (SorobanRpc.Api.isSimulationError(preparedTx as any)) {
+ throw new Error(
+ `Soroban simulation failed: ${(preparedTx as any).error}`
+ );
+ }
+
+ // Step 2: sign
+ (preparedTx as Transaction).sign(this._keypair);
+
+ // Step 3: serialise
+ return (preparedTx as Transaction).toEnvelope().toXDR("base64");
+ }
+
+ // --------------------------------------------------------------------------
+ // Convenience
+ // --------------------------------------------------------------------------
+
+ /**
+ * Expose the underlying keypair for use-cases that need raw sign/verify
+ * access (e.g. building multi-sig transactions).
+ *
+ * Treat the returned keypair as read-only; do not call `keypair.sign()`
+ * directly on transaction envelopes — use `signTransaction()` so the
+ * simulation step is always executed.
+ */
+ get keypair(): Keypair {
+ return this._keypair;
+ }
+
+ /**
+ * Create a KeypairSigner from a secret key stored in an environment
+ * variable.
+ *
+ * ```ts
+ * const signer = KeypairSigner.fromEnv("LP_SECRET_KEY");
+ * ```
+ *
+ * @param envVar - Name of the environment variable holding the secret key
+ * @throws {Error} When the environment variable is not set
+ */
+ static fromEnv(envVar: string): KeypairSigner {
+ const secret = process.env[envVar];
+ Iif (!secret) {
+ throw new Error(
+ `KeypairSigner.fromEnv: environment variable "${envVar}" is not set`
+ );
+ }
+ // fromEnv is the recommended pattern — no warning needed
+ const kp = Keypair.fromSecret(secret);
+ return new KeypairSigner(kp);
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| FreighterSigner.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| FreighterSigner.ts | +
+
+ |
+ 0% | +0/66 | +0% | +0/36 | +0% | +0/16 | +0% | +0/65 | +
| ISigner.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| KeypairSigner.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| KeypairSigner.ts | +
+
+ |
+ 0% | +0/24 | +0% | +0/9 | +0% | +0/7 | +0% | +0/23 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Options for the fundInvoice() SDK method.
+ */
+export interface FundOptions {
+ /**
+ * When true, the SDK will reject funding if the oracle price feed is stale
+ * or unavailable. Defaults to false.
+ */
+ requireOracleVerification?: boolean;
+ /**
+ * Called when the LP's current token allowance is less than the invoice
+ * amount and an approval transaction is about to be built.
+ *
+ * @param params.requiredAmount - Amount that needs to be approved (in token base units)
+ * @param params.currentAllowance - Current allowance the contract holds
+ */
+ onApprovalRequired?: (params: {
+ requiredAmount: bigint;
+ currentAllowance: bigint;
+ }) => void;
+ /**
+ * Called immediately after the approval transaction has been submitted to
+ * the network (before confirmation).
+ *
+ * @param params.approveTxHash - Hash of the submitted approval transaction
+ */
+ onApprovalSent?: (params: {
+ approveTxHash: string;
+ }) => void;
+ /**
+ * Called after the fund_invoice contract call has been simulated and the
+ * transaction is ready to sign and submit.
+ *
+ * @param params.effectiveYieldBps - Annualised yield in basis points derived
+ * from the invoice's discount rate and time-to-due-date
+ * @param params.invoiceId - The invoice being funded
+ */
+ onFunded?: (params: {
+ effectiveYieldBps: number;
+ invoiceId: bigint;
+ }) => void;
+}
+/**
+ * Return value of a successful fundInvoice() call.
+ */
+export interface FundResult {
+ /** Hash of the fund_invoice transaction. */
+ txHash: string;
+ /**
+ * Annualised effective yield in basis points for this funding position.
+ * Derived from discountRate × daysToMaturity / 365.
+ */
+ effectiveYieldBps: number;
+}
+/**
+ * Minimal view of an invoice returned by get_invoice().
+ */
+export interface InvoiceView {
+ id: bigint;
+ /** Token contract address used for this invoice. */
+ token: string;
+ /** Full invoice amount in token base units. */
+ amount: bigint;
+ /** Unix timestamp (seconds) when payment is due. */
+ dueDate: number;
+ /** Discount rate in basis points (e.g. 300 = 3.00 %). */
+ discountRate: number;
+ /** Current lifecycle status string. */
+ status: string;
+}
+/** Allowance query parameters. */
+export interface AllowanceParams {
+ /** Token contract address (SEP-41 / SAC). */
+ tokenAddress: string;
+ /** Address of the token owner (the LP). */
+ owner: string;
+ /** Address that will spend the tokens (the invoice-liquidity contract). */
+ spender: string;
+}
+/** Result of an allowance check. */
+export interface AllowanceResult {
+ /** Current approved amount in token base units. */
+ amount: bigint;
+ /** Ledger sequence at which the allowance expires (0 = no expiry stored). */
+ expirationLedger: number;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Governance types for the ILN SDK.
+ *
+ * Mirrors the on-chain governance contract's proposal model so TypeScript
+ * integrators can create proposals, vote and execute without hand-rolling
+ * Soroban calls.
+ */
+/**
+ * The set of parameter-changing actions a proposal can request.
+ *
+ * The numeric values match the contract's `ProposalAction` enum discriminants
+ * and are used directly as the `u32` argument when encoding the call.
+ */
+export declare enum ProposalAction {
+ /** Update the protocol fee, in basis points. */
+ UpdateProtocolFee = 0,
+ /** Update the minimum payer reputation required to submit an invoice. */
+ UpdateMinReputation = 1,
+ /** Update the oracle contract address (value is an address index/handle). */
+ UpdateOracle = 2,
+ /** Pause the contract (proposedValue ignored). */
+ PauseContract = 3,
+ /** Unpause the contract (proposedValue ignored). */
+ UnpauseContract = 4,
+ /** Update the default grace period, in seconds. */
+ UpdateGracePeriod = 5
+}
+/** Lifecycle status of a proposal. */
+export declare enum ProposalStatus {
+ Active = "Active",
+ Passed = "Passed",
+ Rejected = "Rejected",
+ Executed = "Executed"
+}
+/** A governance proposal as returned by the contract. */
+export interface Proposal {
+ /** Unique proposal identifier. */
+ id: bigint;
+ /** The parameter-changing action this proposal requests. */
+ action: ProposalAction;
+ /** The proposed new value for the action's parameter. */
+ proposedValue: bigint;
+ /** Hex-encoded 32-byte hash of the off-chain proposal description. */
+ descriptionHash: string;
+ /** Address that created the proposal. */
+ proposer: string;
+ /** Total weight of votes in support. */
+ votesFor: bigint;
+ /** Total weight of votes against. */
+ votesAgainst: bigint;
+ /** Current lifecycle status. */
+ status: ProposalStatus;
+ /** Unix timestamp (seconds) when voting closes. */
+ votingEndsAt: number;
+}
+/** Optional filter for {@link listProposals}. */
+export interface ProposalFilter {
+ /** Only return proposals in this status. */
+ status?: ProposalStatus;
+ /** Only return proposals created by this address. */
+ proposer?: string;
+}
+/** Result of creating a proposal. */
+export interface CreateProposalResult {
+ proposalId: bigint;
+ txHash: string;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /** + * Governance types for the ILN SDK. + * + * Mirrors the on-chain governance contract's proposal model so TypeScript + * integrators can create proposals, vote and execute without hand-rolling + * Soroban calls. + */ + +/** + * The set of parameter-changing actions a proposal can request. + * + * The numeric values match the contract's `ProposalAction` enum discriminants + * and are used directly as the `u32` argument when encoding the call. + */ +export enum ProposalAction { + /** Update the protocol fee, in basis points. */ + UpdateProtocolFee = 0, + /** Update the minimum payer reputation required to submit an invoice. */ + UpdateMinReputation = 1, + /** Update the oracle contract address (value is an address index/handle). */ + UpdateOracle = 2, + /** Pause the contract (proposedValue ignored). */ + PauseContract = 3, + /** Unpause the contract (proposedValue ignored). */ + UnpauseContract = 4, + /** Update the default grace period, in seconds. */ + UpdateGracePeriod = 5, +} + +/** Lifecycle status of a proposal. */ +export enum ProposalStatus { + Active = "Active", + Passed = "Passed", + Rejected = "Rejected", + Executed = "Executed", +} + +/** A governance proposal as returned by the contract. */ +export interface Proposal { + /** Unique proposal identifier. */ + id: bigint; + /** The parameter-changing action this proposal requests. */ + action: ProposalAction; + /** The proposed new value for the action's parameter. */ + proposedValue: bigint; + /** Hex-encoded 32-byte hash of the off-chain proposal description. */ + descriptionHash: string; + /** Address that created the proposal. */ + proposer: string; + /** Total weight of votes in support. */ + votesFor: bigint; + /** Total weight of votes against. */ + votesAgainst: bigint; + /** Current lifecycle status. */ + status: ProposalStatus; + /** Unix timestamp (seconds) when voting closes. */ + votingEndsAt: number; +} + +/** Optional filter for {@link listProposals}. */ +export interface ProposalFilter { + /** Only return proposals in this status. */ + status?: ProposalStatus; + /** Only return proposals created by this address. */ + proposer?: string; +} + +/** Result of creating a proposal. */ +export interface CreateProposalResult { + proposalId: bigint; + txHash: string; +} + |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| governance.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| governance.ts | +
+
+ |
+ 0% | +0/12 | +0% | +0/4 | +0% | +0/2 | +0% | +0/12 | +
| invoice.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| params.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 | + + + + + + + + + + + + + + + + + + | export type InvoiceStatus = 'Pending' | 'Funded' | 'PartiallyFunded' | 'Paid' | 'Defaulted' | 'Appealed' | 'Disputed' | 'Expired' | 'Cancelled';
+export interface Invoice {
+ id: bigint;
+ freelancer: string;
+ payer: string;
+ token: string;
+ amount: bigint;
+ dueDate: number;
+ discountRate: number;
+ status: InvoiceStatus;
+ funder?: string;
+ fundedAt?: number;
+ amountFunded: bigint;
+ amountPaid: bigint;
+ referralCode?: string;
+ submitterReputation: number;
+ effectiveYieldBps: number;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 | + + + + + + + + + + + + + + + + + + | export type SupportedToken = 'USDC' | 'EURC' | 'XLM' | string;
+export interface SubmitInvoiceParams {
+ payer: string;
+ amount: bigint;
+ token: SupportedToken;
+ discountRate: number;
+ dueDate: Date | number;
+ referralCode?: string;
+}
+export interface SubmitInvoiceResult {
+ invoiceId: bigint;
+ txHash: string;
+}
+export interface MarkPaidResult {
+ txHash: string;
+ remainingBalance: bigint;
+ fullySettled: boolean;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Allowance utilities for SEP-41 / Stellar Asset Contract tokens.
+ *
+ * Abstracts the "check allowance → approve if needed" pattern so callers
+ * (e.g. fundInvoice) don't need to deal with raw XDR or Soroban operation
+ * building directly.
+ */
+import { SorobanRpc, Account } from "@stellar/stellar-sdk";
+import type { AllowanceParams, AllowanceResult } from "../types.js";
+/**
+ * Query the current SEP-41 token allowance granted by `owner` to `spender`.
+ *
+ * Calls `allowance(from, spender)` on the token contract and decodes the
+ * return value. Both the struct form `{ amount, expiration_ledger }` (SEP-41)
+ * and plain `i128` (older SAC) are handled.
+ *
+ * @param server - Soroban RPC server instance
+ * @param params - Token address, owner, and spender addresses
+ * @param sourceAccount - Account used as the simulation source (sequence consumed)
+ * @returns AllowanceResult with `amount` (bigint) and `expirationLedger`
+ *
+ * @throws When the RPC simulation returns an error response
+ */
+export declare function getAllowance(server: SorobanRpc.Server, params: AllowanceParams, sourceAccount: Account): Promise<AllowanceResult>;
+/**
+ * Build a prepared (but unsigned) `approve` transaction envelope for a
+ * SEP-41 token contract.
+ *
+ * The returned base64-XDR string must be signed by the token owner's keypair
+ * before submission.
+ *
+ * Expiration is set to `currentLedger + 720` (≈ 1 hour at ~2s/ledger).
+ *
+ * @param server - Soroban RPC server instance
+ * @param tokenAddress - Token contract address
+ * @param ownerAccount - Account object for the token owner (the LP)
+ * @param spenderAddress - Address to approve (the invoice-liquidity contract)
+ * @param amount - Amount to approve in token base units
+ * @param networkPassphrase - Stellar network passphrase (defaults to TESTNET)
+ * @returns Base64-encoded XDR of the prepared transaction envelope
+ *
+ * @throws When the Soroban RPC `prepareTransaction` call fails
+ */
+export declare function buildApproveTransaction(server: SorobanRpc.Server, tokenAddress: string, ownerAccount: Account, spenderAddress: string, amount: bigint, networkPassphrase?: string): Promise<string>;
+/**
+ * Returns `true` when the given allowance satisfies both requirements:
+ * 1. `allowance.amount >= required`
+ * 2. The allowance will not expire before `minExpirationLedger` (when
+ * provided). An `expirationLedger` of `0` is treated as "no expiry
+ * stored" and always passes the expiry check.
+ *
+ * @param allowance - Current allowance from getAllowance()
+ * @param required - Minimum amount needed (in token base units)
+ * @param minExpirationLedger - Optional: require the allowance to remain
+ * valid at least until this ledger sequence
+ */
+export declare function isAllowanceSufficient(allowance: AllowanceResult, required: bigint, minExpirationLedger?: number): boolean;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Allowance utilities for SEP-41 / Stellar Asset Contract tokens.
+ *
+ * Abstracts the "check allowance → approve if needed" pattern so callers
+ * (e.g. fundInvoice) don't need to deal with raw XDR or Soroban operation
+ * building directly.
+ */
+
+import {
+ Contract,
+ SorobanRpc,
+ TransactionBuilder,
+ Networks,
+ BASE_FEE,
+ scValToNative,
+ nativeToScVal,
+ Address,
+ Account,
+} from "@stellar/stellar-sdk";
+import type { AllowanceParams, AllowanceResult } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// getAllowance
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the current SEP-41 token allowance granted by `owner` to `spender`.
+ *
+ * Calls `allowance(from, spender)` on the token contract and decodes the
+ * return value. Both the struct form `{ amount, expiration_ledger }` (SEP-41)
+ * and plain `i128` (older SAC) are handled.
+ *
+ * @param server - Soroban RPC server instance
+ * @param params - Token address, owner, and spender addresses
+ * @param sourceAccount - Account used as the simulation source (sequence consumed)
+ * @returns AllowanceResult with `amount` (bigint) and `expirationLedger`
+ *
+ * @throws When the RPC simulation returns an error response
+ */
+export async function getAllowance(
+ server: SorobanRpc.Server,
+ params: AllowanceParams,
+ sourceAccount: Account
+): Promise<AllowanceResult> {
+ const tokenContract = new Contract(params.tokenAddress);
+
+ const op = tokenContract.call(
+ "allowance",
+ new Address(params.owner).toScVal(),
+ new Address(params.spender).toScVal()
+ );
+
+ const tx = new TransactionBuilder(sourceAccount, {
+ fee: BASE_FEE,
+ networkPassphrase: Networks.TESTNET,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const simResult = await server.simulateTransaction(tx);
+
+ Iif (SorobanRpc.Api.isSimulationError(simResult)) {
+ throw new Error(`Allowance simulation failed: ${simResult.error}`);
+ }
+
+ Iif (!simResult.result?.retval) {
+ return { amount: 0n, expirationLedger: 0 };
+ }
+
+ const native = scValToNative(simResult.result.retval);
+
+ // SEP-41: allowance returns { amount: i128, expiration_ledger: u32 }
+ Iif (typeof native === "object" && native !== null && "amount" in native) {
+ const obj = native as Record<string, unknown>;
+ return {
+ amount: BigInt(String(obj["amount"])),
+ expirationLedger: Number(obj["expiration_ledger"] ?? 0),
+ };
+ }
+
+ // Older SAC: plain i128
+ return {
+ amount: BigInt(String(native)),
+ expirationLedger: 0,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// buildApproveTransaction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a prepared (but unsigned) `approve` transaction envelope for a
+ * SEP-41 token contract.
+ *
+ * The returned base64-XDR string must be signed by the token owner's keypair
+ * before submission.
+ *
+ * Expiration is set to `currentLedger + 720` (≈ 1 hour at ~2s/ledger).
+ *
+ * @param server - Soroban RPC server instance
+ * @param tokenAddress - Token contract address
+ * @param ownerAccount - Account object for the token owner (the LP)
+ * @param spenderAddress - Address to approve (the invoice-liquidity contract)
+ * @param amount - Amount to approve in token base units
+ * @param networkPassphrase - Stellar network passphrase (defaults to TESTNET)
+ * @returns Base64-encoded XDR of the prepared transaction envelope
+ *
+ * @throws When the Soroban RPC `prepareTransaction` call fails
+ */
+export async function buildApproveTransaction(
+ server: SorobanRpc.Server,
+ tokenAddress: string,
+ ownerAccount: Account,
+ spenderAddress: string,
+ amount: bigint,
+ networkPassphrase: string = Networks.TESTNET
+): Promise<string> {
+ const tokenContract = new Contract(tokenAddress);
+
+ // expiration_ledger ≈ now + 1 hour (720 ledgers @ ~5s/ledger)
+ const ledgerInfo = await server.getLatestLedger();
+ const expirationLedger = ledgerInfo.sequence + 720;
+
+ const op = tokenContract.call(
+ "approve",
+ new Address(ownerAccount.accountId()).toScVal(),
+ new Address(spenderAddress).toScVal(),
+ nativeToScVal(amount, { type: "i128" }),
+ nativeToScVal(expirationLedger, { type: "u32" })
+ );
+
+ const tx = new TransactionBuilder(ownerAccount, {
+ fee: BASE_FEE,
+ networkPassphrase,
+ })
+ .addOperation(op)
+ .setTimeout(30)
+ .build();
+
+ const preparedTx = await server.prepareTransaction(tx);
+ return (preparedTx as any).toEnvelope().toXDR("base64");
+}
+
+// ---------------------------------------------------------------------------
+// isAllowanceSufficient
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when the given allowance satisfies both requirements:
+ * 1. `allowance.amount >= required`
+ * 2. The allowance will not expire before `minExpirationLedger` (when
+ * provided). An `expirationLedger` of `0` is treated as "no expiry
+ * stored" and always passes the expiry check.
+ *
+ * @param allowance - Current allowance from getAllowance()
+ * @param required - Minimum amount needed (in token base units)
+ * @param minExpirationLedger - Optional: require the allowance to remain
+ * valid at least until this ledger sequence
+ */
+export function isAllowanceSufficient(
+ allowance: AllowanceResult,
+ required: bigint,
+ minExpirationLedger?: number
+): boolean {
+ Iif (allowance.amount < required) return false;
+
+ Iif (
+ minExpirationLedger !== undefined &&
+ allowance.expirationLedger > 0 &&
+ allowance.expirationLedger < minExpirationLedger
+ ) {
+ return false;
+ }
+
+ return true;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| allowance.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| allowance.ts | +
+
+ |
+ 0% | +0/25 | +0% | +0/14 | +0% | +0/3 | +0% | +0/24 | +
| tokenRegistry.ts | +
+
+ |
+ 0% | +0/13 | +0% | +0/2 | +0% | +0/6 | +0% | +0/13 | +
| validate.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| validate.ts | +
+
+ |
+ 0% | +0/37 | +0% | +0/26 | +0% | +0/5 | +0% | +0/37 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * TokenRegistry — centralised multi-token metadata for the ILN SDK (issue #227).
+ *
+ * Provides contract addresses, decimal precision, and minimum amounts
+ * for supported tokens on Stellar testnet and mainnet.
+ */
+
+export type NetworkName = "testnet" | "mainnet";
+
+export interface TokenInfo {
+ /** Token symbol (e.g. "USDC"). */
+ symbol: string;
+ /** Stellar contract address (SAC or SEP-41) for the given network. */
+ contractAddress: string;
+ /** Number of decimal places used by the token (e.g. 7 for USDC on Stellar). */
+ decimals: number;
+ /** Minimum meaningful amount in base units (to guard against dust). */
+ minimumAmount: bigint;
+}
+
+/** Built-in token registry entries per network. */
+const REGISTRY: Record<NetworkName, Record<string, TokenInfo>> = {
+ testnet: {
+ USDC: {
+ symbol: "USDC",
+ contractAddress: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
+ decimals: 7,
+ minimumAmount: 1_000_000n, // 0.1 USDC
+ },
+ EURC: {
+ symbol: "EURC",
+ contractAddress: "GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO575XC74F3X6U",
+ decimals: 7,
+ minimumAmount: 1_000_000n,
+ },
+ XLM: {
+ symbol: "XLM",
+ contractAddress: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
+ decimals: 7,
+ minimumAmount: 10_000_000n, // 1 XLM
+ },
+ },
+ mainnet: {
+ USDC: {
+ symbol: "USDC",
+ contractAddress: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
+ decimals: 7,
+ minimumAmount: 1_000_000n,
+ },
+ EURC: {
+ symbol: "EURC",
+ contractAddress: "CDTKPWPLOURQA2SGTKTUQOWRCBZEORB4BWBOMJ3D3ZTQQSGE5F6JBQLV",
+ decimals: 7,
+ minimumAmount: 1_000_000n,
+ },
+ XLM: {
+ symbol: "XLM",
+ contractAddress: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
+ decimals: 7,
+ minimumAmount: 10_000_000n,
+ },
+ },
+};
+
+export class TokenRegistry {
+ private readonly network: NetworkName;
+
+ constructor(network: NetworkName = "testnet") {
+ this.network = network;
+ }
+
+ /**
+ * Look up a token by symbol.
+ * @throws {Error} when the symbol is not found for the current network.
+ */
+ get(symbol: string): TokenInfo {
+ const entry = REGISTRY[this.network][symbol.toUpperCase()];
+ Iif (!entry) {
+ throw new Error(
+ `Token "${symbol}" is not registered for network "${this.network}". ` +
+ `Supported: ${Object.keys(REGISTRY[this.network]).join(", ")}`
+ );
+ }
+ return entry;
+ }
+
+ /** Returns all registered tokens for the current network. */
+ list(): TokenInfo[] {
+ return Object.values(REGISTRY[this.network]);
+ }
+
+ /**
+ * Register a custom token at runtime (e.g. project-specific SAC tokens).
+ * Custom entries override built-ins for the same symbol.
+ */
+ register(info: TokenInfo): void {
+ REGISTRY[this.network][info.symbol.toUpperCase()] = info;
+ }
+
+ /**
+ * Convert a human-readable amount to base units.
+ * @example registry.toBaseUnits("USDC", 10.5) // 105_000_000n
+ */
+ toBaseUnits(symbol: string, humanAmount: number): bigint {
+ const { decimals } = this.get(symbol);
+ return BigInt(Math.round(humanAmount * 10 ** decimals));
+ }
+
+ /**
+ * Convert base units back to a human-readable number.
+ * @example registry.fromBaseUnits("USDC", 105_000_000n) // 10.5
+ */
+ fromBaseUnits(symbol: string, baseAmount: bigint): number {
+ const { decimals } = this.get(symbol);
+ return Number(baseAmount) / 10 ** decimals;
+ }
+}
+
+/** Default singleton — testnet. Swap via `new TokenRegistry("mainnet")`. */
+export const tokenRegistry = new TokenRegistry("testnet");
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Centralised input validation utilities for the ILN SDK.
+ *
+ * Validation logic for Stellar G-addresses, contract IDs, amounts, discount
+ * rates and due dates was previously duplicated across method implementations.
+ * Concentrating it here keeps error messages consistent and reduces bugs.
+ *
+ * Each validator throws a typed {@link ILNError} on failure and returns `void`
+ * on success, so they can be used as guard clauses at the top of methods.
+ */
+import type { SupportedToken } from "../types/params.js";
+/** Minimum allowed discount rate in basis points. */
+export declare const MIN_DISCOUNT_BPS = 1;
+/** Maximum allowed discount rate in basis points (50%). */
+export declare const MAX_DISCOUNT_BPS = 5000;
+/** Minimum invoice duration: 24 hours from now. */
+export declare const MIN_DUE_DATE_MS: number;
+/** Maximum invoice duration: 365 days from now. */
+export declare const MAX_DUE_DATE_MS: number;
+/**
+ * Validate a Stellar account (G…) address.
+ *
+ * @param address - The address to validate
+ * @throws {ILNError.InvalidAddress} If the address is empty, not a string, does
+ * not start with `G`, or is not 56 characters long.
+ */
+export declare function validateGAddress(address: string): void;
+/**
+ * Validate a Soroban contract (C…) address.
+ *
+ * @param contractId - The contract ID to validate
+ * @throws {ILNError.InvalidAddress} If the contract ID is malformed.
+ */
+export declare function validateContractId(contractId: string): void;
+/**
+ * Validate a token amount against a minimum and the token's precision.
+ *
+ * @param amount - The amount in token base units
+ * @param min - The minimum allowed amount (inclusive) in base units
+ * @param token - The token the amount is denominated in
+ * @throws {ILNError.InvalidAmount} If the amount is not a positive integer, is
+ * below the minimum, or exceeds the token's precision.
+ */
+export declare function validateAmount(amount: bigint, min: bigint, token: SupportedToken): void;
+/**
+ * Validate a discount rate.
+ *
+ * @param rate - Discount rate in basis points (1–5000)
+ * @throws {ILNError.InvalidDiscountRate} If the rate is outside the 1–5000 bps range.
+ */
+export declare function validateDiscountRate(rate: number): void;
+/**
+ * Validate an invoice due date.
+ *
+ * @param date - The due date
+ * @throws {ILNError.InvalidDueDate} If the date is invalid.
+ * @throws {ILNError.DueDateTooSoon} If the date is less than 24h from now.
+ * @throws {ILNError.DueDateTooFar} If the date is more than 365 days from now.
+ */
+export declare function validateDueDate(date: Date): void;
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Centralised input validation utilities for the ILN SDK.
+ *
+ * Validation logic for Stellar G-addresses, contract IDs, amounts, discount
+ * rates and due dates was previously duplicated across method implementations.
+ * Concentrating it here keeps error messages consistent and reduces bugs.
+ *
+ * Each validator throws a typed {@link ILNError} on failure and returns `void`
+ * on success, so they can be used as guard clauses at the top of methods.
+ */
+
+import { ILNError } from "../errors.js";
+import type { SupportedToken } from "../types/params.js";
+
+/** Length of a Stellar StrKey-encoded public key (G…) address. */
+const G_ADDRESS_LENGTH = 56;
+/** Length of a Stellar StrKey-encoded contract (C…) address. */
+const C_ADDRESS_LENGTH = 56;
+
+/** Minimum allowed discount rate in basis points. */
+export const MIN_DISCOUNT_BPS = 1;
+/** Maximum allowed discount rate in basis points (50%). */
+export const MAX_DISCOUNT_BPS = 5000;
+
+/** Minimum invoice duration: 24 hours from now. */
+export const MIN_DUE_DATE_MS = 24 * 60 * 60 * 1000;
+/** Maximum invoice duration: 365 days from now. */
+export const MAX_DUE_DATE_MS = 365 * 24 * 60 * 60 * 1000;
+
+/** Base-unit precision (decimals) for each supported token. */
+const TOKEN_DECIMALS: Record<string, number> = {
+ USDC: 7,
+ EURC: 7,
+ XLM: 7,
+};
+
+/**
+ * Validate a Stellar account (G…) address.
+ *
+ * @param address - The address to validate
+ * @throws {ILNError.InvalidAddress} If the address is empty, not a string, does
+ * not start with `G`, or is not 56 characters long.
+ */
+export function validateGAddress(address: string): void {
+ Iif (typeof address !== "string" || address.length === 0) {
+ throw new ILNError.InvalidAddress("Address must be a non-empty string");
+ }
+ Iif (!address.startsWith("G")) {
+ throw new ILNError.InvalidAddress(
+ `Invalid Stellar address "${address}": must start with "G"`
+ );
+ }
+ Iif (address.length !== G_ADDRESS_LENGTH) {
+ throw new ILNError.InvalidAddress(
+ `Invalid Stellar address "${address}": must be ${G_ADDRESS_LENGTH} characters`
+ );
+ }
+}
+
+/**
+ * Validate a Soroban contract (C…) address.
+ *
+ * @param contractId - The contract ID to validate
+ * @throws {ILNError.InvalidAddress} If the contract ID is malformed.
+ */
+export function validateContractId(contractId: string): void {
+ Iif (typeof contractId !== "string" || contractId.length === 0) {
+ throw new ILNError.InvalidAddress("Contract ID must be a non-empty string");
+ }
+ Iif (!contractId.startsWith("C") || contractId.length !== C_ADDRESS_LENGTH) {
+ throw new ILNError.InvalidAddress(
+ `Invalid contract ID "${contractId}": must start with "C" and be ${C_ADDRESS_LENGTH} characters`
+ );
+ }
+}
+
+/**
+ * Validate a token amount against a minimum and the token's precision.
+ *
+ * @param amount - The amount in token base units
+ * @param min - The minimum allowed amount (inclusive) in base units
+ * @param token - The token the amount is denominated in
+ * @throws {ILNError.InvalidAmount} If the amount is not a positive integer, is
+ * below the minimum, or exceeds the token's precision.
+ */
+export function validateAmount(
+ amount: bigint,
+ min: bigint,
+ token: SupportedToken
+): void {
+ Iif (typeof amount !== "bigint") {
+ throw new ILNError.InvalidAmount("Amount must be a bigint (token base units)");
+ }
+ Iif (amount <= 0n) {
+ throw new ILNError.InvalidAmount("Amount must be greater than 0");
+ }
+ Iif (amount < min) {
+ throw new ILNError.InvalidAmount(
+ `Amount ${amount} is below the minimum of ${min} for ${token}`
+ );
+ }
+ // Precision guard: amounts are integers in base units, so a negative or
+ // unknown decimal config is the only way this can be violated. We surface
+ // unsupported tokens explicitly to avoid silent mis-scaling.
+ const decimals = TOKEN_DECIMALS[token];
+ Iif (decimals === undefined && !token.startsWith("C")) {
+ throw new ILNError.InvalidAmount(
+ `Unknown token "${token}": cannot verify amount precision`
+ );
+ }
+}
+
+/**
+ * Validate a discount rate.
+ *
+ * @param rate - Discount rate in basis points (1–5000)
+ * @throws {ILNError.InvalidDiscountRate} If the rate is outside the 1–5000 bps range.
+ */
+export function validateDiscountRate(rate: number): void {
+ Iif (!Number.isInteger(rate)) {
+ throw new ILNError.InvalidDiscountRate("Discount rate must be an integer (bps)");
+ }
+ Iif (rate < MIN_DISCOUNT_BPS || rate > MAX_DISCOUNT_BPS) {
+ throw new ILNError.InvalidDiscountRate(
+ `Discount rate must be between ${MIN_DISCOUNT_BPS} and ${MAX_DISCOUNT_BPS} bps`
+ );
+ }
+}
+
+/**
+ * Validate an invoice due date.
+ *
+ * @param date - The due date
+ * @throws {ILNError.InvalidDueDate} If the date is invalid.
+ * @throws {ILNError.DueDateTooSoon} If the date is less than 24h from now.
+ * @throws {ILNError.DueDateTooFar} If the date is more than 365 days from now.
+ */
+export function validateDueDate(date: Date): void {
+ Iif (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+ throw new ILNError.InvalidDueDate("Due date must be a valid Date");
+ }
+ const delta = date.getTime() - Date.now();
+ Iif (delta < MIN_DUE_DATE_MS) {
+ throw new ILNError.DueDateTooSoon("Due date must be at least 24 hours from now");
+ }
+ Iif (delta > MAX_DUE_DATE_MS) {
+ throw new ILNError.DueDateTooFar("Due date must be within 365 days from now");
+ }
+}
+ |