Forem: 0xMoJo7

On-Chain SVG Generation - Part 1

0xMoJo7 — Mon, 03 Jan 2022 23:42:49 +0000

As of recent, a lot of projects have requested for us to deploy their art on-chain. While this is cool, trendy way of keeping all of your NFT art on-chain, it comes with some limitations. The image (in bytes) that they want to store on-chain can only be so big without losing a ton of money to gas costs.

While this is not a new idea by any means (Cryptopunks is on-chain and they were one of the first), I found trouble finding a good tutorial on how to do it.

Thus, we will be covering how to generate the art on chain, and in part 2 we will explain how you go about actually handling randomness and pushing the correct metadata for the OS protocol.

First steps

You will need to deploy all of your assets onto IPFS (bear with me, we won't be just referencing them in our metadata as the image). You will then need to build a json struct, here is an example I did for a "Mobsters" NFT:

{
    "Mobster":
    {
        "Shoes": [
            {"Black": "https://gateway.pinata.cloud/ipfs/pinata_shoes_folder/Shoes/Black.png"},
            {"Brown": "https://gateway.pinata.cloud/ipfs/pinata_shoes_folder/Shoes/Brown.png"},
            {"Gold": "https://gateway.pinata.cloud/ipfs/pinata_shoes_folder/Shoes/Gold.png"},
            {"Red": "https://gateway.pinata.cloud/ipfs/pinata_shoes_folder/Shoes/Red.png"},
            {"White": "https://gateway.pinata.cloud/ipfs/pinata_shoes_folder/Shoes/White.png"},
            {"White & Blue": "https://gateway.pinata.cloud/ipfs/pinata_shoes_folder/Shoes/WhiteBlueSneakers.png"},
        ],

        "Pants": [
            {"Black": "https://gateway.pinata.cloud/ipfs/pinata_pants_folder/Pants/Black.png"},
            {"Gold": "https://gateway.pinata.cloud/ipfs/pinata_pants_folder/Pants/Gold.png"},
            {"Jeans": "https://gateway.pinata.cloud/ipfs/pinata_pants_folder/Pants/Jeans.png"},
            {"Pinstripe": "https://gateway.pinata.cloud/ipfs/pinata_pants_folder/Pants/Pinstripe.png"},
            {"Red": "https://gateway.pinata.cloud/ipfs/pinata_pants_folder/Pants/Red.png"},
            {"White": "https://gateway.pinata.cloud/ipfs/pinata_pants_folder/Pants/White.png"}
        ],
   // ETC

Next, we are going to generate a file called Traits.sol (some parts cut for the sake of part 1s simplicity, which is where we are going to upload each of these assets as base64 encoded versions).

It will look something like this:

// SPDX-License-Identifier: MIT LICENSE

pragma solidity ^0.8.0;
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/Strings.sol";
import "./interfaces/ITraits.sol";
import "./interfaces/IMnC.sol";

contract Traits is Ownable, ITraits {

  using Strings for uint256;

  // struct to store each trait's data for metadata and rendering
  struct Trait {
    string name;
    string png;
  }

  // mapping from trait type (index) to its name
  string[8] private _traitTypes = [
      "Shoes",
      "Pants",
      "Shirt",
      "Eyes",
      "Head",
      "Hat",
      "Mouth Piece",
      "Accessories",  
  ];
  // storage of each traits name and base64 PNG data
  mapping(uint8 => mapping(uint8 => Trait)) public traitData;

  /**
   * administrative to upload the names and images associated with each trait
   * @param traitType the trait type to upload the traits for (see traitTypes for a mapping)
   * @param traits the names and base64 encoded PNGs for each trait
   */
  function uploadTraits(uint8 traitType, uint8[] calldata traitIds, Trait[] calldata traits) external onlyOwner {
    require(traitIds.length == traits.length, "Mismatched inputs");
    for (uint i = 0; i < traits.length; i++) {
      traitData[traitType][traitIds[i]] = Trait(
        traits[i].name,
        traits[i].png
      );
    }
  }

  /** RENDER */

  /**
   * generates an <image> element using base64 encoded PNGs
   * @param trait the trait storing the PNG data
   * @return the <image> element
   */
  function drawTrait(Trait memory trait) public pure returns (string memory) {
    return string(abi.encodePacked(
      '<image x="4" y="4" width="64" height="64" image-rendering="pixelated" preserveAspectRatio="xMidYMid" xlink:href="data:image/png;base64,',
      trait.png,
      '"/>'
    ));
  }

  /**
   * generates an entire SVG by composing multiple <image> elements of PNGs
   * @param tokenId the ID of the token to generate an SVG for
   * @return a valid SVG of the Mobster
   */
  function drawSVG(uint256 tokenId) internal view returns (string memory) {
    IMnC.CopperMobster memory s = mncNFT.getTokenTraits(tokenId);

    string memory svgString = string(abi.encodePacked(
      drawTrait(traitData[0][s.shoes]),
      drawTrait(traitData[1][s.pants]),
      drawTrait(traitData[2[s.shirt]),
      drawTrait(traitData[3][s.eyes]),
      drawTrait(traitData[4][s.head]),
      drawTrait(traitData[5][s.hat]),
      drawTrait(traitData[6][s.mouthpiece]),
      drawTrait(traitData[7][s.accessories])
    ));

    return string(abi.encodePacked(
      '<svg id="NFT" width="100%" height="100%" version="1.1" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">',
      svgString,
      "</svg>"
    ));
  }

So, essentially all we are doing her is storing all the traits in a struct which will be stored in a mapping for later use by using the uploadTraits method. This will be the first thing you will want to knock out when starting this project. drawTrait will be used to actually wrap the base64 encoded png in an image tag so it can be rendered. Finally, drawSVG will allow us to grab the randomized trait (will be explained in the next tutorial, there are a lot of ways to do this, but to do it entirely on-chain, here used A.J. Walker's Alias Algorithm for anyone wanting to jump ahead.

Script to upload one group of traits

Note, this can also be done in a loop to do everything at once, but for simplicity sake, here is a script of how to upload one group (we will be doing our mobsters shirts).

const { ethers } = require("hardhat");
require('dotenv').config({path: ".env"})
const fs = require('fs');
const fetch = require("node-fetch");
const traitJson = JSON.parse(fs.readFileSync('scripts/traitMapping.json'));

async function main() {

  const [user1, user2]  = await ethers.getSigners();
  provider = ethers.getDefaultProvider()

  // Deploy our Traits.sol contract
  const Traits = await ethers.getContractFactory("Traits")
  t = await Traits.deploy()
  await t.deployed()
  console.log("Traits.sol deployed to", t.address)
  // Attach to the contract
  const tContract = await Traits.attach(t.address)
  let traitsToUpload = []
  console.log(traitJson["Mobster"]["Shirt"])
  for (let i=0; i < traitJson["Mobster"]["Shirt"].length; i++) {
    // Get name of the specific attribute
    let key = Object.keys(traitJson["Mobster"]["Shirt"][i]).toString();
    // Get IPFS URL for the asset
    let value = Object.values(traitJson["Mobster"]["Shirt"][i]).toString();
    // Encode in Base64 the png (this is where the magic happens)
    let imgB64 = await fetch(value).then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    // Append the dictionary of the mapping fo the name to the base64 image
    traitsToUpload.push({name: key, png: imgB64})
  }
  tx = await tContract.uploadTraits(2, [3, 3, 8, 1, 10, 10, 10, 11, 3, 11, 8, 10], traitsToUpload)
  // The first arg is the position of the trait in Traits.sol, the second array is for randomness
  // randomness which will be explained in part 2 of the tutorial, and finally the third arg is
  // our actual mappings we just generated
  console.log(tx)
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

After doing this for each attribute, all of about assets are ready to be combined upon mint!

Script to make sure your assets combine correctly

If you’re curious how your assets stack up, you can do this off-chain to check that things are assembling correctly, once you have altered the script below, at the bottom of this webpage you can paste in your svg code to see a preview of what it will render as. Keep in mind these are SVG's so you need to keep them small. SVG stands for Scalable Vector Graphics. Which means even if your SVG is very small (64x64px is probably the largest I would go for gas reasons it will scale as it is rendered on OpenSea or elsewhere.)

This is a very blunt script, to help explain in detail what exactly will happen on-chain to combine the assets. (It's crucial you sync with your artist to make sure you are layering them in the correct order.)

const fetch = require("node-fetch");

async function main() {
    let shoesB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/White-Blue-Sneakers.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let pantsB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/Jeans.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let shirtB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/Godfather.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let eyesB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/3D-Glasses.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let headB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/Boss.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let hatB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/White-Fedora.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let mouthB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/Cigar.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));
    let assessB64 = await fetch("https://gateway.pinata.cloud/ipfs/pinata_asset_folder/Tommy-Gun.png").then(r => r.buffer()).then(buf => `data:image/png;base64,`+buf.toString('base64'));


    base = '<image x="4" y="4" width="64" height="64" image-rendering="pixelated" preserveAspectRatio="xMidYMid" xlink:href="'
    end = '"/>'

    shoes = base + shoesB64 + end
    pants = base + pantsB64 + end
    shirt = base + shirtB64 + end
    eyes = base + eyesB64 + end
    head = base + headB64 + end
    hat = base + hatB64 + end
    mouth = base + mouthB64 + end
    access = base + assessB64 + end

    starter = '<svg id="NFT" width="100%" height="100%" version="1.1" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">'
    finisher = "</svg>"

    console.log(starter+shoes+pants+shirt+eyes+head+hat+mouth+access+finisher)
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

This should output a string you can paste in the link above to see if that specific NFT is rendering correctly.

I hope you found this tutorial helpful. If you have any comments or suggestions on how I could improve my process or how you did it more efficiently, I am all ears. Please feel free to leave something in the comments. Once the second part of the tutorial is complete, we will be open sourcing the entire repo.

If you found this tutorial helpful, please give me a follow on Twitter and follow my company, CrossChain Labs for any NFT/DeFi help you made need with your project or more helpful blog posts.

Stay tuned for part 2!!

Merkle Tree + Solidity SC Validation

0xMoJo7 — Thu, 18 Nov 2021 00:59:00 +0000

Merkle Tree Basic Concepts

Merkle Trees are an integral part of any blockchain system and are used extensively for its benefits. The Merkle Tree (or hash tree) was invented in 1979 by Ralph Merkle as a cryptographic means of validating data efficiently and securely for rather large data structures. It allows validation of data without exposing a full data set. The verification of existence of any child data set (leaf node) is possible using a fixed number of other data nodes. We will implement a simple example of Merkle Proofs in this tutorial.

Here is an example of a simple Merkle tree.

The top level is known as the root of the Merkle tree, which we will store as an immutable bytes32 object in our Solidity code. The bottom most nodes are known as the leaf nodes (which will be the hash of our whitelisted addresses), which are then used to generate the intermediate nodes and the root. The intermediate nodes are the hash of it's child nodes. As long as we keep the addresses and the order we hashed them private, no one will be able to reverse engineer our Merkle Tree or root, and bypass our validation.

If your address list needs to be public, you may consider hashing a concatenated string of a static variable (such as your contract address) and wallet addresses to prevent someone from recreating your Merkle Tree and bypassing validation.

I highly encourage reading up on the concepts of a Merkle Tree, while you can just copy and paste this code and make it work, the underlying concepts are both highly interesting and can be applied to other places in your development journey. Or, you can just skip to the repo :)

Before we get too far...This tutorial assumes you have a basic understanding of Solidity, React, Ethers.js and Hardhat. If you are new or need a refresher, there is a fantastic tutorial by Nader located here.

Contract

Ok, let's jump in. Here is the full contract:

Whitelist.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract MerkleProof {
  function verify(
    bytes32 root,
    bytes32 leaf,
    bytes32[] memory proof,
    uint256[] memory positions
  )
    public
    pure
    returns (bool)
  {
    bytes32 computedHash = leaf;

    for (uint256 i = 0; i < proof.length; i++) {
      bytes32 proofElement = proof[i];

      if (positions[i] == 1) {
        computedHash = keccak256(abi.encodePacked(computedHash, proofElement));
      } else {
        computedHash = keccak256(abi.encodePacked(proofElement, computedHash));
      }
    }

    return computedHash == root;
  }
}

contract Whitelist is MerkleProof {
  bytes32 public immutable merkleRoot;

  constructor (bytes32 _merkleRoot) {
      merkleRoot = _merkleRoot;
  }

  function verifyWhitelist(
      bytes32[] memory _proof, 
      uint256[] memory _positions
    ) 
      public 
      view 
      returns (bool) 
    {
        bytes32 _leaf = keccak256(abi.encodePacked(msg.sender));
        return MerkleProof.verify(merkleRoot, _leaf, _proof, _positions);
    }
}

As mentioned before, we are going to pass the merkleRoot to the constructor of the Whitelist contract when we deploy it. We will generate it using the merklejs library in the next step.

Since computation on the Ethereum blockchain is expensive (each byte of data costs additional gas), the rest of the hashing and parameter generation will be done off-chain.

The leaf node generation, which is a hash of our msg.sender, is done inside the verifyWhitelist function in the contract.
The _proof array will be another hash of that specific leaf. This allows us to prove "Proof-of-inclusion" in our Merkle Tree without revealing or calculating all of the information in the tree.
Finally, the _positions array contains the positions of the corresponding proof (aka node) in the Merkle Tree, so that users can verify the consistency by computing the root value directly.

Generating our Merkle Root

This script (which you will see parts of later in our App.js) generates the Merkle Root. It requires that you have the packages merkletreejs and keccack256 (hashing function also available in Solidity) installed.

generateMerkleRoot.mjs

import whitelist from "./whitelist.js";
import { MerkleTree } from "merkletreejs";
import keccak256 from "keccak256";

const buf2hex = x => '0x' + x.toString('hex')
const leaves = whitelist.map(x => keccak256(x))
const tree = new MerkleTree(leaves, keccak256)
// This is what we will pass in to our contract when we deploy it
console.log(buf2hex(tree.getRoot()))

For the sake of example, the variable whitelist is simply an array of Ethereum addresses imported from a file in the same directory. In production, you should consider using a json, or something a bit more secure/efficient. You can add your own Ethereum address or a test account address in the array so you can test the functionality when we are done.

buf2hex is a function that converts our buffered array to hexadecimal.
We create the leaves after hashing them with keccak256 and pass them to the MerkleTree constructor to generate the actual tree.
Finally, we call tree.getRoot() and convert it to hexadecimal, while logging the output to the console. (Save this somewhere safe for your deployment.)

React / App.js

After compiling your contract using npx hardhat compile and deploying to a test network (or localhost) we can now take a look at our actual dapp implementation. For simplicity, we are going to keep all of our Merkle logic in App.js

App.js

import logo from "./logo.png";
import "./App.css";
import React, { useContext, useState, useEffect } from "react";
import { Web3Context } from "./web3";
import contract from './artifacts/contracts/Merkle.sol/Whitelist.json'
import { ethers } from 'ethers'
import whitelist from './merkle/whitelist'
const { MerkleTree } = require("merkletreejs");
const keccak256 = require('keccak256')

function App() {
  const { account, connectWeb3, logout, provider } = useContext(Web3Context)
  const [approved, setApproved] = useState(false);

  const whitelistContractAddress = "0x49F59D1b3035055a5DF5F4EbF876b33f204E5aB1"   // Rinkeby

  const merkle = async () => {
    const whitelistContract = new ethers.Contract(whitelistContractAddress, contract.abi, provider.getSigner())

    const buf2hex = x => '0x' + x.toString('hex')
    const leaves = whitelist.map(x => keccak256(x))
    const tree = new MerkleTree(leaves, keccak256);
    const leaf = keccak256(account)
    const hexProof = tree.getProof(leaf).map(x => buf2hex(x.data))
    const positions = tree.getProof(leaf).map(x => x.position === 'right' ? 1 : 0)
    let result = await whitelistContract.functions.verifyWhitelist(hexProof, positions);
    setApproved(result[0]);
  }

  useEffect(() => {
    if (account != null) {
        merkle(); 
    }
  }, [account])

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="ethereum_logo" />
        <div>
          {account == null ? (
            <button onClick={connectWeb3}>Connect to MetaMask</button>
          ) : (
            <div>
              <p>Account: {account}</p>
              {approved ? <p>Congratulations, you are approved!</p> : <p>Sorry, you are not approved</p>}
              <button onClick={logout}>Logout</button>
            </div>
          )}
        </div>
        <br />
      </header>
    </div>
  );
}
export default App;

Again, this tutorial assumes you do know a bit of React and ethers.js, so we won't be diving into the nitty gritty of every line.

In the main <div> of the webpage, you will see a conditional rendering based on the account being instantiated (see the web3 directory and Web3Context in the git repo for more details). Since the user hasn't connected their wallet to the website this will return a "Connect to MetaMask" button. Once you have connected to an Ethereum network (make sure you connect to the same network you deployed your contract to), React's useEffect() function will be called since your account is no longer null. In turn, we call the merkle() function within the useEffect().

Fortunately, we do not have to compute the root again, but we do need other parameters passed into the smart contract. Lucky for us, it calculates and hashes our parameters very quickly, all based on the end user's wallet address. You'll recognize some code from our generateMerkleTreeRoot.mjs file. It would be possible to export/import the leaves and tree if we reworked the generateMerkleTreeRoot.mjs, but for the sake of simplicity, we will keep the logic here and recompute these variables.

Once hexProof and positions are generated, we pass them to our contract and await for our boolean response. Using React's useState(), if the smart contract and Merkle Tree return true, we set approved to true, which renders "Congratulations, you are approved!".

You can use this frontend logic to conditionally render a mint button or build an address gated site for a select group of users. (For example, you could use moralis or a subgraph to gather all your token holders and give access to exclusive content).

If you are going to render a whitelist mint button for a NFT, make sure that you include the Merkle Proof validation logic in your contract's mint function too, with require(verifyWhitelist(_proof, _positions)) to prevent people from just going around your website and minting on contract.

Thanks For Reading!

I hope you found this tutorial helpful! Due to lack of available material, it took me longer than expected to implement this, so hopefully this helps someone! If you have any questions, suggestions on how to improve this solution, or think I could simply explain this better; feel free to leave me a note in the comments.

Feel free to follow me on Twitter and Github as I plan on building more tutorials and blogging about the new things I learn upon my journey into web3.

Special thanks to Sudeep for the frontend and writing help! We used his very nice bare minimum template based on create-react-app that installs all the main tools needed to build a dapp without the extra bloat, check it out here. We became friends in DEV_DAO, which is a DAO dedicated to helping web3 developers connect and provide learning resources.