> For the complete documentation index, see [llms.txt](https://docs.trilobyte.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilobyte.finance/technical-documentation/typescript-sdk.md).

# TypeScript SDK

Trilobyte provides auto-generated TypeScript client bindings for all **five** contracts. These enable frontend applications, backend services, and keeper bots to interact with the protocol.

## Packages

| Package                               | Path                                    | Description                                                                |
| ------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------- |
| `@trilobyte/globals-client`           | `contracts/globals/bindings/`           | Settings, roles, collateral, fees, asset whitelist, Factory/vault registry |
| `@trilobyte/vault-client`             | `contracts/vault/bindings/`             | Full vault lifecycle, payments, yield, debt tokens, SEP-41                 |
| `@trilobyte/factory-client`           | `contracts/factory/bindings/`           | Vault creation, registry queries (incl. pagination)                        |
| `@trilobyte/timelock-client`          | `contracts/timelock/bindings/`          | Schedule, execute, cancel operations, AccessControl                        |
| `@trilobyte/collateral-escrow-client` | `contracts/collateral-escrow/bindings/` | Borrower-collateral lock / release / seize, pledge queries                 |

## Generation

Bindings are generated using the Stellar CLI:

```bash
# Generate all bindings (build WASM + generate + compile)
./scripts/generate-bindings.sh
```

This runs `stellar contract bindings typescript` for each contract, generating fully typed TypeScript clients from the contract ABIs.

## Usage

### Installation

Add bindings as local path dependencies in your project's `package.json`:

```json
{
  "dependencies": {
    "@trilobyte/globals-client": "file:../trilobyte-new/contracts/globals/bindings",
    "@trilobyte/vault-client": "file:../trilobyte-new/contracts/vault/bindings",
    "@trilobyte/factory-client": "file:../trilobyte-new/contracts/factory/bindings",
    "@trilobyte/timelock-client": "file:../trilobyte-new/contracts/timelock/bindings",
    "@trilobyte/collateral-escrow-client": "file:../trilobyte-new/contracts/collateral-escrow/bindings"
  }
}
```

### Example: Query Vault Config

```typescript
import { Client as VaultClient } from '@trilobyte/vault-client';

const vault = new VaultClient({
  contractId: 'CABC...',
  networkPassphrase: 'Test SDF Network ; September 2015',
  rpcUrl: 'https://soroban-testnet.stellar.org',
});

const config = await vault.get_config();
console.log('Phase:', config.result.phase);

// `outstanding` is NOT a field on VaultConfig — query it separately:
const outstanding = await vault.get_outstanding();
console.log('Outstanding:', outstanding.result);
```

### Example: Deposit into a Vault

```typescript
const tx = await vault.deposit({
  investor: 'GABC...',
  amount: 100_000_0000000n, // 100,000 with 7 decimals
});

await tx.signAndSend();
```

### Example: Create a Vault

`create_vault` takes the full 15-field `VaultParams`. For a manager-collateral-only loan, leave `collateral_escrow` (and the related fields) empty:

```typescript
import { Client as FactoryClient } from '@trilobyte/factory-client';

const factory = new FactoryClient({
  contractId: 'CDEF...',
  networkPassphrase: 'Test SDF Network ; September 2015',
  rpcUrl: 'https://soroban-testnet.stellar.org',
});

const tx = await factory.create_vault({
  params: {
    manager: 'GABC...',
    borrower: 'GDEF...',
    lent_token: 'CGHI...',
    principal: 500_000_0000000n,
    interest_rate: 1000, // 10%
    loan_term: 12,
    split_ratio: 80,
    permissioned: false,
    grace_period: 2592000n,
    funding_deadline: 0n,
    approval_deadline: 0n,
    // Borrower collateral (optional). For a manager-collateral-only loan:
    collateral_escrow: undefined,   // Option<Address> → None
    collateral_token: undefined,    // Option<Address> → None
    collateral_recovery: undefined, // Option<Address> → None
    collateral_min: 0n,
  },
  salt: Buffer.from('unique-salt-value-32-bytes......'), // 32 bytes
});

await tx.signAndSend();
```

For a **borrower-collateral-backed** loan, set `collateral_escrow` to the escrow contract address, `collateral_token` to the pledged asset, `collateral_recovery` to the recovery party, and `collateral_min` to the on-chain floor — then have the borrower `lock` the pledge in the escrow and pass its `pledge_id` to `approve_and_disburse`.

## Keeper / Cron Integration

The TypeScript bindings are consumed by the `trilobyte-vault` NestJS backend. The keeper cron module uses them to:

1. **`apply_late_fee()`** — when a payment is overdue (manager-only)
2. **`check_default()`** — when past the grace period (permissionless)
3. **`check_funding_expiry()`** — for funding-deadline enforcement (permissionless)
4. **`check_approval_expiry()`** — for approval-deadline enforcement (permissionless)

All except `apply_late_fee` are permissionless entry points callable by any address.