Open-source building blocks for DeFi position analysis and EVM infrastructure, including protocol integrations and reusable blockchain utilities.
Developed as part of DeFine, a DeFi risk observability and early warning system.
| Package | Description | Status |
|---|---|---|
@define-kit/position-modules |
Protocol-specific modules for fetching, snapshotting, and evaluating DeFi positions | Active development |
@define-kit/utilities |
Reusable utilities, currently including RPC endpoint health checks | Active development |
More packages will be added only when reusable functionality has a clear independent responsibility.
Position modules follow one execution flow:
fetch protocol state
↓
build a snapshot
↓
evaluate the snapshot
↓
return { snapshot, result }
This separates reusable protocol logic from application runtime concerns.
The toolkit owns:
- protocol-facing reads;
- explicit snapshot shapes;
- deterministic snapshot evaluation;
- typed module results.
The consuming application owns:
- scheduling and refresh orchestration;
- persistence and historical state;
- previous-versus-current comparison;
- alert thresholds and notification delivery;
- RPC endpoint management;
- user interfaces and framework integration.
@define-kit/position-modules currently includes:
- shared contracts for position modules;
- an Aave V3 health-factor adapter;
- Aave V3 supplied-asset and variable-debt reads;
- health-factor result formatting;
- a maturity-date scaffold that explicitly returns
not_implemented.
The Aave V3 adapter reads protocol contracts with viem and uses the health factor returned by Aave's getUserAccountData call. It does not accept externally supplied prices or reconstruct the health factor independently.
@define-kit/utilities currently includes RpcHealthCheck, which:
- validates an RPC endpoint against an expected chain ID;
- checks block-number availability and measures latency;
- reports whether
eth_callappears to be available; - supports metadata passthrough and concurrency-limited batch checks.
Install the published package you need:
npm install @define-kit/position-modules
npm install @define-kit/utilitiesSee the package READMEs for usage and API details:
This repository uses Yarn, Nx, TypeScript, Vitest, and tsdown.
Use yarn nx:g ... for Nx generators. Nx 23.1.0 misreads patched eslint in package.json, while the wrapper temporarily unwraps patched dependencies and restores them after generation.
# Install dependencies
yarn install
# Build all projects
yarn nx run-many -t build
# Run tests
yarn nx run-many -t test
# Run type checking
yarn nx run-many -t typecheck
# Run linting
yarn nx run-many -t lintTo validate one package:
yarn nx build position-modules
yarn nx test position-modules
yarn nx build utilities
yarn nx test utilitiesModules obtain authoritative state from protocol contracts instead of application databases or externally supplied derived values.
Fetched data is normalized into explicit snapshots that can be stored, compared, and evaluated again.
Evaluation receives a snapshot and returns a result. It should not perform network requests, persistence, scheduling, or notification delivery.
Public packages do not depend on backend frameworks, database models, or application-owned runtime state.
Incomplete adapters return an explicit state such as not_implemented rather than producing a misleading partial result.
The public API is still being developed and may change before version 1.0.0. Pin an exact package version when integrating it into production-sensitive software.
The current modules read public blockchain state and do not require private keys or signing credentials.
Never provide a private key or seed phrase to a position module. Consumers are responsible for validating chain IDs, protocol deployments, contract addresses, and RPC endpoints before relying on returned data.
MIT