Ionava Integration Library

TypeScript library for interacting with the Ionava Care Cash smart contract using ethers v6. It provides a focused, typed API for common protocol operations while handling nonces and revert decoding for better developer ergonomics.

Requirements

• Node.js 18+
• Environment variables (for the example runner and typical usage):
  • PROVIDER_RPC_URL: JSON-RPC endpoint
  • IONAVA_CARE_CASH_CONTRACT_ADDRESS: Deployed contract address
  • CARE_CASH_MANAGER_PRIVATE_KEY: EOA for care cash manager actions
  • VAULT_MANAGER_PRIVATE_KEY (optional if same as manager): EOA for vault actions

You can also run the example with a single signer by reusing one private key for both roles.

Important security and nonce guidance

• Do not use the manager private keys manually outside of this library. If you need to perform transactions outside of this code path, use a different key with the same role (e.g., send via a Gnosis Safe or another EOA). Mixing manual sends can cause nonce collisions and failed transactions.
• This library allocates nonces using the pending count and an internal per-address counter, then passes explicit nonces in overrides for each write call. External sends from the same address can still interfere.

Installation in another package

Install from npm:

npm install ionavaintegrationlib 

Build from source (for contributors):

npm install
npm run build

Usage

import { ethers } from "ethers";
import { IonavaIntegrationLib } from "ionavaintegrationlib";

const provider = new ethers.JsonRpcProvider(process.env.PROVIDER_RPC_URL!);
const careCashManager = new ethers.Wallet(process.env.CARE_CASH_MANAGER_PRIVATE_KEY!, provider);
const vaultManager = new ethers.Wallet((process.env.VAULT_MANAGER_PRIVATE_KEY ?? process.env.CARE_CASH_MANAGER_PRIVATE_KEY)!, provider);

const ionava = new IonavaIntegrationLib({
  providerRpcUrl: process.env.PROVIDER_RPC_URL!,
  ionavaCareCashContractAddress: process.env.IONAVA_CARE_CASH_CONTRACT_ADDRESS!,
  careCashManagerSigner: careCashManager,
  vaultManagerSigner: vaultManager
});

// Read example
const info = await ionava.getAllUserInfo("0x...user");

// Write example
const tx = await ionava.addRewards("0x...user", 12345n);
await tx.wait();

Exposed API

Constructor options:

• providerRpcUrl: string
• ionavaCareCashContractAddress: string
• careCashManagerSigner: ethers.Wallet
• vaultManagerSigner: ethers.Wallet

Read-only methods:

• getCareCashBalance(user: string): Promise<bigint>
• getAllUserInfo(user: string): Promise<UserInfo>
• getTotalInterestAccrued(): Promise<bigint>
• totalCareCashSupply(): Promise<bigint>
• totalVaultSupply(): Promise<bigint>
• vaultUsageDelay(): Promise<bigint>
• paused(): Promise<boolean>
• interestRateBoost(): Promise<bigint>
• interestRateKickInDuration(): Promise<bigint>
• maxHealthQuotient(): Promise<bigint>
• minHealthQuotient(): Promise<bigint>
• getETHBalanceOfAddress(address: string): Promise<bigint>

Write methods (nonces handled internally, explicit overrides applied):

• onboardUser(user: string)
• offBoardUserInDefault(user: string)
• addCareCash(user: string, amount: bigint)
• useCareCash(user: string, amount: bigint, infoString: string)
• addRewards(user: string, amount: bigint)
• batchUpdateUserBalances(users: string[])
• setUserInArrears(user: string, userInArrears: boolean)
• setUserInDefault(user: string, userInDefault: boolean)
• setVaultBalance(user: string, amount: bigint) (uses the vault manager signer)
• updateHealthQuotient(user: string, newHealthQuotient: bigint)

Write methods return transaction info, including the transaction hash.

Error handling:

• Custom Solidity errors are decoded via the contract interface. The library throws SmartContractRevert with the error name and args when revert data is available. If it is not a smart contract error, throws more generic error.

Not exposed (admin/UUPS/config)

Admin and upgrade functions are intentionally not wrapped by this library:

• Roles/admin: grantRole, revokeRole, renounceRole, hasRole, getRoleAdmin
• Pausing/config: togglePause, setInterestRateBoost, setInterestRateKickInDuration, setVaultUsageDelay
• UUPS/utilities: upgradeToAndCall, proxiableUUID, initialize, supportsInterface
• Internal helpers: updateUserBalance, updateMyBalance, etc.

If you need these, prefer executing them via a controlled admin (e.g., Gnosis Safe) and/or add a separate admin-only module with appropriate safety checks.

Example runner

This repo includes a simple runner used during development:

npm run dev:example

It reads the environment variables above and demonstrates basic interactions. Do not run this against mainnet with real keys unless you understand the implications. Recomended to try the example using Forge/Anvil.

License

ISC