Open-Sourcing 0x-Parser: Best Practices for Web3 Libraries | Henry Zhu - 0x.org

[Music] hello everyone hi my name is Henry and I'm a software engineer at ZX and today I'm going to be talking about open sourcing a library that we have published at zorx it's called zorx parser we're going to talk about at a high level what this library is and then why it's useful and then we're going to talk about some of the best practices of Open Source and in particular I'm going to focus on automating releases now Auto automating releases are very important because as your team grows everyone has to learn about a manual process and it's not very scalable it's quite brittle at the end we're going to go through a little demo as well so before that I'm going to talk about what zerox is so we're a DEX aggregator uh API so we provide infrastructure for swaps in the middle here we have our Flagship product matcha XYZ and around it we have a couple of wallets now if you've used any of these wallets before and used their swapping feature you've probably used Z's API so we have Phantom got metamask and coinbase wallet now when a user makes a swap on any one of these apps the result is typically a transaction hash and it looks something like this oh wa that's the next slide um they're going to make a request to zerox API so in here we have the URL this is a indication that the user wants to swap 100 usdc for we and so the request goes out to zerox API and what you get back is a data structure that you can submit directly on chain so that's why we have a send transaction function call here and the quote we get back from zorx API has two Fields as a two field which points to the zorx smart contracts that will execute the Swap and then the data field that's the call data that encodes the details of the swap including the route and the amounts and the slippage here's the transaction hash when a user makes a swap the App application will get a transaction hash and typically these apps will have a link linking out to a Blog Explorer like etherscan URL might look like ethers scan.com sltx SL this long string but most apps want to show users some details before they go to a block Explorer so on Macha it looks something like this and on coinbase wallet Phantom and these other apps that use zorox API you want to do something very similar you want to show an amount and the tokens that were swapped and that's where zerox parser comes into play it's very simple the library exports a single function called parse Swap and it only only takes in two arguments it takes in the public client and then the transaction hash the public client is a connection to the ethereum network it's typically powered by RPC provider like Alchemy or node uh Alchemy or quick node the second thing we're going to pass it is that long string we saw earlier the transaction hash and with those two things a direct connection to ethereum and the transaction hash we could fetch data so we have two blobs of data here we got the transaction and the transaction receipt now we take that data and we pass it into some other parsing functions and we're not going to dig too deep into the code here uh the code's like about 500 lines of code you can check that out on GitHub and I'll have the link to the GitHub at the end uh but essentially these functions will return human readable data that we can show to our users so we get a result and the result looks something like this this is a object with two properties token in token out very straightforward now it's important to parse these transactions after the swap has occurred because due to market conditions and slippage the final amount can be different than the quoted amount so in this case the user could have gotten a little bit less we for example 0.024 instead of 0.025 depending on Mark and conditions or maybe they set a high slippage tolerance so that is the library that we're going to publish or that has been published um and then we're going to talk about some of the best practices of automating the uh release process and this all starts with sematic versioning uh if you're developers here you might have heard of this before you might know what this is on the on my leftand side there's the versions for zerox parser and on the right we have a sample of a version for example we have 1.2.

4 now each one of these numbers represent a type of release you want to do so for example if we have a bug fix and we want to release that we're going to increment the patch number if we have a non-breaking feature we're going to want to increment the minor version number and finally if we have a breaking change and that means the uh consumers of our app will have to do something in order for them to upgrade we're going to bump this major version number up so this is the foundation to automating our releases we're going to combine this with something called semantic sorry we're going to combine this with something called conventional commits now conventional commits is not a package or anything like that it's not an npm Library it is simply a way to write your commit messages now you're going to write it as normal but you're going to prefix your commit messages with what we call a standard heading these standard headings are adopted by many open source projects and has been popularized by Google's angularjs here I have a set of commits and each one of these commits have a green underline and that underlines the conventional commit standard heading so I if you have a bug fix you're going to prefix it with a fix standard heading and then going down we have feet and then feet is short for feature and then we have feet exclamation point that's the exclamation point indicates a breaking change so we're going to tie each one of these conventional commits to a semantic version number so a fix correlates to the patch the patch number feet correlates to the minor number and then anytime we see an exclamation point that's a breaking change that correlates to the major number and so with these foundations in place we can write scripts to automate our release process to deploy to to run our C but also to deploy to npm or any registry but we don't have to write those scripts there are packages out there to do that for us two of them are change sets and release please I'm going to talk about release please that's what we use in in our repo and essentially what this is is um a set of GitHub actions that will automate your release process and once you get that set up it all starts with a normal PR this is like any PR you would normally do again the only difference here is we have a standard heading here it is fix colon so this is a bug fix now once we merge that PR releasee please is going to automate the creation of what we call a release PR so this will happen automatically uh a GitHub action will open a PR and this is going to be the preview of your release so we're going to check the version number here it's 2.7.1 so we you know we bumped up the patch uh we bumped up the patch because we fixed the bug so it used to be 2.7.0 now it's 2.

7.1 we also have the pr description that acts as a preview to our change log release please also helps us create change logs automatically based off of our commits so once you merge that it automatically kicks off the process so the GitHub actions run we run our CI we run our build we run our tests and we deploy our artifacts so here we have the tests running and and in our package we also deploy test artifacts to code COV now here's the preview of the the uh change log on the right hand side all of that is automated the only thing the only thing that was added was these images I added those manually but everything else was automated the the tags and the change log and that's it it's released you can now check it out on mpm and GitHub so now I have some time for a demo I'm going to do a live demo real quick and what we're going to do is we're going to publish a new feature live so hopefully this works oh okay all right so here we have a regular PR again we have our commit message with the standard heading feet indicating that this is a non-breaking feature and let's take a look at the diff real quick it's very simple all we're going to do is when a transaction reverts we're just going to we already returning null but we're just going to log a warning for our consumers and that's it so I'm going ahead going to merge this PR cool and that's going to kick off release please if we go to our GitHub actions we we we should see something happening so this might take it might take a minute and this is release please running all of its checks in preparation for that release PR okay so looks like this step has been completed let me go back now if we go to our pull requests we'll see a new PR that was just created just now and this is what we saw earlier in the slides as the release PR again this is a preview to our release so now we're bumping the version up to 2.1.0 and this is a preview of our change log here so now that we let's merge this PR all right and this kicks off the autom release so now if we go back to our GitHub actions it's running the build again it's checking out the repo running CI and building the artifacts I just going to give it maybe 10 15 seconds and there was the publish step uh let me scroll up a little bit so run npm dasu sorry npm publish D access public and we got those green check marks that's it we've automated our release and we've cut a new release 2.10 so if I go back to the repository let's check out a change log in our tags we go down here to releases we'll see that we published 2.

1 2.10 a minute ago and we have our artifacts here and this is our change log now now let's go back and check npm so I'm just going to go back to the top level of the repo and navigate to the npm website okay I'm just going to click into versions actually right here it says last published a minute ago we go into versions there we go 2.10 and that's it we published a new feature live on stage and that's it I hope you learned a little bit about the best practices of automating open sourcing a library and if you're working on a web 3 package you should definitely use a tool like release please I'm Henry you can follow me on warcast or X and asor Rex we build Dex aggregation infrastructure if you're interested in building with us come chat with me thank you