Skip to content

DeFi SDK

arkonix-defi-sdk is the internal protocol-integration layer of the execution engine: a pure Python library that turns a strategist's intent ("allow supplying USDC to Aave V3 on Base") into the two artifacts the execution stack runs on — ready-to-sign transactions and the Merkle policy leaves that constrain them.

Internal component — not for external integration

Unlike the Vault SDK, the DeFi SDK is not a public product. It is documented here so integrators and reviewers understand the execution path; if you are building on ARKONIX, the Vault SDK and the public API are your integration surfaces.

What it is

For every supported protocol action, the SDK produces two things:

  1. Ready-to-sign transactions — transaction requests carrying ABI-encoded calldata for one specific smart-contract function. The SDK never touches private keys; signing and broadcasting belong to the execution platform's KMS/HSM layer.
  2. Merkle policy leaves — the authorization records the backend hashes into the Merkle tree installed on the on-chain proof manager, the "execution arm" that actually moves funds. The proof manager verifies every call it makes against a Merkle proof: a call with no matching leaf cannot be proven and cannot execute.

Because the same codebase defines both the leaf-packing rules and the signatures from which the on-chain calldata decoders are generated, the SDK is the single source of truth for what the execution arm is allowed to do. How that authority is constrained — the leaf system, the escrow discipline, the validation gates — is the subject of Execution Safety Design.

Supported protocols at a glance

Protocol Category Execution capabilities
Aave V3 (and forks: Prime, Lido, Horizon, SparkLend, ZeroLend, HyperLend) Lending Supply, withdraw, borrow, repay, collateral toggles, E-Mode
Morpho Blue Lending Supply/withdraw collateral, borrow, repay, scoped operator authorization
Pendle V4 Yield (PT swaps) Swap token for PT and back
Enso Leverage loops Leverage and delever bundles (Pendle PT + Morpho)
Odos DEX aggregation Swaps
OKX DEX DEX aggregation Swaps
1inch V6 DEX aggregation Swaps (aggregation and Uniswap V3 routes)
PancakeSwap V3 DEX Single-pool swaps
Circle CCTP v2 Bridging Burn-and-mint USDC bridging, attestation handling
Centrifuge vaults (ERC-7540) Vaults Sync/async deposits, redemption requests and claims
Hyperliquid Perps / spot Deposits, perp and spot orders, cancels, transfers (HyperCore precompile)
apyUSD Yield vault (ERC-4626) Deposit, redeem, multi-leg entry from USDC
USDi Yield token Deposit, withdraw
Arkonix-native Escrow Return assets from the execution manager to pool escrow

Chains covered by the action model: Ethereum, Arbitrum, Optimism, Base, Polygon, Avalanche, BSC, HyperCore, and HyperEVM — with per-protocol address maps extending to further networks (Linea, Sonic, Ink, Plasma and others).

Three abstraction levels

The SDK is organized into three layers, each one feeding the next:

  1. Actions — the atomic unit. Each action maps 1:1 to one smart-contract function and knows its target address, calldata encoding, native value, required token approvals, and — critically — how to expand a strategist's selection into Merkle policy leaves. An action's identity (canonical Solidity signature, pinned 4-byte selector, parameter shapes, escrow behavior) lives in a frozen metadata record; calldata encoders recompute the selector from the canonical signature at build time, so a stored selector that drifts from its signature fails immediately.
  2. Flows — ordered multi-call sequences that wrap a single action's transaction in escrow discipline: funds are withdrawn from pool escrow only for the duration of the verified call sequence and swept back at the end. Every call a flow emits carries a canonical function signature that must match a policy leaf. See the escrow-flow discipline.
  3. Policies / leaves — the on-chain constraint set. The backend hashes SDK-produced leaves into the Merkle tree that the proof manager enforces on every call.

The actions layer and the registry

The action registry is the backend's single entry point into the SDK. At load time it walks the protocol packages and indexes every action class by protocol and name — adding a new protocol module auto-registers it, with no manual wiring, a property pinned by dedicated tests.

Through the registry the backend can:

  • enumerate protocols and their actions, and look any action up by name;
  • read each protocol's deployment manifest (the "Protocol Twin"): contract addresses per chain, asset symbols, and decoder addresses;
  • resolve the system contract addresses an action needs (manifest defaults, with database overrides winning) — unresolvable parameters raise a descriptive error rather than producing a malformed call;
  • obtain each protocol's configuration schema — the merged declaration of what a strategist may configure (token symbols, markets, vaults), which drives the policy-configuration UI;
  • run the leaf lifecycle: expand a strategist selection into policy leaves, and reverse-map an installed tree back into a reviewable selection;
  • export the canonical function signatures from which the on-chain decoder contracts are generated — closing the loop between the SDK's signatures and on-chain verification.

This uniform, enumerable action model is also what backs the Discovery API: the protocol and action catalog it serves is enriched with live probes of this SDK, so what the API advertises reflects what execution can actually do.

Where it sits in a rebalance

target allocation (strategy / SignalForge signal)
        │
        ▼
DeFi SDK ── intent → action calldata (per protocol)
        │           + Merkle policy leaves (per strategist policy)
        ▼
escrow-bracketed call sequence (withdraw → approve → act → sweep)
        │
        ▼
policy pre-flight ─▶ simulation ─▶ HSM signing ─▶ proof-verified
                                                  on-chain execution

The SDK constructs transactions and policy leaves; it does not hold keys, does not estimate gas, and does not talk to the platform database. Signing happens in the execution platform's KMS/HSM layer, and every execution passes policy verification and simulation first — see Execution & Strategy Layer for the full pipeline and Custody & Key Management for the signing model.