> 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.


---

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

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

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

```
GET https://docs.trilobyte.finance/technical-documentation/typescript-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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