Farhaan: https://twitter.com/0xfarhaan 
Maple Finance Repo: https://github.com/maple-labs/maple-core-v2/tree/main 
The Bytecode: https://twitter.com/the_bytecode

Welcome to the bytecode, where we look at smart contracts with the people who wrote them.

I'm Irosh Shafoo and today's episode is with Farhan.

I'm the team lead for smart contracts here at Maple Finance.

So yeah, I guess today we'll be covering the Maple Finance smart contracts.

Give you guys a bit of an overview, a lot to get through in an hour, but it will be exciting nonetheless.

We're gonna go through Maple Finance today.

So we're gonna look at invariance testing, how you guys are going to do the operational stuff.

There's a super interesting bike check mechanism to make sure you actually deployed this, the same stuff, or if something changes that for auditors and stuff.

And yeah, we're going to go through some monitoring as well, some health checks that you guys are do after, after deployment.

So yeah, why don't you briefly introduce Maple Finance and then go through the architecture?

Awesome, yeah, you guys can probably see like the architecture diagram on the screen, but yeah, let's do a brief intro of Maple.

So yeah, Maple Finance basically provides on-chain capital debt market infrastructure.

We're also now branching out into managing pools ourselves as well.

But to give you like a bird's eye overview, essentially, we're bringing together 3 parties.

So you can see them denoted by these circles on the left.

So we have liquidity providers, we have a pool delegate and we have a borrower.

So essentially we want to, we want to match liquidity providers with borrowers because the borrowers will borrow some interest rate and then pay that to the pool and then the liquidity providers will obviously be paid for that.

But because we are often dealing with like real world assets or over collateralized borrowing, under collateralized borrowing, we actually support like any mechanism here.

Usually people associate us with this underclass borrowing, but that's just like 1 niche like this other things that we do as well, like we're providing on chain treasuries as well.

So they're the ones kind of managing who can borrow the funds, who's allowed to actually be a liquidity provider as well, especially if we're using a permissioned pool.

So we support both permissioned and unpermissioned pools.

So it's like complete flexibility in terms of like, what is like the scope of the pool.

So to give you 2 concrete examples, you can get an idea of like use cases.

So 1 that I alluded to is treasury management, we call it cash management.

So essentially what's happening is you have KYC liquidity providers, we support US, non-US investors.

The pool delegate in this case would be Maple Finance.

So this is kind of like a unique example of our pool system.

They're a hedge fund, so they use an SPV to basically borrow funds from the pool and they go and directly buy treasury bills.

So they buy treasury bills at whatever the rate is at the time.

So let's just round it down to like 5%, but like 5.5%, for example.

And then they would take a small fee from the pool as like how they're earning money.

Basically, Naples Finance will take a small fee on that.

And then like 4.75 to 5% ish then gets paid out to LPs.

So then because the borrower has this on-chain loan, they have to make payments at a regular interval, whatever the agreed upon loan terms are.

So let's say like a 30 day, payment schedule.

So every 30 days they would pay any interest due And that's just going to liquidity providers.

And then we can get into withdrawal mechanisms separately.

Another example would be our pool with Accru.

So Accru is the pool delegate in this case.

What they're doing is they're underwriting loans to a borrower called Interior.

What they do is they give financing for tax receivables, so IRS tax receivables.

So what that means is there's a company out there in the world that is going to get, let's say, a million dollars back as a tax refund, but they're not going to get it back for another 6 months, say, for example.

So we can provide liquidity via Interior directly to them.

then that $50, 000 is like the profit that's being generated, i.e.

And then yeah, that gets paid into the pool, basically.

And that's like another example of like a real world asset situation.

And I guess a final example, which is a bit closer to home, which we just launched yesterday, is another pool called Maple Direct.

So Maple Direct is managed directly by us.

We're doing over collateralized lending, basically.

So You guys are probably familiar with what happened last year, with the likes of Celsius, et cetera, where they were providing this borrowing service as well.

But everything went under because people were re-hypothecating, there wasn't transparency.

Someone didn't know, oh, they borrowed from Genesis and then they borrowed from Celsius.

And, you know, 1 person could have borrowed with the same funds from like 10 different providers.

What we're doing here is using our on-chain infrastructure to do transparent lending on-chain with this now.

So someone, so yesterday we put out our first loan for 75K to this borrower.

And the borrower put up collateral of Bitcoin, which they put up like about 250% collateral, so about 10-ish Bitcoin or 7 Bitcoin, if I'm not mistaken, against 75K.

So it's over collateralized and we're using an on-chain, sorry, we're using a custodian like a BitGo in this case, to do this.

So that way we can support native assets like Bitcoin, because of course you can't have native Bitcoin on Ethereum, which is where we're based.

So yeah, that's a, that's a cool example of how we're using on-chain infrastructure to do this transparent lending now, because now on-chain alone will say, Yeah, they're borrowing 75K.

The website will give you the information of like the custodian and how much is being collateralized and by what, and that can't be rehypothecated now.

Our system is quite configurable and yeah, we do support a lot of use cases.

So should we go over the architecture briefly so that everyone can get an overview of what's going on?

I guess the way that I will kind of start describing this is, let's think about this like you're an ERC20 token.

What are the contracts that I'm going through and how is this working?

So the blue contracts are instances of an actual pool And then we'll cover the factories in a moment as well.

Yeah, I think, cause yeah, I don't want to lose the whole overview, but can you clearly see that or a bit more?

Now this pool contract follows the 4626 standard.

Cause we do want to interrupt with the rest of the ecosystem.

Now, we'll talk about it through the lens of an open term loan.

The system supports 2 types of loans, fixed term and open term.

With fixed term, up front, you need to say when the end date of the loan is basically, because you define it by the payment terms, like how long between payments and how many payments.

So let's say, you know, 30 day payment intervals and maximum 6 payments.

How long the term would be, or you do an open term loan where you say, Hey, I want to borrow this amount and I'll pay interest every 30 days and then I'll only pay back the loan when it's cold.

So that way, yeah, someone that's continuously needs liquidity can have it and then when we need the principal back with the interest, we can call it as well.

So yeah, pool contract, USDC goes in there.

Now the pool delegate interacts with mainly the pool manager contract.

So the pool manager you can think of as the central nervous system of the entire protocol.

So you can see like all these interactions happening with the pool manager.

On the pool manager you would have functions like, you know, funding a loan, etc.

So what a pool delegate would do, that's underwriting the loan, would fund a loan.

So let's say, imagine this loan is already created.

So they would pass in the loan address, confirm the terms, and then just fund it.

And then what would happen Next is funds would get pulled from the pool via the pool manager, get sent over to this thing what we call the loan manager.

Now the loan manager we can cover as well when you go through the contract code, but it's a really interesting way that we've kind of developed to ensure that there is like a clear issuance rate in terms of the interest that's being paid out.

So actually let's draw this as an example.

So 1 issue we had previously is, so let's imagine a chart.

So we've got time and we've got issuance.

So let's Imagine a pool has a million dollars in it and you've given out a loan for a million bucks and you've got 10% interest that you expect over a year and a loan pays out every 30 days.

What would happen previously is the issuance would be 0 as in the interest per second being generated would just stay static.

Suddenly at time T there would be, you know, I don't know, Like, you know, let's say a thousand units of an asset suddenly paid.

This is something that obviously you can front run and add like MEV risk.

Cause now I imagine, Hey, I know suddenly there's going to be a big payment coming in of interest.

Let me deposit into the pool because I get equal shares.

Like someone can just deposit and get a lot of interest suddenly and then like exit the system.

So what the loan managers do, both for the open term and fixed term, is they smooth out the issuance rate.

So it looks more like a linear graph like this, Because essentially what the loan manager does is it figures out, okay, this loan is over this duration and I expect this much interest to be coming in over an interval.

So the units for this chart would be like the issuance per second.

So in this case, it'd be like, you know, a thousand USD per second, maybe.

So that's what the loan managers are doing.

So if we can zoom back in, I think we're at like

Pool delegate has funded alone by the pool manager.

The loan manager does the calculation to figure out how much the issuance rate should be, what to expect, sets up the loan parameters, and then gives the funds to the loan.

So now the loan has the funds, or actually in the case of open term loans, the funds gets directly sent to the borrower.

So that's kind of like a brief view of how the ERC20 token or USDC in this example goes through the system.

So let, let's like zoom back now and like, what are the other elements in this system?

So to create a pool, you go through this pool deployer contract.

So let me use a slightly less thick background.

So yeah, the pool delegate would call the pool deployer And the pool deployer would then call all these factories to deploy a pool.

So you can see the pool manager factory gets called, it ends up deploying a pool manager, pool factory.

Withdrawal manager, factory deploys a withdrawal manager, fixed term loan manager, factory fixed term loan, open term loan, manager, factory, open term loan.

So we use proxies extensively in our system.

So all these contracts that I just talked through in the blue, these are actually unique instances of proxies that are then pointing to their relevant implementations.

And by using all these different factories, we can actually support different versions.

So say we just want to go update our OpenTerm load, the implementation for it.

So let's say it's on version 100 and we want to update it to version 200.

We would just deploy a new implementation, register that implementation on the factory, call the upgrade function on the implementation, which will then upgrade the proxy to point to the new implementation via the factory.

So yeah, proxies are used extensively and we're using transparent proxies basically to do that functionality.

So that's like the key essence of the pool and like the journey that different ERC20 tokens go through.

Then there's like a few things we have for like security purposes.

So we have this contract, which you might've seen up top here, Maple Globals.

So Maple Globals holds a lot of information like who's a valid borrower.

It's got security functionality like circuit breakers where we can pause either the whole protocol, a specific contract, or even a specific function, which I think is quite cool.

So we have like super granular circuit breakers because of Maple Globals.

And yeah, you can see there's like a governor multi-sig that manages the Maple Globals contract.

The Maple Globals contract is actually also a non-transparent proxy, as in it doesn't have, it has the set implementation function on the proxy itself.

And yeah, and this is like, this is like 1 of the few different kinds of proxies that we manage as part of our system.

So I think, yeah, that's a high level overview of the system.

I appreciate there's a lot going on and it's hard to maybe grasp initially, but yeah, that's the TLDR of the architecture.

I guess, yeah, Do you have any questions that might be useful for the viewers?

We should definitely take a look at, at the Maples globals, circuit breaker logic.

On that note, let's get into the code and actually, yeah, just cause you mentioned it, let's go into Maple globals.

So there's a few things going on with global.

So actually maybe let's talk through how we structure our repo.

So the repo that I'm covering is MapleCore v2.

This is public, so anyone can see our code.

We are heavy Foundry users, big fans of Foundry.

I think we've been using it almost since it came out.

We've been working with them to kind of help define some features and stuff as well.

We worked with them to help develop like the intervariant test suite as well.

Otherwise we're just using like batch scripts to kind of help us out.

Let me hover that and make this slightly bigger so you guys can see.

So what we do here is we import different modules and put it all together and do integrate it like system-wide integration testing in this repo.

So an example of a module is So all the logic to do with pools, for example, like that we have over here, this is its own module.

Everything to do with the withdrawal manager is its own module.

Everything to do with fixed term loans is its own module.

Everything to do with OpenTerminons is its own module.

So you can start saying, yeah, there's a lot of moving parts and modules in the system.

Everything to do with liquidations is its own module as well.

So we have an address registry, So this is kind of like where we keep all our on-chain addresses.

We also have our own ERC-20 implementation.

So 1 thing you'll note is we don't actually have that many external dependencies.

So this took inspiration from like Solmay, OpenZeppelin and DSS.

But yeah, the only external elements we have is basically listening to a chain link price feed, which we rarely do as well.

And using Forge standard for testing, but that's kind of like a testing dependency.

Otherwise we have like 0 external dependencies.

So first of all, could, could you zoom in a little bit again?

But the question is why, why re-implement the ERC20 for example, Is there something you had to change or what's the reason?

So it's just we didn't like the OpenZeppelin implementation completely, didn't like the Soulmate 1 completely.

And we, we are also quite particular with how we like format and read our contracts.

So the way that we use like headers, like we use 140 characters as like the maximum length.

The way we kind of just like organize storage variables or even how we rewrite our functions.

We're just like with formatting and everything we're very particular because our goal is to make our code super legible.

Like the priority is legibility because we believe with with legibility will come good security to the sense that if it's easier to read, it's easier to audit, it's easier to internally audit as well and to get a more intuitive understanding of what's happening in the code as opposed to like having a lot of complexity.

And because we write our own ERC-20, we know what it's doing completely, where there's no like, oh, gotcha, this specific function has this quirk to it of like some external library that we're using basically.

So that's the ERC-20 and then, yeah, like I mentioned, so fixed time loan and fixed time loan manager, their own modules, globals, open term loan and loan manager pool and withdrawal manager.

So yeah, we've got this sub module system that we're using.

So these are just Git submodules that you can add using the Git submodule command, the Git submodule add.

The great thing about using this modular system actually that we find is, we can support different versions of contracts very easily.

To say we have open term loan where it's got a specific implementation.

So you can see it says V1 for this open term loan.

So let's say we create a V2 with different functionality and we want to test both within our monorepo.

We can just create a sub module where we say, you know, open term loan V1, get, add the submodule at that specific commit, and then do the same for V2.

So that was like another rationale for why we want to use the submodule system, because we might have different implementations of versions of the contracts out in the wild at any given point.

And we do want to test both versions at the same time to just check like there's no issues.

So that's like another rationality using the sub-module system.

But with that said, let's get into globals and show you that granular pausing that I was talking about.

So actually, let's go to the storage variable.

So, yeah, another thing I guess I can show you is how we kind of manage our proxies.

So yeah, this is a non-transparent proxy.

So you can see we use submodules within our submodules to kind of make our life easy.

So this is our own implementation of a non-transparent proxy contract, where the set implementation function is an admin function that's actually on the proxy itself.

I appreciate OpenZeppelin uses slightly different terminology.

Their version of a transparent proxy, I think, is what we call a non-transparent proxy and what they call UUPS is our version of a transparent proxy.

So yeah, this might get confusing if you're familiar with OpenZeppelin, but here we're basically saying this has this implementation on the non-transparent proxy.

So this is what Globals utilizes under the hood.

So these are the main pause-related functions.

So you can see we can either pause the whole protocol, so via set protocol pause.

So, either the governor or security admin can call this.

So, what this will do, and we'll see in the other contracts is the other contracts have a modifier usually or a call-out check just to check whether the protocol is paused and if that's paused then none of the functions work.

So let's say for some reason even though the pool delegate is a trusted actor within the system, actually, let me maybe clear out some of these so it looks a bit less messy.

But yeah, let's say the pool delegate for some reason goes rogue.

Maybe we just decide to pause the pool manager contract so they don't have all the functionality that they would.

So yeah, that's what setContractPause lets us do.

And the way that the function specific pose does is it's kind of like a negation the opposite.

So we would pause the contract first, and then we would pass in specific function signatures to unpause.

So all the functions are paused on a contract, and let's say we want to unpose the upgrade functionality because we want to upgrade the contract ourselves, this is how we would then unpose the function.

So the way this works in practice is if we go to is function paused where else is this is this part of course yeah so this is where the check basically happens.

So first it'll check if the protocol is paused or if the contract is paused.

So if the protocol is paused, it'll return a true automatically.

Otherwise it'll check if the contract is paused.

See all shafu transcripts on Youtube

The Bytecode #8 - Farhaan - The Bytecode