The `Sign' button presents this if you offer an MLA.
You're asked to explicitly decline the MLA if you don't offer one.
Post-deployment, your market will appear as Non-Deposited, since obviously no one has put anything in it yet!
Step 1: Enter how much you want to borrow from your market.
Step 2: Verify you're comfortable with how long your market will remain healthy and confirm.
You can also elect to repay a number of days worth of anticipated interest rather than a specific amount.
POV: you're increasing Base APR. No change.
(Recently adjust notification here is just because it's a new market).
POV: you're reducing Base APR by 25% or less. No change.
POV: you're reducing Base APR by more than 25%. No collateral obligation here (empty market), but you'll only be able to borrow half of what anyone deposits for the next two weeks.
Note that the lender has active loans to three markets - the 'No Active Markets' under the 'Non-Deposited' is indicative of the fact that there are no markets where the lender has been explicitly onboarded to by a borrower (or otherwise holds an access credential) and they haven't deposited any assets yet. This might be confusing, let us know if that's the case!
You can reach out to the borrower through one of the methods available on their borrower profile if you want to ask about being added (click the blue underlined borrower name for that market).
This particular market has a minimum deposit amount, but otherwise it's the same
pattern you're used to from everywhere else that you know and love.
These are mock tokens on Sepolia, but tokens in, debt tokens out.
I went and took this image after the one below, no one ever accused me of being good at this.
We did this because we, as its' developers, got confused at one point as to why we weren't able to place withdrawal requests.
Example of the lender's perspective when a withdrawal cycle is ongoing.
2. We update the market after half a year (T2): * scaleFactor = previousScaleFactor \_ (1 + APR \_ timeElapsed / oneYear) = 1.05 * scaledBalanceOf(bob) = 100 * balanceOf(bob) = scaledBalanceOf(bob) \* scaleFactor = 105 * scaledTotalSupply = 100 * totalSupply = (scaledTotalSupply \* scaleFactor) = 105
3. In the same block, Alice deposits 210 TKN (T3): * scaleFactor = 1.05 * scaledBalanceOf(bob) = 100 * balanceOf(bob) = 105 * scaledBalanceOf(alice) = deposit / scaleFactor = 210 / 1.05 = 200 * balanceOf(alice) = scaledBalanceOf(alice) \* scaleFactor = 210 * scaledTotalSupply = 300 * totalSupply = (scaledTotalSupply \* scaleFactor) = 315
4. After another half a year, we update the market again (T4): * scaleFactor = previousScaleFactor \_ (1 + APR \_ timeElapsed / oneYear) = 1.1025 * scaledBalanceOf(bob) = 100 * balanceOf(bob) = scaledBalanceOf(bob) \* scaleFactor = 110.25 * scaledBalanceOf(alice) = 200 * balanceOf(alice) = scaledBalanceOf(alice) \* scaleFactor = 220.50 * scaledTotalSupply = 300 * totalSupply = (scaledTotalSupply \* scaleFactor) = 330.75 # Core Behaviour How a market operates internally: configuration, collateral obligation, interest accrual, state updates and the withdrawal batch lifecycle. This section contains the most important aspects of how a Wildcat market operates. Make sure you understand the [scale factor](/technical-overview/security-developer-dives/the-scale-factor) before continuing. ## Market Configuration Markets are configured with the following values: * `asset` - The underlying asset for the market * `name` - The name of the market (borrower-provided prefix + asset name) * `symbol` - The symbol of the market (borrower-provided prefix + asset symbol) * `borrower` - Address allowed to borrow from and make changes to the market * `feeRecipient` - Recipient of protocol fees * `sentinel` - Chainalysis wrapper determining whether accounts are sanctioned * `maxTotalSupply` - The `totalSupply` at which the market will stop accepting withdrawals * `protocolFeeBips` - A fraction of `annualInterestBips` which accrues to the protocol (in excess of the rate paid to lenders, not subtracted from it). This is not affected by delinquency fees. * `annualInterestBips` - The base interest rate set by the borrower. Accrues solely to lenders. * `delinquencyFeeBips` - Penalty fee added to the interest rate when the borrower is delinquent for too long. . Accrues solely to lenders. * `withdrawalBatchDuration` - The length of a withdrawal cycle. * `reserveRatioBips` - The fraction of outstanding debt which the borrower is obligated to keep in liquid reserves. * `delinquencyGracePeriod` - The amount of time a borrower has before incurring penalties for a delinquent market. * `archController` - Registry for factory/controller/market deployments. * `sphereXEngine` - Engine for SphereX integration which does security checks on transactions. * `hooks` - The market's hooks policy and the address of the hooks instance. ## Basic Market Behavior ### Collateral Obligation Not all market tokens have the same collateral requirements attached. Tokens which are in pending withdrawals (current or unpaid expired batches) must be covered 100% by the borrower with underlying assets as soon as they enter a withdrawal batch, while tokens which are not pending withdrawal only need to be covered at the reserve ratio. We call the portion of the market's total supply which is not pending withdrawal the *outstanding supply*. Aside from market tokens, there are two other contributors to the collateral obligation: unclaimed protocol fees and unclaimed withdrawals. The latter are no longer associated with market tokens as they represent tokens that have already been paid for, burned and subtracted from the total supply; however, because lenders do not receive their withdrawals until they claim them via `executeWithdrawal`, the assets that have been set aside for withdrawals must remain in the market and so increase the collateral requirement for the market. This effectively just reduces the `totalAssets` the market sees as being available, as these assets do not cause the borrower to incur any additional interest payments or fees. See the section on withdrawals for further details. The total collateral obligation that a borrower is required to maintain in the market (`state.liquidityRequired()`) is the sum of: * 100% of all pending (unpaid) withdrawals * 100% of all unclaimed (paid) withdrawals * reserve ratio times the outstanding supply * accrued protocol fees ``` state.normalizeAmount(state.scaledPendingWithdrawals) + state.normalizedUnclaimedWithdrawals + state.normalizeAmount( state.scaledTotalSupply - state.scaledPendingWithdrawals ).bipMul(state.reserveRatioBips) + state.accruedProtocolFees ``` ### **Delinquency** Whenever a market has less total assets than its minimum collateral obligation, the borrower is considered delinquent (`state.isDelinquent`). For every second the borrower remains delinquent, a timer (`state.timeDelinquent`) increments. For every second the market is in a healthy state, the timer decrements. For every second that the market spends with its delinquency timer above the grace period, the delinquency fee is applied to the interest rate. This system results in the borrower being penalized for two seconds for every second they allow `timeDelinquent` to exceed the grace period: once on the way up while the market is delinquent, and once on the way down when the market is healthy. ### Interest Rates Borrowers pay interest based on three rates, all of which are denominated in annual bips (1 = 0.01%): * `annualInterestBips` - The base interest rate set by the borrower. Accrues solely to lenders. * `delinquencyFeeBips` - An additional fee added to the base interest rate whenever the borrower is in penalized delinquency. Accrues solely to lenders. * `protocolFeeBips` - A fraction of `annualInterestBips` which accrues to the protocol (in excess of the rate paid to lenders, not extracted from it). This is not affected by delinquency fees. Every state update, the sum of these rates is applied to the current `scaleFactor` (with the delinquency fee only being applied for the number of seconds the market was in penalized delinquency), compounding the market's interest. ### State Update At the start of every stateful external function on a market which is the first such transaction in a block, a state update occurs to bring the market state up-to-date. The basic state update sequence is: 1. Accrues the base interest rate and protocol fees, as well as the delinquency fee for any seconds since the last update during which the market was in [penalized delinquency](https://github.com/wildcat-finance/v2-protocol/blob/main/docs/Core%20Behavior.md#delinquency) 2. Updates the delinquency timer, increasing if the previous state was delinquent and decreasing if it was not (to a minimum of zero). 3. Applies any available liquidity to the pending withdrawal batch if there is one. If, at the start of the transaction, the current pending withdrawal batch has expired, the state update will be split into two iterations of the above sequence: * The first will use the last update time as the start date and the withdrawal batch expiry as the end date, and it will handle [batch expiry](https://github.com/wildcat-finance/v2-protocol/blob/main/docs/Core%20Behavior.md#withdrawal-expiry--priority) in the third step after reserving available liquidity. * This ensures that the borrower does not pay interest on withdrawals that can be retroactively paid off at the time of expiry. * The second will use the expiry as the start date and the current time as the end date. ### Withdrawals Withdrawal batches group together withdrawal requests from multiple lenders over a period of time (the `withdrawalBatchDuration` parameter) to ensure a fair distribution of available assets when a market is insufficiently liquid to fully honor all withdrawals in a batch. When a lender requests a withdrawal, they will be entered into the current withdrawal batch if one exists; otherwise, a new one will be created. From the time a withdrawal batch is created until the time it expires, new lenders may enter the batch by creating a withdrawal request. At the time of the request, the lender is credited for the scaled token amount their withdrawal is equivalent to, giving them pro-rata ownership of the batch according to that scaled amount. These scaled tokens are removed from the lender's balance, but the total supply is only reduced upon payment. Withdrawal *execution*, or the claiming of paid withdrawals, is only possible after expiry. Withdrawal batches can be in one of three states: * Current: The batch represented by `state.pendingWithdrawalExpiry`. Can be added to by lenders until it expires. * Note: The "current" batch can also be expired until the state update function is executed and converts it to an unpaid or paid batch. * Unpaid: A batch which has expired without sufficient assets to cover all withdrawals. * Paid: A batch which has been fully paid off. * Note: "paid off" means that assets are reserved and available for execution, not necessarily that all the withdrawals have been executed. ### **Withdrawal Expiry & Priority** If a batch expires without sufficient assets to cover all requests in it, it is moved into a first-in-first-out queue of "unpaid" batches. Earlier withdrawal batches receive priority over newer batches for payment, but lenders within the same batch have a pro-rata claim to the underlying assets allocated to it regardless of the order of their requests. When a withdrawal batch expires, the liquidity which can immediately be reserved to pay it off is equal to the market's total assets minus the *unavailable* assets, which is the sum of: * unclaimed (paid) withdrawals (`state.normalizedUnclaimedWithdrawals`) * previous unpaid withdrawals (`state.scaledPendingWithdrawals - batch.scaledOwedAmount`) * unclaimed protocol fees (`state.accruedProtocolFees`) Note that while earlier batches receive priority, **this does not mean they always actually get paid first**. When a current batch expires, it can be fully paid off even if there are currently unpaid withdrawal batches in the queue, but only provided that the market has sufficient assets available to cover both. Once a batch is marked as unpaid, it can not have assets reserved for it until all previous unpaid batches are processed. > Note: Skipping over unpaid batches is allowed for expiring batches because it is trivial to calculate the sum of previous withdrawals as the current batch expires, but doing so for a batch in the middle of the unpaid queue would be much more costly. ### **Withdrawal Payment** The scaled tokens associated with a withdrawal request are subtracted from a lender's balance immediately, but those tokens are not *burned* until they are honored, meaning they only stop accruing interest once underlying assets have been reserved to pay for them. The batch owns these scaled tokens and accrues their interest until they are burned by a payment, and the interest is distributed pro-rata to the lenders in the batch. As assets become available, they can be paid to the withdrawal batch. A check for (and payment of) available assets occurs: * when a lender adds a request to a batch, * during the state update at the start of a transaction (for the current batch but not for unpaid (already expired) batches), * upon a call to `repayAndProcessUnpaidWithdrawalBatches` (for unpaid batches). Once an amount of underlying assets is paid to the batch, the corresponding scaled amount is actually burned: it is removed from the market's total supply, stops accruing interest and becomes available for withdrawal execution by lenders in the batch. These paid-for withdrawals are then moved into the pool of *unclaimed withdrawals* (`state.normalizedUnclaimedWithdrawals`) representing the amount of underlying assets that are still in the market but which can not be borrowed against and can not be counted toward the reserve ratio, protocol fees or new withdrawal payments. # V1 -> V2 Changelog If you have previously reviewed the Wildcat V1 codebase, these are the major changes made for V2. ## Lens Removed the lens contracts from the core protocol repository. ## Market Deployment ### **CREATE2 Restrictions** Borrowers are no longer restricted to deploying one market per combination of (asset, name, symbol), which was an issue when a borrower needed to close and recreate an existing market. When deploying a market, the borrower can now provide an arbitrary salt in the style of 0age's ImmutableCreate2Factory, where the first 20 bytes must either be zero or match the borrower's address, and the remaining 12 bytes can be any value so long as the full salt has not already been used. ### **Name/Symbol Length** Increased maximum supported name/symbol length for underlying contract from 32 to `63 - prefix.length`. The name/symbol queries now support arbitrary length strings; once combined with their prefixes, each must fit into two slots, with one byte reserved for the string length. ## Markets ### **Accounts** * Accounts no longer have a `role` field, their ability to access various functions (other than borrower-only ones) is not restricted within the market itself, this is delegated to the market's hooks. ### **Handling Of Sanctioned Accounts** * Removed `stunningReversal` because accounts no longer have roles marking them as sanctioned. * Market tokens are forced into a withdrawal batch rather than being transferred to an escrow when an account is marked as sanctioned. Withdrawal execution on a sanctioned account still transfers the underlying assets to the corresponding escrow. * Functions which are not accessible to sanctioned entities no longer fail gracefully (in V1 they would block the account rather than revert). They now revert with an `AccountBlocked` error when the account is sanctioned. ### **Withdrawal Batch Rounding** Normalised values for withdrawal batch payments are now rounded down rather than up to prevent a bug where closed markets could have their last withdrawal batch become uncloseable due to underpayment by a few wei. ### **Token Rescue Function** For assets other than the market token itself or the underlying asset, ERC20 tokens sent to the contract can be recovered by the borrower. ### **Market Closure** * When a borrower closes a market that has pending withdrawals or unpaid withdrawal batches, rather than reverting, the market now steps through the list of unpaid batches and closes them after transferring all remaining debt from the borrower. * `closeMarket` now callable by borrower rather than controller. ### **ReentrancyGuard** The ReentrancyGuard now uses transient storage, using a modified version of 0age's ReentrancyGuard from Seaport. ### **APR/Reserve Ratio Setters** * Removed `setAnnualInterestBips` and `setReserveRatioBips` * Added `setAnnualInterestAndReserveRatioBips` * Now callable by borrower rather than controller ### **Miscellaneous** Replaced most of the remaining ABI decoders/encoders for calls and large structs with manual assembly coder functions. * Custom encoder for writing MarketState to storage. * Custom decoder for constructor parameters and factory call. * Custom encoders for all sentinel calls in market. * Custom name/symbol query functions * Custom state initialisation in constructor, only touching slots that are actually initialised. ## Market Control Market controllers have been removed in favour of borrower-controlled markets with hooks that can impose their own restrictions. By default, the market itself does not restrict basic access to the market. # Known Issues Some aspects and quirks of the protocol codebase that may raise concern. ## **Avoiding Delinquency Fees** If the borrower closes a Wildcat market while it is still in penalized delinquency, they will not have to pay out the remaining time worth of penalized delinquency fees as the timer will be set to zero. We decided that this is an acceptable trade-off enabling lenders to access their funds immediately, rather than waiting what could range from days to weeks for a borrower to come good on their word. ## **Malicious/Delinquent Borrowers Can Lead To Loss Of Funds** This one is fairly obvious but worth stating - if a borrower fails to repay their debt for any reason, lenders will inevitably lose funds. If the borrower is malicious, they can hurt lenders in a variety of ways, including but not limited to: not repaying debt; adding themselves as a lender in order to withdraw beyond the borrow limit on a market they intend to default on; slowly reducing the APR by 25% every two weeks to avoid the penalty of an increased reserve ratio, and several other things. ## **Newer Withdrawals Lose Some Of Their Accrued Interest To Previous Withdrawals In The Same Batch** This one is intentional but may initially seem erroneous. If Alice creates a withdrawal batch with a request to withdraw 100 tokens while the scale factor is 1, and then Bob later requests a withdrawal of 200 tokens when the scale factor is 2 and they are in the same batch, Alice and Bob will both receive 150 underlying tokens: they have each been credited for 100 scaled tokens given to the batch. This is very much desired behavior, as it prevents earlier lenders from being penalized for creating a batch (which benefits the other lenders). All interest earned on scaled tokens entered into a batch is distributed evenly to the lenders in the batch, as if they had all created their withdrawal requests at the same time. The example given is also an extreme one: in practice it'd much more likely be a fraction of a percent. ## **Bad Hook Implementations** If any of the hooks that are enabled for a market can revert unexpectedly, the corresponding market function may become permanently disabled. This is considered a known/unfixable issue with respect to the market, but if such an issue is actually discovered in a hooks template that has been developed and deployed, this is a major vulnerability that should be reported. ## **Sanctioned Account Handling Can Lead To Unexpected Behaviour On Markets With Withdrawal Restrictions** If a market uses a hook with a withdrawal restriction, e.g. to prevent withdrawals before a specified date, sanctioned account handling may not work correctly as it will attempt to force the lender into a withdrawal, and those withdrawals are treated the same as any other. This could lead to unavoidable interest payments to a sanctioned entity's escrow address (where the funds will go when withdrawals are eventually unrestricted). ## **Hooks Lack Some Specificity** While one of the stated objectives of hooks is to enable auxiliary behavior based on the state of a Wildcat market (one example is a Masterchef-style contract), the hooks do not necessarily provide enough information to replicate the market state 1:1 in real time. Specifically, because payment towards a withdrawal batch does not have its own hook, the hooks instance would need to query additional data and perform additional calculations to precisely track the balance of an account including its pending withdrawals in real time, or to know the exact state of a pending/unpaid withdrawal batch. We anticipate that, for any features added in the future, considering an account to have burned their market tokens at the time a withdrawal is queued will be sufficient precision for the purposes we expect to need this for, and as such we consider the loss of 100% precision on the exact internal market state to be a reasonable sacrifice considering the additional cost such precision would impose. Any other issues with the ability of a hooks instance to track the state of the market should be reported. ## **Conversion Between Scaled And Normalised Amounts Have Some Rounding Error** We are aware that deposits, withdrawals, and even transfers incur some inevitable rounding error. We will only accept findings that show either: * This dust is sufficient to break something in the market, or * The rounding error can realistically be more than dust So for example, we would not accept a finding that says you could do ten million transfers to accumulate ten million wei worth of the market token. On the other hand, in V1 there was a finding where the dust could cause a market to be impossible to close, which is why we now round down for withdrawal payments to a batch. ## **Some Assembly Blocks Leave Dirty Bits In Memory** For example, in `HooksConfig`, all of the calls from a market to the various hook functions are done in assembly, with the calldata written to unallocated memory that is left as is at the end of the call. We would only accept a finding on this subject if it demonstrated a specific attack showing this is unsafe or can lead to buggy behavior. ## **Markets Can Be Constructed In A Way That Makes It Impossible For Anyone To Request A Withdrawal** While we tried our best to ensure lenders who deposit to a market can not have their withdrawal rights revoked (by ensuring the deposit/transfer hooks are always enabled if the withdrawal hook is enabled), it is still possible for a borrower to maliciously prevent lenders from ever acquiring the necessary credential for withdrawals. The way this would work is: * Create a market with credentials required for withdrawal but not for deposit or transfers. * Never add any role providers. * Lenders can deposit, but since they'll never have a credential, they will never be given the `isKnownLender` flag, and thus can never withdraw. Unfortunately it is not possible to remove this problem without eliminating certain kinds of market that are desirable, so we consider this in a similar vein to the issue with malicious borrowers simply not repaying their debt, in that it's up to lenders to be selective with who they lend to. As a mitigation, we force all markets deployed through the Wildcat frontend as having credentials required for deposit. ## **Reliance On Chainalysis** If the Chainalysis sanctions oracle were to be compromised or otherwise start flagging accounts as sanctioned that in reality are not, that would lead to those accounts being frozen on all Wildcat markets they lend to. # Hooks Overview of the hooks system that gates and reacts to market actions. Wildcat V2 markets support hooks which can add additional behaviour to the markets, such as handling access control or adding new features. The goal of the hooks feature is two-fold: to allow restrictions to be set for individual markets and to enable secondary actions that occur in reaction to market actions. Some examples of the individualized restrictions hooks enable are: * An access control scheme that allows lenders to access markets without manual approval by the borrower, * Minimum deposit requirements, * Time restrictions on withdrawals, i.e. no withdrawals for the first 3 months. An example of the additional behaviour hooks enable is the ability to add a Masterchef-style system that distributes rewards to lenders, which requires tracking token balances for the market on a separate contract. This hooks system was chosen to make Wildcat V2 more modular than V1 and improve our ability to develop and deploy new features for Wildcat markets without changing the rest of our core infrastructure such as factories or the base market contract, or needing to re-audit the static parts of the codebase. ## Hooks Templates The Wildcat Labs team will develop various templates for hooks contracts, with each intended for use with a separate kind of market. For example, our initial hooks template only provides access control for lenders and some basic restrictions on APR changes, whereas future templates might provide for withdrawal time limits on hooked markets or token rewards distribution. Approved templates will be deployed as stored initcode (constructor code with a leading zero byte to prevent execution) and approved on the HooksFactory contract. Borrowers who are registered on the archcontroller can then select from the available templates when deploying new markets. ## Hooks Deployment Hooks contracts can be deployed by borrowers registered on the archcontroller. Borrowers can choose to deploy a new hooks instance for each market (which they might want to do if the markets need different requirements for access, or they want to use a different hooks template), or to re-use the same hooks instance for several markets (if they want the same kind of market and the hooks instance supports use with multiple markets). Each hooks instance defines a set of optional hooks and a set of required hooks. When deploying a market, the borrower specifies which hooks the market should utilize, and the market will use the hooks which are marked as required by the hooks instance or marked optional and selected by the borrower. Once a market is deployed, its hooks instance cannot be edited, nor can the set of hooks it uses. ## Source Code \[repo not yet public] Links TBA ## Further Reading How Hooks Work Access Control Hooks # How Hooks Work The hookable market functions, HooksConfig flags, intermediate state, and the extraData calldata buffer. Each of the following is considered a core function within the WildcatMarket contract which we may want a hooks contract to be able to track, impose restrictions on, or otherwise react to in some way: * `deposit` (+ `depositUpTo`) * `queueWithdrawal` (+ `queueFullWithdrawal`) * `executeWithdrawal` (+ `executeWithdrawals`) * `transfer` (+ `transferFrom`) * `borrow` * `repay` (+ `repayOutstandingDebt`, `repayDelinquentDebt`) * `closeMarket` * `setMaxTotalSupply` * `nukeFromOrbit` * `setAnnualInterestAndReserveRatioBips` Each of these functions has a corresponding hook that can be called on the configured hooks contract, as well as a flag in the market's hooks configuration (`HooksConfig`) indicating whether the hook *should* be called. When one of these functions on a market is called, the market will check if the corresponding hook is enabled; if it is, it will call the hook function on the configured hooks contract, providing the intermediate state (prior to applying the full effects of the relevant action, but after accruing interest and fees), the relevant data for the action, the caller address (except for borrower-only functions) and an optional `extraData` buffer supplied by the caller. Hooks can not modify internal behavior of the market and do not have any privileged access to its state; rather, they are designed to be *reactive to* and *restrictive of* market actions. This means, for example, that a hook can not change who receives a transfer or force a lender into a withdrawal, but it can prevent a transfer from occurring or keep some internal state about the withdrawal. ## **Exceptions To The Above** There are two exceptions to the behavior described above. 1\) The rule about not modifying the market behavior is violated by `setAnnualInterestAndReserveRatioBips` - when a market's APR or reserve ratio are changed, the associated hook has the ability to modify those two values. 2\) The rule about only providing intermediate state (i.e. before execution of the action) is violated by the `queueWithdrawal` functions - when a withdrawal is queued, the intermediate state provided to the hooks call is the state *after* the market's `pendingWithdrawalExpiry` is updated. This ensures the hook has access to the withdrawal expiry if that is ever needed. ## `extraData` Buffer In a call to one of the core functions listed above, the caller can append arbitrary bytes to the end of the function calldata. If they do, these bytes will be provided to the call to the hooks contract in the `bytes extraData` field. The primary use-case for this field is for the access control hooks, where the caller may need to provide a signature, merkle proof, or some other verification data in order to be authenticated to a particular market. The `extraData` field is not part of the market's function signatures; the raw bytes must be appended to the end without ABI offset or length fields, and without padding to the closest word (otherwise the calculated length will be incorrect). For calls to `executeWithdrawals` and `nukeFromOrbit`, the optional buffer cannot be provided. # Access Control Hooks The access-control hooks template: role providers (pull/push), credential validation, and the access-resolution flow. In the access control hooks, the borrower can configure a set of "role providers" - accounts which grant credentials to lenders. Within the hooks contract, the borrower configures each provider with a TTL - the amount of time a credential granted by the provider is valid. The provider itself defines whether it is a "pull provider", meaning whether the hooks contract can query the role provider to check if a lender has a credential, using only the lender's address. ## Role Providers Role providers can "push" credentials to the hooks contract by calling `grantRole`: * `grantRole(address account, uint32 roleGrantedTimestamp) external` There are three functions that the hooks contract can call on role providers: * `isPullProvider() external view returns (bool)` * Defines whether the hooks contract can retrieve credentials using `getCredential` * `getCredential(address account) external view returns (uint32 timestamp)` * Looks up a credential for an account using only its address, so it must already be stored somewhere. * `validateCredential(address account, bytes calldata data) external returns (uint32 timestamp)` * Attempts to validate a credential from some arbitrary data (e.g. ecdsa signature or merkle proof). Role providers do not *have* to implement any of these functions - a role provider can be an EOA. *** ## tryValidateAccess(address lender, bytes hooksData) When a restricted function is called, the access control contract will attempt to validate the caller's access to the market in several ways. 1. If lender has an unexpired credential from a provider that is still supported, return true. 2. If the lender provided `hooksData`, run [`handleHooksData(lender, hooksData)`](https://github.com/wildcat-finance/v2-protocol/blob/main/docs/hooks/templates/Access%20Control%20Hooks.md#handleHooksDataaddress-lender-bytes-hooksData) * If it returns a valid credential, go to step 5 3. If the lender has an expired credential from a pull provider that is still supported, try to refresh their credential with `getCredential` (see: [tryPullCredential](https://github.com/wildcat-finance/v2-protocol/blob/main/docs/hooks/templates/Access%20Control%20Hooks.md#tryPullCredentialaddress-provider-address-lender)) * If it returns a valid credential, go to step 5 4. Loop over every pull provider in `pullProviders` (other than the existing provider and provider in `hooksData`, if they exist) * Run [tryPullCredential](https://github.com/wildcat-finance/v2-protocol/blob/main/docs/hooks/templates/Access%20Control%20Hooks.md#tryPullCredentialaddress-provider-address-lender) on each provider. * If any returns a valid credential, break the loop and go to step 5 5. If any provider yielded a valid credential, update the lender's status in storage with the new credential and return. 6. Otherwise, throw an error. ```mermaid flowchart TD validateAccess[["tryValidateAccess(address lender, bytes hooksData)"]] --> hasUnexpiredCredential{Lender has\nunexpired credential?} hasUnexpiredCredential -- yes --> returnTrue([Access verified]) hasUnexpiredCredential -- no --> providedHooksData{hooksData?} providedHooksData -- yes --> callHandleHooksData[["handleHooksData(lender, hooksData)"]] callHandleHooksData -- valid credential --> step5[(Write credential\nto storage)] --> returnTrue callHandleHooksData -- no valid credential --> expiredCredential{Lender has\nexpired credential?} providedHooksData -- no --> expiredCredential expiredCredential -- yes --> callTryPullCredential1[["tryPullCredential(existing provider, lender)"]] callTryPullCredential1 -- valid credential --> step5 callTryPullCredential1 -- no valid credential --> loopStart expiredCredential -- no --> loopStart subgraph loopProviders [Loop over pull providers] loopStart{Next provider} loopStart -. next provider .-> callTryPullCredential2[["tryPullCredential(next provider, lender)"]] callTryPullCredential2 -. no valid credential .-> loopStart loopStart -- no more providers --> throwErrorHandle{{Throw}} end callTryPullCredential2 -- valid credential --> step5 ``` *** ## tryPullCredential(address provider, address lender) 1. If the provider is not approved, return with no valid credential 2. Call `getCredential` on the provider * If it reverts, return with no valid credential 3. Add the returned `timestamp` to the provider's TTL to get the expiry 4. If the resulting credential is expired, return with no valid credential 5. Return with valid credential ```mermaid flowchart TD A[["tryPullCredential(address provider, address lender)"]] --> B{provider\n approved?} B -- yes --> X{"provider is\npull provider?"} B -- no --> C([No valid credential]) X -- yes --> D["Call provider.getCredential(lender)"] X -- no --> C D -- revert --> C D -- invalid data --> C D -- timestamp --> T[+ provider's TTL = expiry] --> F{expired?} F -- yes --> C F -- no --> G([Valid credential]) ``` *** ## handleHooksData(address lender, bytes hooksData) 1. Is `hooksData` 20 bytes? * If not, go to 2 * Set `provider` to `hooksData` * Return result of `tryPullCredential(provider, lender)` 2. Is `hooksData` more than 20 bytes? * If not, return false 3. Take first 20 bytes as `provider`, the rest is `validateData` 4. If the provider is not approved, return false 5. Call `validateCredential(lender, validateData)` * If it reverts, return false * If it returns invalid data, throw an error because the call could have side effects 6. Add the returned timestamp to the provider's TTL to calculate the expiry 7. If it is expired, return false 8. Return true ```mermaid flowchart TD handleData[["handleHooksData(address lender, bytes hooksData)"]] --> check20Bytes{is hooksData\n20 bytes?} check20Bytes -- no --> checkMoreThan20Bytes{more than\n20 bytes?} checkMoreThan20Bytes -- no --> invalidCredential([No valid credential]) checkMoreThan20Bytes -- yes --> extractProviderAndData["provider = hooksData[0:20]\nvalidateData = hooksData[20:]"] extractProviderAndData --> isProviderApproved{provider\n approved?} isProviderApproved -- no --> invalidCredential isProviderApproved -- yes --> callValidateCredential["Call provider.validateCredential(lender, validateData)"] callValidateCredential -- revert --> invalidCredential callValidateCredential -- timestamp --> calculateExpiry["+ provider's TTL = expiry"] --> checkExpiry{expired?} callValidateCredential -- invalid data --> throwError{{Throw}} checkExpiry -- yes --> invalidCredential checkExpiry -- no --> validCredential([Valid credential]) check20Bytes -- yes --> extractProvider["provider = hooksData"] --> callPullCredential[["tryPullCredential(provider, lender)"]] callPullCredential -.-> invalidCredential callPullCredential -.-> validCredential ``` # Fixed Term Loan Hooks The fixed-term variant of the access-control hooks, adding a withdrawal-blocking fixed term. The fixed term loan hooks template is identical to the access control hooks template with one additional feature - the borrower can define a timestamp before which the market is considered a "closed term" loan, where withdrawals are disallowed. This expiry time can be reduced but can not be set to a later date after deployment. ## `onCreateMarket` When deploying a market, the borrower must provide an ABI encoded timestamp for the market's `fixedTermEndTime` in the `hooksData` field of `HooksFactory.deployMarket` or `HooksFactory.deployMarketAndHooks`. This time cannot be in the past and can not be more than one year in the future. They can optionally provide a minimum deposit amount by setting `hooksData` to the ABI encoded tuple `(fixedTermEndTime, minimumDeposit)`. The `onQueueWithdrawal` hook will always be enabled, but will only require access if the borrower's provided config had `useOnQueueWithdrawal` enabled, which will also affect the transfer and deposit hooks in the same way as `AccessControlHooks`. # Wildcat 4626 Wrapper Developer reference for the Wildcat4626Wrapper and its factory — functions, rounding, exchange-rate helpers and error codes. The `Wildcat4626Wrapper` is a vault that wraps a Wildcat market's rebasing debt token with a non-rebasing ERC-4626 share token. Wrapper shares mirror the market's *scaled* balances while the underlying "asset" is the rebasing market token itself. Make sure you understand the [scale factor](https://docs.wildcat.finance/technical-overview/security-developer-dives/the-scale-factor) before continuing: the wrapper leans on it heavily for all share/asset conversions. Deployed addresses for factories can be found [here](https://docs.wildcat.finance/technical-overview/contract-deployments). ### TLDR The 'wrapper' is itself an ERC-4626 vault where: * The **asset** is the Wildcat market token (the rebasing debt token). * **Shares** are equivalent to the market's *scaled* token amounts: 1 wrapper share represents `1 * scaleFactor` market tokens at any given time. * The **exchange rate** between shares and assets is the market's `scaleFactor`. As interest accrues and the scale factor grows, each wrapper share becomes convertible to more market tokens, but the share balance itself does not change. This means a holder of wrapper shares sees a stable balance that appreciates in *value* over time (via the increasing exchange rate), rather than a balance that constantly rebases upward. ### Contracts #### `Wildcat4626Wrapper` An ERC‑4626 vault where: * **Asset** is the Wildcat market debt token (rebasing ERC‑20). * **Shares** are a wrapper ERC‑20 that mirrors the market’s *scaled* accounting (non‑rebasing). The wrapper uses the market's current `scaleFactor` as the exchange rate between shares and assets. Converting assets to shares means dividing the rebasing market-token amount by the scale factor, while converting shares back to assets means multiplying the share amount by that same factor. Because the scale factor grows as interest accrues, a holder's wrapper share balance stays constant while the amount of market tokens those shares can redeem for increases over time. #### Metadata **`name()`** Returns `"
## File: src/IHooksFactory.sol ## Struct: HooksTemplate /// @dev Asset used to pay origination fee address originationFeeAsset /// @dev Amount of \`originationFeeAsset\` paid to deploy a new market using /// an instance of this template. uint80 originationFeeAmount /// @dev Basis points paid on interest for markets deployed using hooks /// based on this template uint16 protocolFeeBips /// @dev Whether the template exists bool exists /// @dev Whether the template is enabled bool enabled /// @dev Index of the template address in the array of hooks templates uint24 index /// @dev Address to pay origination and interest fees address feeRecipient /// @dev Name of the template string name ## File: src/types/LenderStatus.sol ### Struct: LenderStatus bool isBlockedFromDeposits address lastProvider bool canRefresh uint32 lastApprovalTimestamp ## File: src/access/AccessControlHooks.sol ### Struct: HookedMarket bool isHooked bool transferRequiresAccess bool depositRequiresAccess uint128 minimumDeposit
## File: src/access/FixedTermLoanHooks.sol ### Struct: HookedMarket bool isHooked bool transferRequiresAccess bool depositRequiresAccess bool withdrawalRequiresAccess uint128 minimumDeposit uint32 fixedTermEndTime ## File: src/access/MarketConstraintHooks.sol ### Struct: TemporaryReserveRatio uint16 originalAnnualInterestBips uint16 originalReserveRatioBips uint32 expiry ## File: src/libraries/MarketState.sol ### Struct: MarketState bool isClosed uint128 maxTotalSupply uint128 accruedProtocolFees // Underlying assets reserved for withdrawals which have been paid // by the borrower but not yet executed. uint128 normalizedUnclaimedWithdrawals // Scaled token supply (divided by scaleFactor) uint104 scaledTotalSupply // Scaled token amount in withdrawal batches that have not been // paid by borrower yet. uint104 scaledPendingWithdrawals uint32 pendingWithdrawalExpiry // Whether market is currently delinquent (liquidity under requirement) bool isDelinquent // Seconds borrower has been delinquent uint32 timeDelinquent // Fee charged to borrowers as a fraction of the annual interest rate uint16 protocolFeeBips // Annual interest rate accrued to lenders, in basis points uint16 annualInterestBips // Percentage of outstanding balance that must be held in liquid reserves uint16 reserveRatioBips // Ratio between internal balances and underlying token amounts uint112 scaleFactor uint32 lastInterestAccruedTimestamp ### Struct: Account uint104 scaledBalance ## File: src/libraries/Withdrawal.sol ### Struct: WithdrawalBatch // Total scaled amount of tokens to be withdrawn uint104 scaledTotalAmount // Amount of scaled tokens that have been paid by borrower uint104 scaledAmountBurned // Amount of normalized tokens that have been paid by borrower uint128 normalizedAmountPaid ### Struct: AccountWithdrawalStatus uint104 scaledAmount uint128 normalizedAmountWithdrawn ### Struct: WithdrawalData FIFOQueue unpaidBatches mapping(uint32 => WithdrawalBatch) batches mapping(uint256 => mapping(address => AccountWithdrawalStatus)) accountStatuses ## File: src/libraries/FIFOQueue.sol ### Struct: FIFOQueue uint128 startIndex uint128 nextIndex mapping(uint256 => uint32) data ## File: src/spherex/ISphereXEngine.sol ### Struct: ModifierLocals bytes32\[] storageSlots bytes32\[] valuesBefore uint256 gas address engine
## File: ../src/interfaces/IWildcatSanctionsSentinel.sol ### Struct: TmpEscrowParams address borrower address account address asset
## File: src/interfaces/WildcatStructsAndEnums.sol ### Struct: MarketParameters address asset uint8 decimals bytes32 packedNameWord0 bytes32 packedNameWord1 bytes32 packedSymbolWord0 bytes32 packedSymbolWord1 address borrower address feeRecipient address sentinel uint128 maxTotalSupply uint16 protocolFeeBips uint16 annualInterestBips uint16 delinquencyFeeBips uint32 withdrawalBatchDuration uint16 reserveRatioBips uint32 delinquencyGracePeriod address archController address sphereXEngine HooksConfig hooks ### Struct: DeployMarketInputs address asset string namePrefix string symbolPrefix uint128 maxTotalSupply uint16 annualInterestBips uint16 delinquencyFeeBips uint32 withdrawalBatchDuration uint16 reserveRatioBips uint32 delinquencyGracePeriod HooksConfig hooks ### Struct: MarketControllerParameters address archController address borrower address sentinel address marketInitCodeStorage uint256 marketInitCodeHash uint32 minimumDelinquencyGracePeriod uint32 maximumDelinquencyGracePeriod uint16 minimumReserveRatioBips uint16 maximumReserveRatioBips uint16 minimumDelinquencyFeeBips uint16 maximumDelinquencyFeeBips uint32 minimumWithdrawalBatchDuration uint32 maximumWithdrawalBatchDuration uint16 minimumAnnualInterestBips uint16 maximumAnnualInterestBips address sphereXEngine ### Struct: ProtocolFeeConfiguration address feeRecipient address originationFeeAsset uint80 originationFeeAmount uint16 protocolFeeBips ### Struct: MarketParameterConstraints uint32 minimumDelinquencyGracePeriod uint32 maximumDelinquencyGracePeriod uint16 minimumReserveRatioBips uint16 maximumReserveRatioBips uint16 minimumDelinquencyFeeBips uint16 maximumDelinquencyFeeBips uint32 minimumWithdrawalBatchDuration uint32 maximumWithdrawalBatchDuration uint16 minimumAnnualInterestBips uint16 maximumAnnualInterestBips # Contract Deployments Core contract deployment addresses across chains — Ethereum mainnet, Plasma, and Sepolia testnet. ## Ethereum ### Mainnet \[V2]
| Contract Name | Contract Address |
|---|---|
| MarketLens | 0xfDA5C5B96bb198D2fca1A01d759620B64Ae5afE7 |
| WildcatArchController | 0xfEB516d9D946dD487A9346F6fee11f40C6945eE4 |
| WildcatSanctionsSentinel | 0x437e0551892C2C9b06d3fFd248fe60572e08CD1A |
| WildcatHooksFactory | 0xdd7dd3b5076cf89440d05585ff56d246386207be |
| Wildcat4626WrapperFactory | 0xEA6DE11f8F3F83c79bD9d8Db5517fCFDf2Bb148a |
| FixedTermHooks Template | 0x7e49CabA6FB53CDc70CD98829731A2b8d76dfc36 |
| OpenTermHooks Template | 0x4c62B4844C8371f321541E8d564A4B3896cEceC7 |
| WildcatFeeRecipient | 0x35A5D1bd68F3139971027b92c1eE9384A0708554 |
| Contract Name | Contract Address |
|---|---|
| MarketLens | 0xf1D516954f96c1363f8b0aE48D79c8ddE6237847 |
| WildcatMarketControllerFactory | 0xFd31007613C9F671df6A8D4234901324986Bfd13 |
| Contract Name | Contract Address |
|---|---|
| AccessControlHooks_initCodeStorage | 0x42893972c752E731c3457d0d541a2BC6fAdFE751 |
| HooksFactory | 0x6Cb3512b541733d340Aa520b63105586588BD600 |
| MarketLens | 0xb3925B31A8AeDCE8CFc885e0D5DAa057A1EA8A72 |
| MockArchControllerOwner | 0xa476920af80B587f696734430227869795E2Ea78 |
| MockChainalysis | 0x9d1060f8DEE8CBCf5eC772C51Ec671f70Cc7f8d9 |
| MockERC20Factory | 0x54A3103904977DCb3C2fB782059F5431db90C96e |
| WildcatArchController | 0xC003f20F2642c76B81e5e1620c6D8cdEE826408f |
| WildcatMarketControllerFactory | 0xEb97C8E52d7Fdf978a64a538F28271Fd8499b864 |
| Wildcat4626WrapperFactory | 0x0566Fe57682164af689f1440cb3BCEedEe3bf843 |
| WildcatMarket_initCodeStorage | 0xB666C1C67A20814E3eEE15A06780E0821Ae30dd1 |
| WildcatSanctionsSentinel | 0xFBCE262eC835be5e6A458cE1722EeCe0E453316B |
| Contract Name | Contract Address |
|---|---|
| ChainalysisProxy | 0x38056F7fE6396417b191BF7Dc6a3aA04235f3f46 |
| FixedTermHooks_initCodeStorage | 0x59010b706959c15977304C2553F3f4c697A73018 |
| HooksFactory | 0xB46bae25AC6D23148531ed1853a8881FD842E517 |
| MarketLens | 0x7e5d6d9f9a2091dD781118514F5397A8107c81c5 |
| OpenAccessRoleProvider | 0x792F1368f8B8f450c14875eb6FF0028dFc2629b4 |
| OpenTermHooks_initCodeStorage | 0x40217f6e5891C8F1524744C0747e07d316a0c798 |
| SphereXEngine | 0x931fe4a88e1C1f1A7402dF6A40988f38503f1061 |
| WildcatArchController | 0xdb2e0DE97d6d96aa56754635704a4273E0F348ae |
| WildcatCopyOfChainalysisList | 0xfEB516d9D946dD487A9346F6fee11f40C6945eE4 |
| WildcatMarket_initCodeStorage | 0x74b253041BE30b7698B5f69239c271Ea8DB57261 |
| WildcatSanctionsSentinel | 0x37064895ba2C1e269EAF7FF32564818d08903f5B |
| WildcatFeeRecipient | 0x437e0551892C2C9b06d3fFd248fe60572e08CD1A |
*** ## Wildcat V1 Reviews ### [alpeh\_v](https://x.com/alpeh_v) \[Independent Security Review] **Date**: 13 - 29th September 2023 **Scope**: `src/markets/*`, `src/libraries/*`, `src/ReentrancyGuard.sol` **LOC**: \~1,500 **Results**: * 1 critical * 2 high * 4 medium * 2 low * Various notes **Report**: