Aegis SDK

The official TypeScript SDK for the Aegis RWA Protocol. This library provides a clean, class-based interface to interact with Aegis Soroban smart contracts on the Stellar network.

Installation

npm install @aegis/sdk

Quickstart

Use the role-aware factory to construct a client with explicit capability intent. The returned object only exposes modules and operations that are appropriate for the declared role.

import {
  createReadOnlyClient,
  createInvestorClient,
  createIssuerClient,
  createAdminClient,
} from '@aegis/sdk';
import { Keypair } from '@stellar/stellar-sdk';

// Read-only — no keypair needed. Suitable for dashboards and indexers.
const reader = createReadOnlyClient({
  environment: 'testnet',
  contractId: 'C_YOUR_CONTRACT_ID',
});
const isApproved = await reader.compliance.checkWhitelist('G_USER_PUBLIC_KEY');
const portfolio  = await reader.investor.getPortfolio('G_USER_PUBLIC_KEY');

// Investor — keypair required. Transfer capability only.
const investor = createInvestorClient({
  environment: 'testnet',
  contractId: 'C_YOUR_CONTRACT_ID',
  keypair: Keypair.fromSecret('S_INVESTOR_SECRET'),
});
await investor.asset.transfer('G_RECIPIENT', 100);

// Issuer — keypair required. Adds asset minting.
const issuer = createIssuerClient({
  environment: 'testnet',
  contractId: 'C_YOUR_CONTRACT_ID',
  keypair: Keypair.fromSecret('S_ISSUER_SECRET'),
});
await issuer.asset.mint('G_INVESTOR', 5000);

// Admin — keypair required. Full access.
const admin = createAdminClient({
  environment: 'testnet',
  contractId: 'C_YOUR_CONTRACT_ID',
  keypair: Keypair.fromSecret('S_ADMIN_SECRET'),
});
admin.assertAdminAccess(); // explicit guard before privileged call
await admin.asset.mint('G_INVESTOR', 10000);

See Role-Aware Client Factory for the full capability matrix, compliance-operator usage, error handling, and security notes.

For direct AegisClient construction (advanced / custom setups):

import { AegisClient } from '@aegis/sdk';

const aegis = new AegisClient({
  environment: 'testnet',
  contractId: 'C_YOUR_CONTRACT_ID',
  keypair: Keypair.fromSecret('S...'), // optional for read-only
});

Role Discovery & Capability Checks

Check what an address is classified as, and what it can currently attempt through the SDK. This is a client-side convenience for UI gating, not on-chain authorization — see the full documentation for important caveats.

const roleResult = await aegis.role.discoverRole('G_USER_PUBLIC_KEY');
console.log('Role:', roleResult.role); // 'investor' | 'unauthorized' | 'unknown'

const capability = await aegis.role.checkCapability('G_USER_PUBLIC_KEY', 'receive_transfer');
console.log('Can receive transfer?', capability.isPermitted);

Contract Event Decoder

Decode Soroban contract events into typed audit-trail models for dashboards and indexers.

import { decodeContractEvent } from '@aegis/sdk';

const event = decodeContractEvent({
  topic: rpcEvent.topic,
  value: rpcEvent.value,
  txHash: rpcEvent.txHash,
});

if (event.kind === 'transfer') {
  console.log(event.from, event.to, event.amount);
}

See Contract Event Decoder for supported topics, unknown fallback behaviour, and dashboard integration guidance.

Testing

To run the SDK unit tests locally:

npm run test

Run the full release gate, including TypeScript compilation and browser/Node runtime compatibility checks:

npm run check

Pre-submit verification

Run all checks (lint, format, build, test, compat) in a single command before submitting a PR:

npm run verify

See Test-First Contribution Guide for when behavior changes need happy-path, negative-path, and no-test justification coverage.

See Verification Command for detailed usage and troubleshooting guidance.

See Runtime Compatibility for the supported environments, what the automated probes cover, and integration guidance.

For step-by-step instructions on reproducing and fixing CI check failures, see the CI Resolution Workflow.

Contributing

We welcome contributions! Please check our CONTRIBUTING.md for our branching strategy and code style guidelines.

Before submitting a PR, follow our Test-First Contribution Guide to understand when tests are required, what type of tests are expected per module, and how to prove your change works correctly.

Review Process

PRs submitted to this repository are reviewed against our Pull Request Reviewer Checklist, which covers code implementation, unit test coverage, CI build compatibility, API reference documentation, security/compliance, and acceptance criteria.

Acceptance Criteria Traceability

Every PR must include an acceptance criteria traceability table that maps SDK modules, tests, docs, and behaviour verification to each acceptance criterion from the linked issue. This makes evaluation straightforward for maintainers and GrantFox reviewers.