ATFi SDK

TypeScript SDK for interacting with ATFi commitment vaults on Base. Stake tokens, verify attendance, earn rewards.


Features

- Simulation-first - Know results before wallet popup
- Transaction callbacks - Loading states for UX
- Read-only mode - Show data before wallet connection
- User-centric queries - Dashboard, registered events, claimable rewards
- Real-time watching - Subscribe to live vault events
- TypeScript - Full type safety

Installation

``bash
npm install atfi viem
`

Quick Start

`typescript
import { ATFiSDK } from 'atfi';
import { createPublicClient, createWalletClient, http, custom } from 'viem';
import { base } from 'viem/chains';

// Setup clients
const publicClient = createPublicClient({
chain: base,
transport: http(),
});

const walletClient = createWalletClient({
chain: base,
transport: custom(window.ethereum),
});

// Initialize SDK
const sdk = new ATFiSDK(publicClient, walletClient);
`

How It Works

Every write function returns { simulation, execute() } - one call gives you everything:

`typescript
const action = await sdk.register({ vaultAddress: '0x...' });

// 1. Check simulation result (NO wallet popup yet!)
if (!action.simulation.success) {
console.error(action.simulation.error.message);
return;
}

// 2. Show user what will happen
console.log(Stake: ${action.simulation.stakeAmount} ${action.simulation.tokenSymbol});
console.log(Your balance: ${action.simulation.userBalance});
console.log(Gas estimate: ${action.simulation.gasEstimate});

// 3. User confirms → execute with loading callbacks
const result = await action.execute({
onApproving: () => setStatus('Approving token...'),
onApproved: (hash) => setStatus('Token approved!'),
onSubmitting: () => setStatus('Submitting...'),
onSubmitted: (hash) => setStatus(TX: ${hash}),
onConfirming: () => setStatus('Confirming...'),
});
console.log('Done!', result.txHash);
`

---

Read-Only Mode

Show data before user connects wallet:

`typescript
import { ATFiSDK } from 'atfi';
import { createPublicClient, http } from 'viem';
import { base } from 'viem/chains';

// No wallet needed!
const publicClient = createPublicClient({
chain: base,
transport: http(),
});

const sdk = ATFiSDK.readOnly(publicClient);

// All read functions work
const events = await sdk.getAllEvents();
const info = await sdk.getEventInfo('0x...');

// Write functions throw helpful error
await sdk.register({ vaultAddress: '0x...' });
// Error: "SDK is in read-only mode. Initialize with a walletClient to perform write operations."
`

---

API Reference

$3

`typescript
const action = await sdk.createEvent({
stakeAmount: '10', // 10 USDC
maxParticipants: 50,
useYield: true, // Enable Morpho yield
token: 'USDC', // 'USDC' or 'IDRX'
});

if (action.simulation.success) {
console.log('Expected vault ID:', action.simulation.expectedVaultId);
console.log('Token:', action.simulation.token.symbol);
console.log('Gas:', action.simulation.gasEstimate);

const result = await action.execute({
onSubmitting: () => showLoader('Creating event...'),
onConfirming: () => showLoader('Confirming...'),
});
console.log('Created:', result.vaultAddress);
}
`

Simulation returns:
| Field | Type | Description |
|-------|------|-------------|
| expectedVaultId | bigint | Next vault ID |
| token | object | { address, symbol, decimals } |
| stakeAmount | string | Human readable stake |
| maxParticipants | number | Max allowed |
| useYield | boolean | Yield enabled |
| gasEstimate | bigint | Estimated gas |

---

$3

`typescript
const action = await sdk.register({ vaultAddress: '0x...' });

if (action.simulation.success) {
console.log(Stake: ${action.simulation.stakeAmount} ${action.simulation.tokenSymbol});
console.log(Your balance: ${action.simulation.userBalance});
console.log(Needs approval: ${action.simulation.needsApproval});
console.log(Spots left: ${action.simulation.maxParticipants - action.simulation.currentParticipants});

// Callbacks for loading states (approval + stake transaction)
const result = await action.execute({
onApproving: () => showLoader('Approving USDC...'),
onApproved: (hash) => showToast(Approved! ${hash}),
onSubmitting: () => showLoader('Staking...'),
onConfirming: () => showLoader('Confirming...'),
});
}
`

Simulation returns:
| Field | Type | Description |
|-------|------|-------------|
| stakeAmount | string | Amount to stake |
| tokenSymbol | string | USDC or IDRX |
| userBalance | string | Your token balance |
| currentAllowance | string | Current approval |
| needsApproval | boolean | Need approve TX first |
| currentParticipants | number | Current count |
| maxParticipants | number | Max allowed |

---

$3

`typescript
const action = await sdk.startEvent({ vaultAddress: '0x...' });

if (action.simulation.success) {
console.log(Total staked: ${action.simulation.totalStaked});
console.log(Participants: ${action.simulation.participantCount});
console.log(Has yield: ${action.simulation.hasYield});

const result = await action.execute();
}
`

---

$3

`typescript
const action = await sdk.verifyParticipant({
vaultAddress: '0x...',
participants: ['0xAddr1', '0xAddr2', '0xAddr3'],
});

if (action.simulation.success) {
console.log(Will verify: ${action.simulation.toVerify.length});
console.log(Already verified: ${action.simulation.alreadyVerified.length});
console.log(Not staked: ${action.simulation.notStaked.length});

const result = await action.execute();
}
`

Simulation returns:
| Field | Type | Description |
|-------|------|-------------|
| toVerify | Address[] | Will be verified |
| alreadyVerified | Address[] | Already done |
| notStaked | Address[] | Not registered (will fail) |
| currentVerified | number | Current count |
| newVerifiedCount | number | Count after |

---

$3

`typescript
const action = await sdk.settleEvent({ vaultAddress: '0x...' });

if (action.simulation.success) {
console.log(Verified: ${action.simulation.verifiedCount});
console.log(No-shows: ${action.simulation.noShowCount});
console.log(Yield earned: ${action.simulation.estimatedYield});
console.log(Protocol fees: ${action.simulation.estimatedProtocolFees});
console.log(Reward per attendee: ${action.simulation.estimatedRewardPerParticipant});

const result = await action.execute();
}
`

Simulation returns:
| Field | Type | Description |
|-------|------|-------------|
| totalStaked | string | Total staked |
| verifiedCount | number | Attendees |
| noShowCount | number | No-shows |
| estimatedYield | string | Yield earned |
| estimatedProtocolFees | string | Protocol fees |
| estimatedNoShowFees | string | No-show fees |
| estimatedRewardPerParticipant | string | Reward each |

---

$3

`typescript
const action = await sdk.claim({ vaultAddress: '0x...' });

if (action.simulation.success) {
console.log(Total: ${action.simulation.claimableAmount} ${action.simulation.tokenSymbol});
console.log(Your stake: ${action.simulation.stakeAmount});
console.log(Bonus: ${action.simulation.bonusShare});

const result = await action.execute();
}
`

Simulation returns:
| Field | Type | Description |
|-------|------|-------------|
| claimableAmount | string | Total to claim |
| tokenSymbol | string | Token symbol |
| stakeAmount | string | Original stake |
| bonusShare | string | Bonus from no-shows + yield |

---

Read Functions

`typescript
// Get event details
const info = await sdk.getEventInfo('0xVaultAddress');

// Get participant status
const status = await sdk.getParticipantStatus('0xVault', '0xParticipant');

// Get all events (batched for performance)
const events = await sdk.getAllEvents();

// Get vault by ID
const vault = await sdk.getVaultAddress(1);
`

---

Token Balance Helpers

`typescript
// Get single token balance
const usdcBalance = await sdk.getTokenBalance('0xUserAddress', 'USDC');
console.log(USDC: ${usdcBalance}); // "125.50"

// Get all supported token balances
const balances = await sdk.getAllTokenBalances('0xUserAddress');
console.log(balances);
// { USDC: "125.50", IDRX: "1000000.00" }
`

---

User-Centric Queries

Get events filtered by user:

`typescript
// Events created by user
const myEvents = await sdk.getEventsByOwner('0xUserAddress');

// Events user registered for
const registered = await sdk.getRegisteredEvents('0xUserAddress');

// Events with unclaimed rewards
const claimable = await sdk.getClaimableEvents('0xUserAddress');

// Complete dashboard data (all in one call)
const dashboard = await sdk.getUserDashboard('0xUserAddress');
console.log(dashboard);
// {
// asOrganizer: [...], // Events user created
// asParticipant: [...], // Events user joined
// claimable: [...], // Ready to claim
// balances: { USDC: "125.50", IDRX: "1000000.00" }
// }
`

---

Transaction Callbacks

All write functions accept callbacks for loading states:

`typescript
interface TransactionCallbacks {
onApproving?: () => void; // Starting token approval
onApproved?: (txHash: Hash) => void; // Approval submitted
onSubmitting?: () => void; // Starting main transaction
onSubmitted?: (txHash: Hash) => void; // Transaction submitted
onConfirming?: () => void; // Waiting for confirmation
}

// Example: Full loading state management
const result = await action.execute({
onApproving: () => {
setStatus('approving');
setMessage('Please approve token in wallet...');
},
onApproved: (hash) => {
setMessage(Approved! TX: ${hash.slice(0, 10)}...);
},
onSubmitting: () => {
setStatus('submitting');
setMessage('Please confirm transaction in wallet...');
},
onSubmitted: (hash) => {
setMessage(Submitted! TX: ${hash.slice(0, 10)}...);
setTxHash(hash);
},
onConfirming: () => {
setStatus('confirming');
setMessage('Waiting for blockchain confirmation...');
},
});
setStatus('success');
`

---

Real-Time Event Watching

Subscribe to vault events for live UI updates:

`typescript
const unwatch = sdk.watchVault('0xVaultAddress', {
onParticipantJoined: (address, total) => {
console.log(${address} joined! Total: ${total});
updateParticipantList();
},
onParticipantVerified: (address, totalVerified) => {
console.log(${address} verified!);
updateVerifiedCount(totalVerified);
},
onSettled: (totalYield, protocolFee) => {
console.log(Event settled! Yield: ${totalYield});
showClaimButton();
},
onClaimed: (address, amount) => {
console.log(${address} claimed ${amount});
},
onStakingStatusChanged: (isOpen) => {
updateRegistrationStatus(isOpen);
},
onError: (error) => {
console.error('Watch error:', error);
},
});

// Stop watching when done
unwatch();
`

---

Error Handling

Errors are returned in simulation, not thrown:

`typescript
const action = await sdk.register({ vaultAddress: '0x...' });

if (!action.simulation.success) {
switch (action.simulation.error.code) {
case 'STAKING_CLOSED':
showMessage('Registration ended');
break;
case 'ALREADY_STAKED':
showMessage('Already registered');
break;
case 'INSUFFICIENT_BALANCE':
showMessage(Need ${action.simulation.stakeAmount} ${action.simulation.tokenSymbol});
break;
case 'MAX_PARTICIPANTS_REACHED':
showMessage('Event is full');
break;
default:
showMessage(action.simulation.error.message);
}
return;
}
`

Error Codes:
- STAKING_CLOSED - Registration ended
- ALREADY_STAKED - Already registered
- INSUFFICIENT_BALANCE - Not enough tokens
- MAX_PARTICIPANTS_REACHED - Event full
- NOT_OWNER - Not event owner
- EVENT_ALREADY_STARTED - Already started
- VAULT_ALREADY_SETTLED - Already settled
- VAULT_NOT_SETTLED - Not settled yet
- NOT_VERIFIED - Not verified for attendance
- ALREADY_CLAIMED - Already claimed

---

Supported Tokens

| Token | Address | Decimals | Yield |
|-------|---------|----------|-------|
| USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 6 | Yes |
| IDRX | 0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22 | 2 | No |

Contract Addresses (Base Mainnet)

| Contract | Address |
|----------|---------|
| FactoryATFi | 0x0be05a5fa7116c1b33f2b0036eb0d9690db9075f |
| Morpho Vault | 0x050cE30b927Da55177A4914EC73480238BAD56f0` |

License

MIT