Jango: https://twitter.com/me_jango
Juicebox repo: https://github.com/jbx-protocol/juice-contracts-v3
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 Yorush Shafoo and today's episode is with Django from Juicebox.

So Django, thanks for taking the time, man.

I love talking about the nitty-gritty of what makes codebases special.

Yeah, so Django's gonna walk us through the Juicebox Contracts v3.

So yeah, Django, why don't you briefly introduce yourself, introduce Juicebox, and then we can directly jump into the code.

So Juicebox is a protocol that allows folks to program conditions according to which their project can receive funds.

So like what happens when you receive funds and under what conditions funds can be accessed from your project by yourself or from a community.

It's useful to create these patterns with familiar levers that can express relationships between producer and consumer, between 1 community member and another, between a customer and employee, an investor and a entrepreneur.

And if we can reference similar patterns, then we can kind of create these networked projects that can talk to each other with financial rails that make sense and can wield a lot of power to share in a community effort.

Usually projects are community efforts that are taking in funds in 1 way or another.

So right now we're kind of in the process of shaping this juicebox language for intentional competitive use.

But the very baseline of what Juicebox is, is just a flexible language for expressing these if this, then that conditions that make up a project's finances.

The original intent behind the project was to create a system where I can express up front how much funds I need, and then I can accept payments into a project.

And if there's funds over what I was intended to raise in a particular time period, then everyone who helped me raise can essentially get a rebate on their initial price that they paid in to push everyone's price towards 0.

The end result is I get what I needed and everyone, the more people we paid, pay less.

So everyone pays less, but we still fulfill the mission.

This was a few years ago when I was prototyping and writing the first version of this.

And then a really inspiring community of developers has come through and really expanded that initial idea into something much more powerful and generic.

And it's feeling like it's at a very stable place for to now be used to build applications on top of, which is what the current kind of topic du jour is, is how can we use these tools to build powerful applications and express business models.

So we're going to focus in on 1 particular contract that has the meat and potatoes of what it means to interact with Juicebox.

If we're curious to learn more over time feel free to reach out or poke around in the codebase.

But essentially what we're going to be looking at mostly is this contract called the payment terminal, which is where when you pay a project, you're interacting directly with this contract.

All the funds stay in this contract, so it's the 1 that has, it's what has most concerns from security perspective.

If you're trying to access funds from your project, you're going to do it through this contract here.

It's called JB Payout Redemption Payment Terminal, and then 3.1.2 is the current version of this 1.

Basically it's a generic JB payment terminal which is the standard baseline component of how payment terminals are expressed via this very simple interface here.

So to be a payment terminal in Juicebox world, all you need to do is implement a pay function, which is the function that folks are expected to call when they're trying to pay your project and have some reciprocal action take place.

For instance, you pay my project and the project will mint, let's say, a million of its tokens and issue them back out to the payer.

That's a very baseline juicebox interaction.

And so that kind of stuff will be implemented in pay.

And there's, you should also implement an add to balance function, which is I just want to deposit funds in a project, but have no reciprocal action take place.

And then there's some view functions here that you need to implement to let the outside world know if you're going to, if you're accepting a particular token, what the currency is for that token, how many decimals, etc.

So very baseline, basic payment terminal functionality, and then there are layers of functionality we can add to this payment terminal to get to the contract we were looking at, which is a payout redemption payment terminal, which suggests, hey, we can also manage payouts from this.

So once the payments come in, you can now manage how those payments are leveraged.

And then redemptions means there's also some functionality in here that allows token holders that receive tokens from, for example, from after having paid.

So I pay 1 ETH to the project, I receive a million project tokens, I can burn the million project tokens and receive the one-eighth back, or some version of that rule set depending on what the current redemption criteria is for the project.

Yeah go for it, Please jump in at any point.

A question regarding the versioning system.

Why do it like this and just why not use Git for versioning or something?

Why keep track of the contracts like that?

So the kind of core philosophy of how these things are architected is that anyone should be able to roll their own payment terminal at any point.

Juicebox DAO is sponsoring the development of a few versions of these payment terminals, which are the canonical versions, which sites like juicebox.money use.

But if you are a project running on the protocol, you should have the ability to write your own payment terminal and then migrate your funds and operations from whatever payment terminals you're currently using into your terminals of choice.

And so to take a step back in the architecture, I don't have a kind of clear diagram, full picture, but if we go kind of up the hierarchy of generic contracts, we get to this JB directory contract, which has a simple mapping, for example, of a project ID, which is this 256 here, to an array of IJB payment terminals, which is that very baseline payment terminal implementation that folks are responsible for rolling if they're rolling their own.

So, from the JB directory, you can get a list of all the payment terminals that a project is currently accepting funds through.

In the directory here, the project can set the terminals that they are accepting funds through so the outside world knows, hey, I want to pay this project.

I don't necessarily, I don't really care which terminals are using.

I just want to know that they, for instance, have an ETH payment terminal, right?

So then I can go and get, I can go and get like the, where are we, where are we, the primary terminal of a project for ETH, for instance, and then independent of what payment terminal a project is using, it can resolve to the 1 I should pay, which gives us a lot of flexibility and gives projects flexibility to start somewhere that might be more convenient and then eventually evolve as their idea grows into something that needs something more proprietary for themselves.

And so the versions that we've created ourselves here, they aren't, they're presented linearly because they are linear improvements.

Like if you see 3.1.2, you should probably use that instead of 3.1.1, because it either has a slight kind of edge case tweak or introduces an amendment to some data passing standard that maybe broadens functionality or something.

But there are projects that are on all of these versions because they deployed them and they haven't migrated, or they deployed in a previous version.

And the reason why JuiceboxDAO created a subsequent version was for a reason unrelated to their project's operations, so they don't really care to migrate funds over and send that transaction.

But in either case, if you go to the JB directory, you can kind of get a sense of which terminals the project is currently accepting funds through.

And projects have total freedom without Juicebox DAOs control or care as to which PMA terminals they're operating under.

If we go to back to 3.1.2 just to quickly paint a little bit of a deeper picture here.

There's a call to migrate so here's a basically here's like a how functions are written and organized in this contract.

So migrate project to another payment terminal, for instance, we're gonna require permissions.

So whoever's calling migrate has to either be the owner of the project, which means that the address that owns the project's admin NFT, each project in Juicebox is represented as an NFT.

JB Projects is a 721 votes, so every time you create a project you're basically creating a new NFT in this contract and whoever owns that NFT has that admin capacity.

So in Migrate, only the project owner or someone who operates, who the project owner has given operator permissions to migrate terminal.

So we have this operator standard where project owners can give any address, any number of permissions to do things on their behalf.

And then we're going to do a really simple just move funds from this contract into the destination contract and make sure the balance is internal accounting is in check.

It's not guaranteed since it's not in that core spec, but it's pretty standard in the ones that Juicebox DAO encourages folks to use, since we really want to make sure that we can evolve and that if any risks do appear, We do our best to test things thoroughly and audit things thoroughly and make sure things are safe and sound.

But, you know, I think all developers know that things pop up sometimes seemingly out of nowhere, and we need to be very prepared to make decisions.

And 1 of our juicebox DAOs principles is we aren't going to make decisions for you.

Every project owner has total control over their funds, over their project.

So the best we can do is suggest moves for you to make, but you have to send those transactions yourself as a project owner.

Juicebox DAO is a project on the Juicebox protocol.

So it is also making these same decisions alongside everybody else.

This is the general migration idea behind what's going on.

And we leave them all in the repo here to show that here's the progression.

We don't intend for this list to grow infinitely long.

Most of these versioning efforts were small edge case tweaks that we needed to improve to make the protocol more like guaranteed peace of mind for longer.

All kind of feature additions or extensionality are made available through other hooks and whatnot, which hopefully we'll go through here in a bit and get to at least 1 of these core hooks.

Now payment terminals are still a little bit abstract to me, so could you maybe give a specific example why a project would have several payment terminals?

So most projects don't, let's start here.

And I will actually go through this inheritance stack just to be clear.

So a payment terminal, as we saw, the core payment terminal, can accept any number of tokens, right, and just has to tell the world that it accepts it or it doesn't.

Then we have a, we've scoped that down to this idea of a single token payment terminal, which is it's a payment terminal that essentially says I have only 1 token, here's how many decimals it uses, here's the currency, and then in all those view functions that the core implementation needs, it just returns the fixed value.

So now we've kind of scoped it down to 1 token.

Now we've added all this other information as we just saw, payout redemption.

And then what we're gonna do finally is we're gonna introduce 2 things.

We have a JBEth payment terminal 3.1.2 and a JBERC20 payment terminal

This basically takes this abstract class and just implements how do I transfer in this particular token implementation.

ERC20 has the same thing, but obviously transfers happen a little differently.

And so the idea here is, though most projects currently only have 1 payment terminal, they're ETH payment terminal, and the reason you'd want to have multiple payment terminals might just be to evolve from 1 to another.

So maybe I start with 1 payment terminal and then I switch to another and I switch to another but I always just have 1.

What you can do at any point is you can add other payment terminals that accept different currencies into your payment terminal world And these are all contracts that now hold your project's balances, which means if you're a community member of this project, i.e.

You own the token of this project, a core juicebox principle is you should have access to the project's funds in some capacity, or rather the project owner should be able to give token holders at least some access to the project's funds.

And so having this having multiple payment terminals where you're receiving different kinds of tokens in makes it makes it such that you can not only receive payments in those, but also I can burn my project's tokens, let's say, into the ETH payment terminal, but I can have the balances of any number of my payment terminals taken into account to determine how much funds from that ETH payment terminal I have a right to.

And so it kind of allows us to start to glue these things together while still giving folks with the token access to the full picture of what's going on.

Okay, so you have to loop over every payment terminal.

Is there like a, do you guys set a hard limit on the amount of terminals 1 project can have?

Anyone can essentially bring their own risks and opportunities in that sense.

Like I said, everything that has been facilitated thus far has just been 1 payment terminal.

So, a lot of this is kind of designed such that we can afford ourselves growth and projects can afford themselves growth.

When I say we can afford ourselves growth, I mostly mean Juicebox DAO as project number 1.

But when we build for ourselves, we're kind of also building these capabilities for other projects going on.

And a lot of folks in Juicebox DAO are also building other projects.

So, like, hardly anybody's focused entirely just on juicebox DAO.

We're all building juicebox DAO almost as a means to an end to create this set of tools that can empower other projects that we're working on.

But this is also kind of a thing that hasn't

it's hard to find concrete examples because it hasn't been used yet.

I think the end of this year we'll probably see a few new pockets of kind of opportunities and risks exposed from Juicebox to Howzend.

We've been doing a lot of more, a lot of work in this contract components called the pay delegate, which is essentially a pocket of code that you can bring into your project that gets executed every time someone pays your project.

For instance, oh, if someone pays me between 0.1 and 0.5, then do this extra thing, or only allow these addresses to pay during this time frame so you can kind of bring custom components.

We've been doing spending a lot more time supporting builds that kind of explored that little pocket of experimentation.

But that's feeling pretty sturdy, pretty good.

I think the next thing that folks are interested in are multi-terminal projects.

So how can I accept stable coins as well as native tokens to a chain, and then also multi-chain as well?

So how Juicebox now is thinking about multi-chain is less so like, which chain do we want to be on?

Or do we want to roll our own chain and more so like how can an organization this abstract idea of an organization exist across any number of chains while still maintaining the core value prop of its token being that it can access the total amount of what that project's value is.

The total amount across chains of what this project has at its disposal, what its total treasury is.

So those 2 questions are really going to blow open this idea of what a payment terminal kind of is relative to a project.

But for now, everyone just uses the JBE payment terminal.

So a lot of these contracts, there aren't even folks sending funds through right now.

So I think it'd be fun to do a deeper dive into how a payment works.

So we can kind of just walk through a payment, and then I think that'll take up a good chunk of the hour.

Maybe we can zip through, and if we do, then we'll do maybe a redemption call as well.

But this is a good starting point for understanding how the protocol thinks about data structures and how the protocol makes certain choices and trade-offs.

So this is the external call when you are trying to pay a project.

This is 1 of those core must-haves in a baseline JP payment terminal.

The payment terminal can be used by any number of projects.

All values are kind of mapped to by projects.

All funds are kind of stay in this contract, like across all projects.

You can send the amount here which gets overridden if you're sending ETH.

So this again is an abstract contract that it works the same if you're sending ETH or ERC20s.

So a lot of the stuff kind of here we see some pivots that are that depending if you're not sending ETH you have to transfer the ERC20 in otherwise go ahead and just override the amount with the message value.

You send the token here but again this is a single token payment terminal.

It's just in the case of the ETH payment terminal, for instance, just takes ETH.

So we're going to ignore the fact that you set a token.

It already knows what the token it expects is.

The beneficiary is the address that you want to benefit from any reciprocal actions.

Like if you're trying to mint an NFT, or if you're trying to get tokens in return, they get sent to this beneficiary.

Min tokens returned kind of gives some expectations.

So the protocol may think it should send you X amount of tokens but you're expecting a little less, a little more than X, so the function would revert.

Each juicebox project doesn't necessarily need ERC20 tokens, but each juicebox project can account for fungible tokens.

And it does so using an internal accounting mechanism that kind of makes each of these interactions a little cheaper such that the pay function can be very cheap.

It also makes deploying projects cheaper.

If you don't need to deploy an ERC20, why do you need to deploy a project?

Any time after you deploy a project, you can mint an ERC20 token, and then folks that have balances can claim them into the ERC20 form.

So this flag is just like, if you make a payment and you're like, just give me the claimed version, give me the full ERC20 right out of the bat, even though it might cost me a little bit more gas for that operation.

Otherwise, it'll just be stored and you can claim and batch later.

And then some memo to send to the event, and some metadata that gets forwarded to any extensions that the project rolls.

Question regarding the first line of the function.

Prevents unused var compiler and that's the complaints.

Yeah, it's just, yeah, it's like you could, you can get rid of this and change net spec elsewhere but it's common enough that we just kind of left it in

okay the question I have which I which I would find interesting, does this cost gas?

Does it actually put token on the stack or something?

As far as I know, if someone has an inkling, or kind of thinks it does, please let me know.

It's kind of been a while since we wrote it, but this was like a thing that we were considering for maybe like half a day.

And then we were like, yeah, let's just do this because it makes it pretty explicit that it's not being used.

Solidity tidbit, or maybe we're just silly, and it does cost too much gas for some odd reason and everyone's been paying too much gas.

Please inform us if we are weesh about this.

so once it's normalized some stuff, depending on which tokens this terminal is responsible for coordinating, then we're going to go in and do this internal pay function.

Maybe interesting for some folks, Django, the balance before and the amount stuff This is because some ERC 20s take a fee or something in the middle, right?

So again, this is a very generic abstract Abstract terminal and we don't know which kind of tokens are going to implement it.

This is just in case this transfer from is a virtual function in this abstract class that we saw how it was implemented earlier in ERC20.

Anyone can roll another version of this that does something more clever and transfer from like take a fee here or whatever and so this balance before is just saying I want to know how many tokens I have beforehand I want to do the operation and I just want to overwrite the amount that was sent here to the exact difference And then meanwhile I want to send the amount into the transfer from so that it can actually happen accordingly.

Under most cases this isn't necessary and you can just keep amount as is and go on, but this is like a like it's like all edges all edge cases covered situation.

So let's go into this internal pay function, which has the, all the good stuff in it.

It takes basically the same stuff so nothing new here and it's responsible for returning how many tokens the beneficiary got.

I'm gonna go through line by line And we'll talk about it.

I think it's also the most important thing you should understand if you're either starting a Dues Fox project or paying 1 is like what exactly happens.

It makes sense to do this due diligence if you really care about the software you're using.

And it's the real benefit of open source software is you can never ask your bank for the line by line of what happens when you receive a payment or how it gets dispersed.

But here we can talk about it out loud on calls like this, and it's amazing.

We are 1 of those people who do the sanity check to make sure you're not sending an empty beneficiary on accident.

A lot of people choose not to do this kind of check, which makes a lot of sense.

Because, I mean, if you mess up something, usually the consequences are a little worse.

And we do try to be somewhat helpful along the way and try to help folks not set up botched treasuries or botched payments.

So we've talked about the core Juicebox interaction point, which is the payment terminal.

The Core Juicebox data structure is a funding cycle.

So every project is always in a funding cycle.

So and your funding cycles are either fixed, a fixed duration, meaning like a 14-day funding cycle, which means here I am in this funding cycle and then 14 days later I have an opportunity to change the configurations of my next funding cycle, but I can never change the current funding cycle I'm in.

Or I can be in a flexible 1 where I'm in a current funding cycle, but I can change it at any time to be in the next funding cycle.

All a funding cycle is is a set of rules.

It's a data structure that encapsulates all of the rules that a project is currently abiding by.

This includes how many tokens should be issued per unit of payment coming in.

It includes how should redemptions work, like how many tokens should I get in return if I burn a project token?

So we'll get to little points where we can see these things come out, but we want to get a reference to the project's current funding cycle so that we can operate accordingly.

Then we have some dreaded stack-too-deep blocks.

Always praying to the stack-too-deep gods, but hey, it worked.

And then we are going to – so Here's kind of a tricky but maybe sensible thing to consider.

I don't know if I can really rationalize it in kind of 5 minutes, but I'll try.

All the funds stay in the payment terminal, but each Payment Terminal has a Payment Terminal store, which isn't like a shopping store, it's like a storage store.

It's where the information is stored for this Payment Terminal.

And in the store, we'll see where balances are accounted for and all the actual data gets stored.

In the payment terminal, it'll just receive payments and distribute payments accordingly.

The 1 big thing we want to do here is go to the store and record the payment.

So record the payment from payer, how much was paid, which we bundled up here.

Bundled amount is just the amount plus a bunch of context about what kind of token was maybe a product ID, base weight currency.

And it's definitely technical and in the weeds, but back on the note of multi-term, multi-terminal, What base weight currency is, is imagine like I have an ETH payment terminal and it says, you give me an ETH, I give you a million project tokens back.

And then imagine I also have a DAI payment terminal and it says you give me 1 DAI and I give you a million tokens back those 2 terminals are incompatible because You get a million tokens back at very different rates Because 1 die is not 1 piece And so let's consider a world where instead, the die payment terminal, although it's its main currency is die, its base weight currency can be ease such that if I pay 1 DAI into the terminal, I get 1 ETH's worth of DAI, rather I get, I convert the currency into the base weight currency to determine how many tokens get issued out.

So now I can have any number of terminals that take in any number of currencies and they all can be normalized.

So token issuance, which uses this like token weight, this idea of a weight, all uses the same currency.

So now, I can actually distribute my project token fairly across any number of token values.

So I just wanna tell the payment store what that base weight currency is for this terminal.

See all shafu transcripts on Youtube

The Bytecode #9 - Jango - Juicebox