Table of Contents:

1. Project Overview
2. Contracts
   1. ChainRunners.sol
   2. ChainRunnersBaseRenderer.sol
      1. Picking the Layers
      2. Generating the Pixels
3. Security and Safety Considerations
   1. setRenderingContractAddress
   2. setLayers
4. Notes

Project Overview

Before we being, here are the contracts that we will be looking at:
Main Contract: ChainRunners.sol - stores NFT data and contains controls for minting
Render Contract: ChainRunnersBaseRenderer.sol - calculates the pixels/art and creates an SVG

Project Name: Chain Runners
Website: https://www.chainrunners.xyz/
Description: 100% on chain generative pixel art. This means that all of the data making up the art is computed and stored on chain.
Total Supply: 10,000 (85 reserved for founders)
Mint Price: 0.05 ETH
Early Access: Yes
Mint Status: Finished
OpenSea: https://opensea.io/collection/chain-runners-nft (OpenSea is a marketplace for buying and selling NFTs)

Contracts

Now that we have an overview of the project lets dive in. We will start with the first contract

ChainRunners.sol

This contract is an ERC721 with some additional functionality to control minting access - founder, early access, and public minting - and creating the data that the NFTs will be built from.

The first function we want to look at is the internal mint function:

function mint(uint256 tokenId) internal {
    ChainRunnersTypes.ChainRunner memory runner;
    runner.dna = uint256(keccak256(abi.encodePacked(
        tokenId,
        msg.sender,
        block.difficulty,
        block.timestamp
    )));

    _safeMint(msg.sender, tokenId);
    runners[tokenId] = runner;
}

It is a simple function that does the following:

1. Generates the dna of a runner based on the tokenId and some other parameters. We concatenate the parameters and then take the keccak256 (sha3) hash and cast it to a unsigned integer of 256 bits.
   1. It is possible to mint multiple runners (tokens) in a single transaction so using the tokenId as a parameter was necessary to ensure the dna would be different for every runner
2. Mint the tokenId using the ERC721 _safeMint
3. Save the runner (its dna) to a state variable

The runners (and their dna) are stored on this main contract. We dont have an image/svg yet though. For this we will need to start using the second contract, but before we do, the second contract address must be set. It is set by, and only by, the owner of the contract. Remember this, we will discuss the tradeoffs soon.

function setRenderingContractAddress(address _renderingContractAddress) public onlyOwner {
    renderingContractAddress = _renderingContractAddress;
}

So far we have a list of tokenIds mapped to their runners (which contain the dna) and a rendering contract. In order to get the svg/rendering we need to call the function tokenURI (NOTE - it is not the only way but it is the easiest):

function tokenURI(uint256 _tokenId) public view virtual override returns (string memory) {
    require(_exists(_tokenId), "ERC721Metadata: URI query for nonexistent token");

    if (renderingContractAddress == address(0)) {
       return '';
    }

    IChainRunnersRenderer renderer = IChainRunnersRenderer(renderingContractAddress);
    return renderer.tokenURI(_tokenId, runners[_tokenId]);
}

The tokenURI function calls the renderer contract's tokenURI function with the tokenId and the runner associated with the tokenId. What we get back is a base64 encoded string which when we decode it we see contains the SVG data which we can then render.

Its basically magic at this point, but lets take a look at the second contract and see how this magic happens.

ChainRunnersBaseRenderer.sol

As we saw in the first contract, the main entry point on this contract is the tokenURI function.

 /*
    Generate base64 encoded tokenURI.

    All string constants are pre-base64 encoded to save gas.
    Input strings are padded with spacing/etc to ensure their length is a multiple of 3.
    This way the resulting base64 encoded string is a multiple of 4 and will not include any '=' padding characters,
    which allows these base64 string snippets to be concatenated with other snippets.
    */
    function tokenURI(uint256 tokenId, ChainRunnersTypes.ChainRunner memory runnerData) public view returns (string memory) {
        // first we obtain the layers, colors, and traits
        (Layer [NUM_LAYERS] memory tokenLayers, Color [NUM_COLORS][NUM_LAYERS] memory tokenPalettes, uint8 numTokenLayers, string[NUM_LAYERS] memory traitTypes) = getTokenData(runnerData.dna);
        string memory attributes;
        for (uint8 i = 0; i < numTokenLayers; i++) {
            attributes = string(abi.encodePacked(attributes,
                bytes(attributes).length == 0 ? 'eyAg' : 'LCB7',
                'InRyYWl0X3R5cGUiOiAi', traitTypes[i], 'IiwidmFsdWUiOiAi', tokenLayers[i].name, 'IiB9'
                ));
        }
        // then we construct the svg from the layers and colors
        string[4] memory svgBuffers = tokenSVGBuffer(tokenLayers, tokenPalettes, numTokenLayers);
        // finally, we construct the final base64 encoded string
        return string(abi.encodePacked(
                'data:application/json;base64,eyAgImltYWdlX2RhdGEiOiAiPHN2ZyB2ZXJzaW9uPScxLjEnIHZpZXdCb3g9JzAgMCAzMjAgMzIwJyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHNoYXBlLXJlbmRlcmluZz0nY3Jpc3BFZGdlcyc+',
                svgBuffers[0], svgBuffers[1], svgBuffers[2], svgBuffers[3],
                'PHN0eWxlPnJlY3R7d2lkdGg6MTBweDtoZWlnaHQ6MTBweDt9PC9zdHlsZT48L3N2Zz4gIiwgImF0dHJpYnV0ZXMiOiBb',
                attributes,
                'XSwgICAibmFtZSI6IlJ1bm5lciAj',
                Base64.encode(uintToByteString(tokenId, 6)),
                'IiwgImRlc2NyaXB0aW9uIjogIkNoYWluIFJ1bm5lcnMgYXJlIE1lZ2EgQ2l0eSByZW5lZ2FkZXMgMTAwJSBnZW5lcmF0ZWQgb24gY2hhaW4uIn0g'
            ));
    }

There are two functions that are called here that do the heavy lifting. First, the function getTokenData is called which picks the race, layers, and colors. Then the function tokenSVGBuffer creates the svg rects (pixels). Lastly, the remaining code in tokenURI bundles everything together in the final base64 string

Before jumping into the details, lets define some of the data we will see:

• WEIGHTS - Rarity weights split by Race and Layer; they determine the frequency of that layer for that race
• Race - There are 3 races in this contract. They are hard coded and created on contract creation
  1. Alien/Human
  2. Skull
  3. Bot
• Layers - These are the traits that layer on top of each other to create the image. These are set by the owner using the setLayers function. There are 13 traits which are pre-encoded in base64:
  1. Background - QmFja2dyb3VuZCAg
  2. Race - UmFjZSAg
  3. Face - RmFjZSAg
  4. Mouth - TW91dGgg
  5. Nose - Tm9zZSAg
  6. Eyes - RXllcyAg
  7. Ear Accessory - RWFyIEFjY2Vzc29yeSAg
  8. Face Accessory - RmFjZSBBY2Nlc3Nvcnkg
  9. Mask - TWFzayAg
  10. Head Below - SGVhZCBCZWxvdyAg
  11. Eye Accessory - RXllIEFjY2Vzc29yeSAg
  12. Head Above - SGVhZCBBYm92ZSAg
  13. Mouth Accessory - TW91dGggQWNjZXNzb3J5

Picking the Layers

The function getTokenData splits the dna into 13 pieces. The second piece is used to obtain the Race by using the weights associated with the default race. Other pieces are used to obtain specific traits such as having a mask or a face accessory. This is done to make sure layers are compatible with each other visually (it wouldn't look good if the NFT had a mask with a mouth accessory).

Then we generate the layers that will make up the NFT. For each piece of dna, we generate the layer index using the weights of race and the current iteration. This gives us a layer which contains a name, an item index, a layer index, and a hexString. The hexString is used to generate RGBA colors that will be transformed into a 6 letter hex string later on. The iteration is also used to select the trait name from the 13 traits to be used in the final base64 string listed as attributes.

Generating the Pixels

Once we have the layers and the colors, we can start building the NFT pixel by pixel. The function tokenSVGBuffer creates 8 buffers of 4 pixels 32 times (8432=1024). It creates 4 pixels independently and then bundles those into a base64 encoded string. Each pixel combines the individual colors from the layer at a specific position in the hexString. Since most of the layers wont have overlapping pixels we only combine the first two non-transparent layers. The combination of the layers is then converted into a 6 letter hex string. Doing this 8 times in a single iteration creates an entire row of pixels. This happens 32 times generating all of the rows.

Security and Safety Considerations

Overall, generating and storing the data and logic that makes the NFTs/art on chain is a big step in the direction of complete ownership over the NFT and immutable art. Here we see two caveats (albeit small ones) that make it not 100% immutable.

setRenderingContractAddress

Going back to the first contract, we saw the function setRenderingContractAddress which can only be set by the owner. Since all of the logic for creating the art from the dna is in the rendering contract it is possible for the owner to change the way the dna is rendered. Is this a bad thing? Maybe, maybe not. It really all depends on trusting the owners. It might be an issue if the owner's account is hacked or the owner becomes malicious; they can change the rendering contract to something new making an entirely new project. On the other hand, the owner can upgrade the rendering contract to something new which contains additional functionality and extends the current project. At this point, there isn't a need to fear a malicious owner and the community seems to be growing. I'm definitely leaning to the side of extensible upgrades.

setLayers

In the second contract there is a function setLayers, which the owner uses to set the different layers of traits and pixel colors to use for generating the art. The only checks on this function are for the caller to be the owner. This means the owner can change the layers at any point and change the art by doing so since the art is recomputed on each call to tokenURI. Given that it costed the owners close to 7 ETH (you can add up all the fees from the 2nd-8th transactions on the contract) just to upload the original layers' data, its unlikely that they will use this to change the art. It might have been interesting to store the hash of the entire tokenURI to prove no manipulation has been done but then again maybe the team has bigger plans for expanding the narrative and needs the flexibility.

Notes

1. If we look at the first contract again, we can see that there is a function mintRunnerZero. It is callable by anyone but in order to mint it, you need to know the seed used to configure runnerZero which is set by the owner using configureRunnerZero. These functions have not been called yet by the owners! This is one reason that I believe the above security considerations are meant to be used as upgrades in a second/additional narrative to the Chain Runners sagas.

2. There isn't a single hard coded plain text string in the entire render contract. Anything that is meant to be a string was pre-encoded to base64. This saves on computation and can also save on gas if the functions are called as part of an external call (not an external view call). The only down side to this is readibility, though decoding base64 isn't difficult.

3. The only pieces of data that are stored are:

   • WEIGHTS
   • Layers
   • Runner DNA
   • Pre-encoded base64 strings

Whaaaaaat 🤔🤯🤔🤯🤔🤯

Don't worry, we will go through each piece of that sentence and you'll be a pro. Much of what we define will be limited to what we need to understand a blockchain. If you want a TL;DR, skip to the end😉.

A Network of Computers that Communicate

You're currently using a laptop, tablet, phone, or another electronic device to read this article. We can consider any of these a "Computer" - some electronic device that can process information and communicate with other devices that are similar (this is not a strict definition of a Computer, just a definition that we will use).

A Network of Computers is many of these devices that are connected by some capability of communication.

As an example, let’s assume you're at home and connected to your WiFi along with a friend that is also connected to the same WiFi. The two devices can communicate through the WiFi network. This is an example of a small network, your home WiFi. Bigger networks can be created by combining smaller networks and so on. Eventually we get to what we call the Internet - a massive network of many many smaller networks.

A blockchain is exactly this - a small network. A bunch of computers that are continuously talking to each other as one network. In order to join this network and be able to communicate with the other computers, a computer must start a program specific to the blockchain network it wants to join. This program is what allows each computer in the network to speak the same language and communicate with each other. You can think of this as somewhat like WhatsApp - if you want to communicate with someone who is using WhatsApp you must start WhatsApp and then you can talk.

Quick recap: A blockchain is a network of computers that are all running the same program enabling them to communicate with each other.

And Verify Transactions

In the simplest sense, a transaction is some command that is sent to one of the computers in the network. For us, we will assume that all of these commands are of the format "Send X (an amount) Y (some currency) to Z (a person/account)". We can think of it much like using PayPal, Venmo, or any other money sending app.

Each computer in the network (we will call these nodes) will receive some transactions from people using the blockchain. Those nodes will communicate with other nodes about each new transaction they become aware of. This will repeat, until all the nodes know about all of the current transactions. Each node will verify each transaction it knows about to ensure that the person sending actually owns the funds they are trying to send.

As an example, let’s say Alice has 5 dollars and she sends the following transaction to a node: "Send 4 dollars to Bob". That node needs to verify that Alice actually has 4 dollars to send. The node will also notify other nodes that they received this transaction and each of those nodes will also verify that Alice actually has 4 dollars.

Once there are enough verified transactions, one of the nodes creates a block - a chunk of verified transactions. This block is then added to the end of the latest block that was created making a chain of blocks. As more transactions occur, more blocks are created and appended, making the blockchain longer.

Quick recap: Computers in the network, called nodes, receive transactions from users. The node will verify that the transaction is valid and will notify other nodes about the transaction. These other nodes will also verify that the transaction is valid. Once many transactions have been verified, they are bundled into a block which is appended to the last created block, creating a chain of blocks - aka The Blockchain.

To Keep an Immutable Distributed Ledger

All of these transactions and blocks are making up a ledger of who owns what funds based off of incoming and outgoing transactions. Each node holds an exact copy of these records and runs the same program to keep the ledger up to date and valid. This is what makes the ledger distributed; all nodes perform some action to compute a single outcome that is shared with all nodes.

As time progresses, more transactions are being verified and more blocks are being added to the chain. Each block contains a few pieces of data; the list of transactions, a unique identifier (called a hash) of the block, and the previous block’s hash. Since each block contains the hash of the previous block, each block is linked to the previous one. This means, if someone wanted to change the history of the chain by removing one of the blocks, everyone would know since the block after the one removed would not contain the hash of the block before the one removed.

Assume we have a blockchain that contains 100 blocks currently. Someone wants to change history and remove block #97. If this happened, then we would have block #96 before block #98. BUT Block #98 contains #97's hash not #96's so everyone would know that some history is missing or is incorrect and would not accept the change.

This is what makes the blockchain immutable. Or does it? What if we removed blocks #97, 98, 99, and 100 and replaced them with valid but different blocks? Since the historical chain is valid it should be accepted.

This is true and it is possible that it can happen. So how is a blockchain immutable???

Since the current history is progressing by adding blocks, the alternate history needs to be created at a faster rate than the current history. This is both extremely costly and time consuming as we will see in a later post, making it very unlikely to happen and causing the blockchain to be probabilistically immutable.

In a later post we will discuss Why blockchains are useful and matter in today's world.

Full Recap

A blockchain is a network of computers (nodes) that are all running the same program allowing them to communicate about transactions that each one knows of.

Transactions are sent to each node to verify that they are valid and viable transactions. Once a chunk of transactions have been verified, a block containing these verified transactions is appended to the end of the current chain of previous blocks which contain the history of validated and verified transactions - this chain of blocks is the ledger aka The Blockchain.

Each node holds their own copy of the agreed upon blockchain. Each block contains a piece of the previous block linking them together in the history. In order to change the history, one of the nodes must create an alternate history that is both valid and longer than the current history (we will see that this is not 100% for every blockchain). Since the current history is progressing by adding blocks, the alternate history needs to be created at a faster rate than the current history. This is both extremely costly and time consuming, making it very unlikely to happen and causing the blockchain to be probabilistically immutable.

So what is Bitcoin?

Stay tuned for part 2 of Crypto College

This series will take you on a journey through the cryptoverse. We will begin with the basics and build on top to more complex ideas and hands on tutorials. No prior knowledge of blockchains is needed, however some familiarity with computer concepts is recommended.

After each post is released, the list below will be updated with links to each post. Italicized titles are coming soon. If you have specific topics you want covered please comment below and I will try to add them to the list.

I always appreciate feedback, corrections, and questions; Feel free to email me jeremy.felder1@gmail.com (or comment below) and I will try to respond as much as possible.

Intro to blockchain and money

• What is a blockchain anyway?
• So what is Bitcoin?
• Why does blockchain technology matter: A history of money
• So what is Ethereum?