ERC-3156 — Flash Loans

Back to DeFi Building Blocks

ERC-3156: Flash Loan Standard

ERC-3156 standardises uncollateralized atomic loans: a borrower receives any amount, executes arbitrary logic in a callback, and must return the principal + fee before the transaction ends. If the callback fails to repay, the entire transaction reverts and the loan never happened.

Lender Interface

function maxFlashLoan(address token) external view returns (uint256);
function flashFee(address token, uint256 amount) external view returns (uint256);
function flashLoan(IERC3156FlashBorrower receiver, address token,
                   uint256 amount, bytes calldata data) external returns (bool);

Borrower Interface

function onFlashLoan(address initiator, address token, uint256 amount,
                     uint256 fee, bytes calldata data)
    external returns (bytes32);   // returns keccak256("ERC3156FlashBorrower.onFlashLoan")

Neo Equivalent

Neo flash loans work identically — atomic transactions ensure repay-or-revert. The "magic return value" pattern translates one-for-one. The Neo port below uses NEP-17 transfers and a callback method name onFlashLoan that borrowers implement.

Live on Neo TestNet

Both implementations deployed on Neo N3 TestNet.

Implementation	TestNet Address	Contract Hash
Solidity (neo-solc)	NhSy8SUwdRdrYAvK2YadgbXZwRTfJZC6DT	0xb7d5cd14…117d37ec
Neo C# (nccs)	NSogFgSB3xhbRn81ie21Xb8L5vzxAguyZZ	0xa82c8142…1440984b

Verified: pre-setup state (feeBps == 0). Both implementations enforce the ERC-3156 callback magic value (keccak256("ERC3156FlashBorrower.onFlashLoan")) on repay. docs/standards-mirror/deployments/erc-3156/.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IERC3156FlashBorrower {
    function onFlashLoan(address initiator, address token, uint256 amount,
                         uint256 fee, bytes calldata data)
        external returns (bytes32);
}

contract FlashLender {
    bytes32 constant CALLBACK_SUCCESS = keccak256("ERC3156FlashBorrower.onFlashLoan");
    address public immutable token;
    uint256 public           feeBps;   // 9 == 0.09%

    constructor(address token_, uint256 fee_) {
        token = token_;
        feeBps = fee_;
    }

    function flashFee(address t, uint256 amount) public view returns (uint256) {
        require(t == token, "wrong token");
        return amount * feeBps / 10_000;
    }

    function flashLoan(IERC3156FlashBorrower receiver, address t,
                       uint256 amount, bytes calldata data)
        external returns (bool)
    {
        require(t == token, "wrong token");
        uint256 fee = flashFee(t, amount);
        // Send funds
        IERC20(token).transfer(address(receiver), amount);
        // Borrower runs logic; must return CALLBACK_SUCCESS
        require(
            receiver.onFlashLoan(msg.sender, token, amount, fee, data) == CALLBACK_SUCCESS,
            "callback failed"
        );
        // Pull principal + fee back
        IERC20(token).transferFrom(address(receiver), address(this), amount + fee);
        return true;
    }
}

interface IERC20 {
    function transfer(address, uint256) external returns (bool);
    function transferFrom(address, address, uint256) external returns (bool);
}

using System;
using System.ComponentModel;
using System.Numerics;
using Neo;
using Neo.SmartContract.Framework;
using Neo.SmartContract.Framework.Attributes;
using Neo.SmartContract.Framework.Native;
using Neo.SmartContract.Framework.Services;

namespace R3E.Examples;

[DisplayName("FlashLender")]
[ContractPermission("*", "*")]
public class FlashLender : SmartContract
{
    private static readonly byte[] TokenKey = { 0xA0 };
    private static readonly byte[] FeeKey   = { 0xA1 };

    public const string CallbackSuccess = "ERC3156FlashBorrower.onFlashLoan";

    [DisplayName("FlashLoan")]
    public static event Action<UInt160, UInt160, BigInteger, BigInteger> OnFlashLoan;

    [Safe]
    public static UInt160 Token() => (UInt160)Storage.Get(Storage.CurrentContext, TokenKey);

    public static BigInteger FlashFee(UInt160 t, BigInteger amount)
    {
        if (!t.Equals(Token())) throw new Exception("wrong token");
        var bps = (BigInteger)(Storage.Get(Storage.CurrentContext, FeeKey) ?? ByteString.Empty);
        return amount * bps / 10_000;
    }

    public static BigInteger MaxFlashLoan(UInt160 t)
    {
        if (!t.Equals(Token())) return 0;
        return (BigInteger)Contract.Call(Token(), "balanceOf", CallFlags.ReadOnly,
                                         new object[] { Runtime.ExecutingScriptHash });
    }

    public static bool FlashLoanRequest(UInt160 receiver, UInt160 t,
                                        BigInteger amount, object data)
    {
        if (!t.Equals(Token())) throw new Exception("wrong token");
        if (amount <= 0)        throw new Exception("amount <= 0");

        var fee = FlashFee(t, amount);
        var balanceBefore = MaxFlashLoan(t);

        // Send principal to borrower
        Contract.Call(Token(), "transfer", CallFlags.All,
            new object[] {
                Runtime.ExecutingScriptHash, receiver, amount,
                "flashloan-principal"
            });

        // Borrower executes — must return CallbackSuccess
        var ret = (string)Contract.Call(receiver, "onFlashLoan", CallFlags.All,
            new object[] {
                Runtime.CallingScriptHash, Token(), amount, fee, data
            });
        if (ret != CallbackSuccess) throw new Exception("callback failed");

        // Verify repaid: balance must be >= balanceBefore + fee.
        var balanceAfter = MaxFlashLoan(t);
        if (balanceAfter < balanceBefore + fee)
            throw new Exception("flashloan not repaid");

        OnFlashLoan(receiver, t, amount, fee);
        return true;
    }

    public static void _deploy(object data, bool update)
    {
        if (update) return;
        var args = (object[])data;
        Storage.Put(Storage.CurrentContext, TokenKey, (UInt160)args[0]);
        Storage.Put(Storage.CurrentContext, FeeKey,   (BigInteger)args[1]);
    }
}

/// <summary>Borrower contract: receives the principal, runs strategy, repays.</summary>
[DisplayName("FlashBorrower")]
public class FlashBorrower : SmartContract
{
    public static string OnFlashLoan(UInt160 initiator, UInt160 token,
                                     BigInteger amount, BigInteger fee, object data)
    {
        // ... arbitrage / liquidation / refinance logic here ...
        // Must end with: send (amount + fee) back to caller.
        Contract.Call(token, "transfer", CallFlags.All,
            new object[] {
                Runtime.ExecutingScriptHash,
                Runtime.CallingScriptHash,
                amount + fee,
                "flashloan-repay"
            });
        return FlashLender.CallbackSuccess;
    }
}

Why This Works on Neo

Atomic transactions: any uncaught exception or insufficient repayment unwinds the whole transaction, restoring the lender's balance. Same property as Ethereum. Re-entrancy is not a concern because the state changes are deterministic and balance verification at the end of FlashLoanRequest proves repayment.