There are 2 ways to query reporting data for Kiln DeFi:

1. Using Kiln Connect API (recommended): a simple REST API doing all aggregation for you

2. Using Kiln public TheGraph instances directly

Get a user position(s) and total rewards inside of Vault(s)

Route: GET /v1/defi/v1/stakes

Goals

• Get a list of positions inside a list of vaults

• Positions include current deposited balance and total rewards and withdrawn amounts

• This data can be used to showcase current holdings of a user in Kiln DeFi vaults

Query parameters

• wallets: comma-separated list of wallet address to fetch position data for

• vaults: comma-separated list of vaults, where each value has the protocol_address format

These are not exclusive and can be used together. Some use-cases could be:

• query all current positions of a vault or a list of vaults

• query all current positions of a user or a list of users

• query all current positions of a user or a list of users within a vault or a list of vaults

Specs: https://docs.api.mainnet.kiln.fi/preview.html#tag/defi/operation/getDefiStakes

Get Operations on a position

Route: GET /v1/defi/v1/operations

Goals

• Get all operations performed on a list of positions inside a list of vaults

• Operations include deposit and withdrawal operations

• This data can be used for accounting reconciliation

Query parameters

• wallets: comma-separated list of wallet address to fetch position data for

• vaults: comma-separated list of vaults, where each value has the protocol_address format

These are not exclusive and can be used together. Some use-cases could be:

• query all operations of positions on a vault or a list of vaults

• query all operations of positions of a user or a list of users

• query operations of positions of a user or a list of users within a vault or a list of vaults

Specs: https://docs.api.mainnet.kiln.fi/preview.html#tag/defi/operation/getDefiOperations

Get Statistics of a vault

Route: GET /v1/defi/v1/network-stats

Query parameters

• vaults: comma-separated list of vaults, where each value has the protocol_address format

Specs: https://docs.api.mainnet.kiln.fi/preview.html#tag/defi/operation/getDefiNetworkStats

Change the end user fee

FEE_MANAGER should be used to perform these actions.

Set the deposit fee

The deposit fee is taken at the time of deposit. You can set it by calling the setDepositFee(uint256 newDepositFee), where newDepositFee is a fixed amount of tokens deducted from each deposit.

Set the rewards fee

The rewards fee is computed as percentage of the rewards generated by the Vault as a whole. It can be set by callingsetRewardFee(uint256 newRewardFee), where newRewardFeeis denominated in basis points.

Change commission recipients

ADMIN should be used to perform these actions.

Set fee recipients

To set the recipients of the deposit and rewards fees, you can call the setFeeRecipients(FeeRecipient[] memory recipients) function where recipients is an array of the following structure:

struct FeeRecipient {
        address recipient;
        uint256 depositFeeSplit;
        uint256 rewardFeeSplit;
}

where:

• recipient is the address of the fee recipient

• depositFeeSplit is the share of the recipient on the deposit fee (in basis points)

• rewardFeeSplit is the share of the recipient on the performance fee (in basis points)

The sum of alldepositFeeSplit values and the sum of all rewardFeeSplit values in the struct must both equal 100 * 10^(decimal places of the token).

Vault administration (partner)

Vaults are managed by partners using several key admin roles:

• SYS_ADMIN: wallet responsible for contract administration and other role attribution

• FEE_MANAGER: wallet responsible for changing the end user fee and the split between multiple recipients

• FEE_COLLECTOR: wallet responsible for claiming the commission

• SANCTIONS_MANAGER: wallet responsible for enabling the OFAC-sanctioned wallet check

• CLAIM_MANAGER: wallet responsible for claiming additional rewards from the lending protocols

• PAUSER: wallet responsible for pausing all interaction with vault contracts, managed by Kiln as a security fail-safe

• UNPAUSER: wallet responsible for unpausing the contract

It is recommended to have multi-sig wallets for these roles with a strong quorum security.

NOTE: You can only have 1 wallet assigned as SYS_ADMIN, but multiple wallets assigned to all other roles.

Blocklist administration (partner)

Kiln DeFi vaults feature custom deposit blocklists that partners can opt to use. The blocklist admin role is:

• OPERATOR: wallet responsible for adding and removing addresses to and from the custom blocklist

Upgradability Structure (Kiln)

Kiln DeFi Vaults

Kiln DeFi vaults follow the beacon proxy pattern where all vaults fetch their implementation address from a VaultUpgradeableBeacon smart contract.

This is administered by 4 roles:

• PROXY_ADMIN: a multisig quorum between Kiln and third parties responsible for attributing the below roles

• PAUSER: a wallet responsible for pausing all interaction with vault contracts, managed by Kiln as a security failsafe

• FREEZER: a multisig quorum between Kiln and third parties responsible for freezing Vault implementation (to make it non-upgradeable)

• IMPLEMENTATION_MANAGER: a multisig quorum between Kiln and third parties responsible for upgrading Vault implementations

Kiln DeFi Connectors

Kiln DeFi Connectors also follow the beacon proxy pattern where each connector implementation address is fetched from a ConnectorRegistry contract.

This is administered by 4 roles:

• ADMIN: a multisig quorum between Kiln and third parties responsible for attributing the below roles

• PAUSER: a wallet responsible for pausing all interaction with connector contracts, managed by Kiln as a security failsafe

• FREEZER: a multisig quorum between Kiln and third parties responsible for freezing connector implementations (to make some of them non-upgradeable)

• CONNECTOR_MANAGER: a multisig quorum between Kiln and third parties responsible for upgrading connectors implementation

Kiln DeFi Vault smart contracts adhere to the ERC4626 standard, making integration straightforward. When users deposit tokens, they receive shares representing their position. For a better user experience, we recommend abstracting any asset-to-share conversions and always displaying asset amounts on the UI instead of share amounts.

Here is the ABI of the Vault contract:

1. Depositing

Before depositing 'x' assets, ensure the user has approved the vault to spend 'x' on their behalf via the asset contract.

• Check Allowance: Call the allowance(address owner, address spender) → uint256 function on the ERC20 asset contract.

• Increase Allowance: Use the approve(address spender, uint256 amount) → bool function on the ERC20 asset contract to increase the allowance to the desired deposit amount.

Before depositing X assets, you must make sure the user approved the vault to spend X on its behalf on the asset contract.

To deposit an amount of the vault's ERC20, the transaction sender must call the deposit(uint256 assets, address receiver) function, where assets is the amount of ERC20 to deposit in the strategy, and receiver is the address that should own the deposited position.

(Optional) If you need to compute the amount of shares the user will receive before making a deposit, you can preview the amount by calling previewDeposit(uint256 assets), where assets is the amount of ERC20 to deposit.

2. Get the balance in assets

curl https://api.kiln.fi/v1/defi/v1/stakes?users=$ADDRESS1&vaults=$VAULT1,$VAULT2 \
   -H "Authorization: Bearer $API_TOKEN"

200
{
  "stakes": [
    {
      "current_balance": 1880000,
      "asset": "0x94a9d9ac8a22534e3faca9f4e7f2e2cf85d5e4c8",
      "total_rewards": 42000,
      "asset_symbol": "USDC",
      "total_deposited_amount": 1980000,
      "total_withdrawn_amount": 100000,
      "vault": "0x9aB5F9101a3C1B868e2c422E294cc2ee685551D5",
      "chain": "ethereum"
    },
    {
      "current_balance": 1880000,
      "asset": "0x94a9d9ac8a22534e3faca9f4e7f2e2cf85d5e4c8",
      "total_rewards": 1330,
      "asset_symbol": "USDC",
      "total_deposited_amount": 1980000,
      "total_withdrawn_amount": 100000,
      "vault": "0x8aB6F9101a3C1B868e2c422E294cc2ee686662Ab",
      "chain": "ethereum"
    }
  ]
}

3. Exiting a position

Case 1: exit part of a position

In this case, we expect the user to input the amount of ERC20 they want to withdraw and then call the withdraw(uint256 assets, address receiver, address owner) function. Here:

• assets is the amount of ERC20 to withdraw.

• receiver is the address that will receive the redeemed ERC20.

• owner is the address of the position owner (the same as the transaction sender).

Case 2: exit a position fully

To exit the entire position, the best approach is to determine the user's share amount and redeem it. Follow these steps:

1. Retrieve the share amount of the user's position using the balanceOf(address owner) function, where owner is the address of the position owner.

2. Redeem the shares by calling the redeem(uint256 shares, address receiver, address owner) function, where:

   • shares is the amount of shares to redeem.

   • receiver is the address that will receive the redeemed ERC20.

   • owner is the address of the position owner (the same as the transaction sender).

Some DeFi protocols deploy incentives programs (like governance tokens distributions, airdrops etc.) for users depositing into their pools.

In the case of Kiln DeFi, user positions are aggregated on a Vault contract and then deposited to the underlying protocol, which makes the Vault be seen as one user by the underlying protocols.

Kiln DeFi is offering multiple additional rewards distribution models:

1. Claim; Allowing Kiln partners to claim all additional rewards received by their vaults, allowing partners to keep it from them or to redistribute it to users via protocols like Merkl.

2. Reinvest; Allowing Kiln partners to trigger a swap from the reward asset eg. COMP to the vault asset eg. USDC, it will boost the APY of the users you can do this a the frequency you prefer.

3. Direct user claim; Only available with Morpho, where are have a custom partnership so that users can directly claim morpho tokens.

Here is a list of the protocol distributing additional rewards on top of the base rewards of lending assets.

Detailed flow for each additional rewards distribution models

Claim and Reinvest (or none) must be specified in the Vault at its initialization in the deployment parameters.

1. Claim: integrator can trigger the claim of the extra-rewards which will make an ERC-20 transfer from the vault to the address specified in the claim transaction. This is useful if you want to redistribute this revenue to the users yourself or with a solution like Merkl. Please contact Kiln team if you are interested in this option.

1. Reinvest: you can emit an instruction to the vault to swap the ERC-20 additional-rewards to the Vault asset (ex: USDC for a USDC AAVE v3 vault) which will create a rewards bump for all users. This is very useful to not expose users to other tokens than the one they deposited, creating a simple and aggregated experience. You can perform this operation every end of month for example that can create an incentive for the user to wait for the "additional rewards boost" before withdrawing and make this product more sticky.

1. Direct user Claim: Direct user claim is only available with Morpho, and is not managed by the vault itself but by the morpho team. No action will be required on your end, Kiln is providing APIs to display theses rewards and know how much can be claimed by your users.

   1. Note that with morpho, rewards can be distirbuted in MORPHO token but also with other type of assets, and each asset type will need to be claimed individually by the user, you need to plan to add this in your UI if you are not using Kiln Widget.

How to perform these transactions?

Using the CLAIM_MANAGER_ROLE wallet, you can call the following function on the vault claimAdditionalRewards(address rewardsAsset, bytes calldata payload)where rewardsAsset is the address of the ERC20 token additional-rewards to process and payload is the calldata the vault should execute depending on the claim or reinvest strategy.

This function will execute the configured vault strategy when you call it. You can either call it one-time (ex: to process an airdrop) or regularly (ex: every month to claim a governance token boost).

Partners can choose any asset available to supply on the supported protocols and chains below.

For each unique 'protocol <> asset <> chain' combination, a dedicated vault is deployed for the integration.

For example, if an partner wants to create a strategy around USDC on Ethereum mainnet for AAVE v3, Compound v3, and on Base for Compound v3, then 3 vaults will be deployed:

• USDC <> Aave v3 <> Ethereum

• USDC <> Compound v3 <> Ethereum

• USDC <> Compound v3 <> Base

Supported protocols, assets and chains

Please be aware that assets with negligible Total Value Locked (TVL) or minimal yield generation are not listed in our documentation for convenience. We aim to update this page on a monthly basis so the details below may change.

For the latest information, you can always access the lending protocol directly through the links provided below or you can use this link that provides a single view of all protocols and asset yield.

We are always evaluating new DeFi protocols to support, and can quickly add new protocols based on demand. Adding support for additional EVM-based chains is generally quick and easy. We are also exploring support for select non-EVM chains, such as Tron and Solana. If your preferred DeFi protocol or blockchain is not listed here, please contact us to discuss its addition.