Ether.fi 백서

Ether.fi

원문

bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 61쪽 중 2쪽

ond if unauthorized recovery is attempted * Allows cancellation of mistaken or malicious recovery attempts * Provides necessary notice to all stakeholders before ownership changes #### Managing or Disabling Recovery While recovery provides important security benefits, you may modify or disable it: 1. Initiate a transaction to update recovery settings or disable the feature 2. Gather the required signatures from Vault owners according to your threshold 3. If you disable recovery, consider implementing alternative backup access methods # Cash Modules This contract is the main neobank financial operations module for EtherFi Vault users. User interactions with the EtherFi Cash system occur via the CashModule contract. `CashModule` allows users to: * Spend funds in Direct Pay mode or Credit mode * Set spending limits * Request and process withdrawals * Earn cashback rewards * Repay borrowed funds * Switch between operational modes * Configure cashback splits CashModule is implemented as a set of contracts following the proxy pattern with distinct components: * `CashModuleCore`: Core financial operations * `CashModuleSetters`: Configuration management * `CashModuleStorageContract`: Storage implementation * `CashLens`: Read-only views ### Write Methods #### setupModule ```solidity function setupModule(bytes calldata data) external ``` Initializes the Cash Module for a new Vault. Function is invoked when the Cash Module is added to an EtherFi Vault. Sets up default spending limits and mode configuration. **Input Parameters:** | Name | Type | Description | | ---- | ----- | ------------------------------------------------------------------------------------------ | | data | bytes | The encoded initialization data containing daily limit, monthly limit, and timezone offset | #### spend ```solidity function spend( address vault, address spender, address referrer, bytes32 txId, BinSponsor binSponsor, address[] calldata tokens, uint256[] calldata amountsInUsd, bool shouldReceiveCashback ) external ``` Processes a spending transaction, transferring funds from the Vault in either Direct Pay or Credit mode. Requires the caller to have the `ETHER_FI_WALLET_ROLE`. When spending in Direct Pay mode, tokens are transferred directly from the Vault to the settlement dispatcher. In Credit mode, tokens are borrowed against the Vault's collateral. **Input Parameters:** | Name | Type | Description | | --------------------- | ---------- | ----------------------------------------------------------------------- | | vault | address | The address of the EtherFi Vault | | spender | address | The address of the user initiating the spend | | referrer | address | The address of the referrer (or address(0) if none) | | txId | bytes32 | Unique transaction identifier | | binSponsor | BinSponsor | Identifier of the bin sponsor (Rain or Reap) | | tokens | address\[] | Array of token addresses to spend | | amountsInUsd | uint256\[] | Array of amounts in USD value to spend (must match tokens array length) | | shouldReceiveCashback | bool | Flag indicating if the transaction should earn cashback | #### repay ```solidity function repay( address vault, address token, uint256 amountInUsd ) public ``` Repays borrowed tokens in Credit mode. When repaying, the Vault must have sufficient balance of the token being used for repayment. **Input Parameters:** | Name | Type | Description | | ----------- | ------- | ------------------------------------------- | | vault | address | The address of the EtherFi Vault | | token | address | The address of the token used for repayment | | amountInUsd | uint256 | The amount to repay, expressed in USD value | #### requestWithdrawal ```solidity function requestWithdrawal( address vault, address[] calldata tokens, uint256[] calldata amounts, address recipient, address[] calldata signers, bytes[] calldata signatures ) external ``` Requests a withdrawal of tokens from the Vault to a recipient address. The function requires valid signatures from the Vault owners according to the Vault's threshold configuration. Initiates a withdrawal request that will be available for processing after the withdrawal delay period. **Input Parameters:** | Name | Type | Description | | ---------- | ---------- | ----------------------------------------------------------------- | | vault | address | The address of the EtherFi Vault | | tokens | address\[] | Array of token addresses to withdraw | | amounts | uint256\[] | Array of token amounts to withdraw | | recipient | address | Address that will receive the tokens | | signers | address\[] | Array of Vault owner addresses that signed the withdrawal request | | signatures | bytes\[] | Array of signatures corresponding to the signers | #### processWithdrawal ```solidity function processWithdrawal(address vault) public ``` Processes a pending withdrawal request after the delay period has passed. The function executes the token transfers to the recipient specified in the withdrawal request. Fails if the withdrawal delay period has not yet elapsed. **Input Parameters:** | Name | Type | Description | | ----- | ------- | -------------------------------- | | vault | address | The address of the EtherFi Vault | #### setMode ```solidity function setMode( address vault, Mode mode, address signer, bytes calldata signature ) external ``` Sets the operational mode for a Vault (Direct Pay or Credit). Switching to Credit mode may have a delay period depending on configuration. Switching to Direct Pay mode happens immediately after verification. **Input Parameters:** | Name | Type | Description | | --------- | ------- | ------------------------------------------------------ | | vault | address | The address of the EtherFi Vault | | mode | Mode | The target mode (Direct Pay or Credit) | | signer | address | Address of the Vault admin signing the transaction | | signature | bytes | Signature from the signer authorizing this mode change | #### updateSpendingLimit ```solidity function updateSpendingLimit( address vault, uint256 dailyLimitInUsd, uint256 monthlyLimitInUsd, address signer, bytes calldata signature ) external ``` Updates the spending limits for a Vault. Changes to spending limits take effect after the configured delay period. **Input Parameters:** | Name | Type | Description | | ----------------- | ------- | -------------------------------------------------- | | vault | address | The address of the EtherFi Vault | | dailyLimitInUsd | uint256 | New daily spending limit in USD | | monthlyLimitInUsd | uint256 | New monthly spending limit in USD | | signer | address | Address of the Vault admin signing the transaction | | signature | bytes | Signature from the signer authorizing this update | #### setCashbackSplitToSafeBps ```solidity function setCashbackSplitToSafeBps( address vault, uint256 splitInBps, address signer, bytes calldata signature ) external ``` Sets the percentage of cashback that goes to the Vault (versus the spender). The split is expressed in basis points, where 10000 represents 100%. **Input Parameters:** | Name | Type | Description | | ---------- | ------- | --------------------------------------------------- | | vault | address | The address of the EtherFi Vault | | splitInBps | uint256 | Percentage in basis points to allocate to the Vault | | signer | address | Address of the Vault admin signing the transaction | | signature | bytes | Signature from the signer authorizing this change | #### clearPendingCashback ```solidity function clearPendingCashback(address[] calldata users) external whenNotPaused ``` Clears pending cashback for a list of users. Attempts to retrieve any pending cashback and distribute it to the specified users. **Input Parameters:** | Name | Type | Description | | ----- | ---------- | ----------------------------------------------------- | | users | address\[] | Array of user addresses to clear pending cashback for | ### Read Methods #### getMode ```solidity function getMode(address vault) external view returns (Mode) ``` Gets the current operational mode of a Vault. Considers pending mode changes that have passed their delay period. **Input Parameters:** | Name | Type | Description | | ----- | ------- | -------------------------------- | | vault | address | The address of the EtherFi Vault | **Return Values:** | Type | Description | | ---- | --------------------------------------------------- | | Mode | The current operational mode (Direct Pay or Credit) | #### canSpend ```solidity function canSpend( address vault, bytes32 txId, address[] calldata tokens, uint256[] calldata amountsInUsd ) public view returns (bool, string memory) ``` Checks if a spending transaction can be executed. Validates if the Vault has sufficient balance or borrowing power for the specified tokens and amounts. **Input Parameters:** | Name | Type | Description | | ------------ | ---------- | --------------------------------- | | vault | address | The address of the EtherFi Vault | | txId | bytes32 | Transaction identifier | | tokens | address\[] | Array of token addresses to spend | | amountsInUsd | uint256\[] | Array of amounts in USD to spend | **Return Values:** | Type | Description | | ------ | ---------------------------------------- | | bool | Whether the spending is allowed | | string | Error message if spending is not allowed | #### maxCanSpend ```solidity function maxCanSpend( address vault, address token ) public view returns ( uint256 returnAmtInCreditModeUsd, uint256 returnAmtInDebitModeUsd, uint256 spendingLimitAllowance ) ``` Calculates the maximum amount that can be spent in both Credit and Direct Pay modes. **Input Parameters:** | Name | Type | Description | | ----- | ------- | --------------------------------- | | vault | address | The address of the EtherFi Vault | | token | address | The address of the token to spend | **Return Values:** | Type | Description | | ------- | --------------------------------------------------------- | | uint256 | Maximum amount that can be spent in Credit mode (USD) | | uint256 | Maximum amount that can be spent in Direct Pay mode (USD) | | uint256 | Remaining spending limit allowance | #### getSafeCashData ```solidity function getSafeCashData( address vault ) external view returns (SafeCashData memory safeCashData) ``` Gets comprehensive cash data for a Vault. Aggregates data from multiple sources including DebtManager and CashModule. **Input Parameters:** | Name | Type | Description | | ----- | ------- | -------------------------------- | | vault | address | The address of the EtherFi Vault | **Return Values:** | Type | Description | | ------------ | --------------------------------------------------------------------------------- | | SafeCashData | Comprehensive data structure containing mode, balances, borrowing power, and more | #### getPendingCashback ```solidity function getPendingCashback(address account) external view returns (uint256) ``` Gets the pending cashback amount for an account in USD. **Input Parameters:** | Name | Type | Description | | ------- | ------- | ----------------------------------------- | | account | address | Address of the account (Vault or spender) | **Return Values:** | Type | Description | | ------- | ------------------------------ | | uint256 | Pending cashback amount in USD | #### getData ```solidity function getData(address vault) external view returns (SafeData memory) ``` Retrieves cash configuration data for a Vault. **Input Parameters:** | Name | Type | Description | | ----- | ------- | ---------------------------- | | vault | address | Address of the EtherFi Vault | **Return Values:** | Type | Description | | -------- | -------------------------------------------------- | | SafeData | Data structure containing Vault cash configuration | ### Events The CashModule emits events for all major operations through the CashEventEmitter: #### WithdrawalRequested ```solidity event WithdrawalRequested( address indexed vault, address[] tokens, uint256[] amounts, address indexed recipient, uint256 finalizeTimestamp ) ``` Emitted when a withdrawal is requested. #### WithdrawalProcessed ```solidity event WithdrawalProcessed( address indexed vault, address[] tokens, uint256[] amounts, address indexed recipient ) ``` Emitted when a withdrawal is processed. #### Spend ```solidity event Spend( address indexed vault, bytes32 indexed txId, BinSponsor indexed binSponsor, address[] tokens, uint256[] amounts, uint256[] amountInUsd, uint256 totalUsdAmt, Mode mode ) ``` Emitted when tokens are spent from a Vault. #### Cashback ```solidity event Cashback( address indexed vault, address indexed spender, uint256 spendingInUsd, address cashbackToken, uint256 cashbackAmountToVault, uint256 cashbackInUsdToVault, uint256 cashbackAmountToSpender, uint256 cashbackInUsdToSpender, bool indexed paid ) ``` Emitted when cashback is calculated and potentially distributed. #### ReferrerCashback ```solidity event ReferrerCashback( address indexed vault, address indexed referrer, uint256 spendingInUsd, address cashbackToken, uint256 referrerCashbackAmt, uint256 referrerCashbackInUsd, bool indexed paid ) ``` Emitted when referral cashback is calculated and potentially distributed. #### ModeSet ```solidity event ModeSet( address indexed vault, Mode prevMode, Mode newMode, uint256 incomingModeStartTime ) ``` Emitted when the operational mode of a Vault is changed. #### SpendingLimitChanged ```solidity event SpendingLimitChanged( address indexed vault, SpendingLimit oldLimit, SpendingLimit newLimit ) ``` Emitted when a spending limit is changed. # MCP Server Connect an AI assistant to your ether.fi Cash account. Read-only, scope by scope, approved with your passkey. ether.fi Cash exposes an [MCP](https://modelcontextprotocol.io) server that lets an AI assistant read your account: your transactions, your cards, your balances and holdings. Ask Claude or ChatGPT what you spent on groceries last month, or what your spending power is today. Visit [ether.fi/ai-connector](https://ether.fi/ai-connector) to explore examples with sample data and copy prompts to use with your own account. The connector URL is: ``` https://mcp.ether.fi/mcp ``` The connector is read-only. There is no write path anywhere in the system, so no assistant can spend, borrow, repay, withdraw, or change your cards through it. Supported assistants are limited to a registry ether.fi maintains. Today that is Anthropic (Claude, including Claude Code) and OpenAI (ChatGPT). *** ## 1. Connecting an assistant Open **Settings → AI Connections** in the Cash app to copy the connector URL and manage your connections. 1. **Copy the URL.** One connector covers every Cash account you hold. 2. **Add it in your assistant.** Open its settings and look for connectors, apps, or plugins, then add one by URL and paste. 3. **Approve with your passkey.** You return to the Cash app to pick an account and choose what the assistant can read. {% hint style="info" %} A passkey is required. If your account has no passkey yet, add one in your security settings, then start the connection again from your assistant. {% endhint %} *** ## 2. What an assistant can read Access is split into three scopes. All three default to off, and you choose which to grant when you approve. | Scope | What you approve | Assistant can read | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `transactions:read` | Your transactions and merchants | Card purchases and on-chain activity: merchant, amount, date, category. Includes top-ups, withdrawals, borrows, repayments, and cashback. | | `cards:read` | Your cards | Card nickname, network, and last four digits. Never the full number, CVC, or expiry. | | `balances:read` | Your balances, holdings, and vault address | Available balance, credit limit, amount borrowed, and the assets in your vault with quantity and dollar value. Includes your vault address. | {% hint style="warning" %} Your vault address is a permanent public identifier. Anyone holding it can look up all of the account's on-chain activity, including after you revoke the connection. {% endhint %} Five account-data tools sit behind those scopes. Each is available only when the assistant's grant carries the matching scope. A sixth tool, `example_library`, is available to every connection and reads no account data. | Tool | Scope | Reads | | --------------------- | ------------------- | -------------------------------------------------------------------------------------- | | `list_transactions` | `transactions:read` | Card and on-chain activity, filterable by date, category, and merchant | | `list_cards` | `cards:read` | Nickname, type, last four digits, status, currency | | `get_main_account` | `balances:read` | Spending power, credit limit, amount borrowed, vault address | | `get_portfolio` | `balances:read` | Per-asset holdings: quantity, dollar value, whether it backs spending, yield | | `get_deposit_address` | `balances:read` | Deposit address and the networks and assets it accepts | | `example_library` | None | Curated examples, prompts, required tools, a style guide, and the public examples page | An assistant can call `example_library` with no arguments (`{}`) when you ask what you can build, or before creating a page or chart from your Cash data. It returns `examples_page`, `style_guide`, and an `examples` list. Each example includes its name, description, prompt to generate it, and the account-data tools it needs. Building an example with your own data still requires the scopes for those tools. *** ## 3. What an assistant cannot do Four boundaries hold at every scope, for every assistant. **No writes.** No spending, borrowing, repaying, withdrawing, or card management. A write scope would be a different threat model, so none exists. **No card secrets.** The full card number, CVC, and expiry are not readable through the connector at any scope. `list_cards` returns the same fields the app's card list shows without stepping up authentication. **No choosing an account.** The account is never a tool parameter. It lives inside the signed token issued for the connection and is re-derived on every request. One connection reads exactly one account, and an assistant cannot ask for a different one. **No figures ether.fi did not compute.** There is no spending-total tool. Every number the connector returns is one your own app screen also shows, so anything an assistant quotes can be checked against a row you can open. Totals are the assistant's arithmetic over transactions you can see. {% hint style="info" %} AI assistants can make mistakes when summarising or totalling. Treat what an assistant tells you as a convenience and your Cash app as the source of truth. {% endhint %} *** ## 4. Consent Every connection is approved on an ether.fi screen, in your browser, with a passkey. On it you: * **Pick the account.** If you hold more than one, they are labelled distinctly. * **Choose the scopes.** Switches default to off. Granting nothing is a valid outcome. * **See existing connections.** If that assistant is already connected to that account, approving adds a second connection rather than replacing the first. * **Prove presence with a passkey.** That signature binds the grant to you and to the account you picked. Everything the screen says about who is asking comes from ether.fi's own registry: name, icon, developer, and verified legal entity are all fields ether.fi controls. None of it comes from what the client asserts about itself, because a name a client picks is a name an attacker can pick. This is what makes co
프로젝트로 돌아가기