DEV Community: Ivan Montiel

Enforcing Localization through Types

Ivan Montiel — Sat, 19 Aug 2023 20:29:14 +0000

When building web applications, enforcing that strings be localized to the user’s preferred language can sometimes be achieved via lint rules. But what if we could enforce proper localization using types in Typescript?

Defining a Localized Type

Typescript doesn’t natively provide an Opaque type that we can use to define a string that has already been localized. If the data looks like a string, Typescript will consider it a string. We can however use utility types that simulate opaque types, like the Opaque definition in type-fest:

import { Opaque } from 'type-fest';

type LocalizedString = Opaque<'LocalizedString', string>;

Playground example

Here is a short example where we create a localized string and try to use a raw string and our localized string in a function:

import { Opaque } from 'type-fest';

type LocalizedString = Opaque<'LocalizedString', string>;

function createLocalizedString(s: string): LocalizedString {
    return s as LocalizedString;
}

function example(s: LocalizedString) {
    return s;
}

console.log(example('test')); // Will throw a type error
console.log(example(createLocalizedString('test'))); // Works correctly

Playground example

Now we have a type that we can use in our function and components to denote that we expect an already localized string to be used.

Enforcing in Components

The simplest way we can enforce that strings have already been localized is by using the type in our component’s props interface:


interface ButtonProps {
  label: LocalizedString;
}

function Button(props: ButtonProps) {
  return <button>{props.label}</button>;
}

Now if we try to use that component without a localized string, we get an error:

import React from 'react';
import { Opaque } from 'type-fest';

type LocalizedString = Opaque<'LocalizedString', string>;

function createLocalizedString(s: string): LocalizedString {
    return s as LocalizedString;
}

interface ButtonProps {
  label: LocalizedString;
}

function Button(props: ButtonProps) {
  return <button>{props.label}</button>;
}

function Example() {
    return (
        <>
            <Button label="Test" />
            <Button label={createLocalizedString("Test")} />
        </>
    );
}

Playground example

Localizing Strings

So far, we’ve been using a utility createLocalizedString to create and use the LocalizedString type. This utility is only really practical in unit tests. For real applications, we’ll want to use a translation function from react-i18next or next-i18next to do the heavy lifting. Then we just wrap the translation functions that are provided in order to use our type:

import React, { useCallback } from 'react';
import { Opaque } from 'type-fest';
import { useTranslation } from 'react-i18next';

type LocalizedString = Opaque<'LocalizedString', string>;

function createLocalizedString(s: string): LocalizedString {
    return s as LocalizedString;
}

interface ButtonProps {
  label: LocalizedString;
}

function Button(props: ButtonProps) {
  return <button>{props.label}</button>;
}

function useLocalizedTranslation() {
    const { t : originalTranslate } = useTranslation();

    const t = useCallback((key: string, defaultString: string) => {
        return originalTranslate(key, defaultString) as LocalizedString;
    }, [originalTranslate]);

    return { t };
}

function Example() {
    const { t } = useLocalizedTranslation();
    return (
        <>
            <Button label={t("test", "Test")} />
        </>
    );
}

Playground example

Here we use useTranslation from react-i18next and wrap the t translation function that is returned to override the type it gives us.

Now when engineers go to use the Button component, they will know they need a LocalizedString, and the most straightforward way to get it will be to use the i18next utilities that we also provide.

Feature Contexts

Ivan Montiel — Thu, 17 Aug 2023 20:46:10 +0000

A common pattern in larger application when trying to track feature usage is to try to namespace events. For example, you might have a button that you want to track clicks on. For the sake of this article, we will use the data-track attribute on elements to track their usage, but you can imagine this works with any tracking implementation where you may need to explicitly call a tracking function (e.g. track(namespace)).

Simple Example

As requests to start tracking user events come up, typically the easiest way is to just hard code the tracking namespaces:

<button data-track="chat.form.send">Send<button>

And as the tracking grows, these might get moved to a separate file and a constant/enumeration:

const ChatTracking = {
  send: 'chat.form.send',
  attachMedia: 'chat.form.attachMedia',
  edit: 'chat.messages.edit',
  delete: 'chat.messages.delete',
} as const;

// usage

<button data-track={ChatTracking.send}>Send</button>

We have a lot of string duplication here. We might be tempted to use template strings or some other way of creating the string, but it doesn’t end up reducing any of the duplication.

Passing Namespaces

As the application grows more complex, an engineer working on another set of features ends up wanting to re-use the chat form from above. It already has some additional animation and composes together the component library widgets, why not re-use it in the context of forums.

Except now the data-track attribute has to be passed in as a prop:

The Forums usage ends up adding its own tracking attribute, but ends up having to prop-drill down the namespace from the Forums components, through the ChatForm, to the SendButton component.

Using Context

Instead, what if we wrap our features in some Context component that helps us track where our components are being used. Then we can just build up the tracking namespace based on where the component is in the feature tree, rather than having to keep track of long namespace strings.

First let’s build a context in React:

FeatureContext.tsx

import { createContext } from 'react';

/**
 * Context for tracking features
 */
export const FeatureContext = createContext<string[]>([]);

Then we’ll create a helper component that we can use throughout the application:

Feature.tsx

import type { ReactNode } from 'react';
import { useContext, useMemo } from 'react';
import { FeatureContext } from './FeatureContext';

export interface FeatureProps {
    readonly name: string;
    readonly children: ReactNode;
    readonly topLevel?: boolean;
}

export function Feature({
    name,
    children,
    topLevel,
}: FeatureProps): JSX.Element {
    const parentContext = useContext(FeatureContext);

    const currentContext = useMemo(() => {
        if (topLevel === true) {
            return [name];
        }
        return [...parentContext, name];
    }, [parentContext, name, topLevel]);

    return (
        <FeatureContext.Provider value={currentContext}>
            {children}
        </FeatureContext.Provider>
    );
}

Usage of this component would look like:

function Forums() {
  return (
    <Feature name="forums">
      <ChatForm />
    </Feature>
  );
}

function Chat() {
  return (
    <Feature name="chat">
      <ChatForm />
    </Feature>
  );
}

function ChatForm() {
  return (
    <Feature name="form">
      <SendButton />
    </Feature>
  );
}

Then, in SendButton, when we actually need to use the feature context, we construct the namespace:

SendButton.tsx

function SendButton() {
  const featureContext = useContext(FeatureContext);

  return (
    <button data-track={[...featureContext, 'send'].join('.')}>Send</button>
  );
}

Note: the above example has been simplified for this article’s sake. Typically some utility for reading the context, joining the namespaces, and memoizing the value would be provided.

No additional props are needed, and the Feature components can be used throughout the application as a standard mechanism for building up feature namespaces.

Conclusion

Rather than trying to alleviate string duplication and prop-drilling as separate problems, we can leverage React Context to solve both problems at the same time and leverage context to determine where we are in a feature tree. Not only does the Feature context help with constructing the data-track attributes, but it now provides a consistent mechanism that we can use throughout the application to let components know the feature namespace they are currently in without the parent components prop-drilling the namespace down to every component.

Safely typing full/partial objects

Ivan Montiel — Mon, 14 Aug 2023 17:26:48 +0000

When trying to be as type-safe as possible in Typescript, there are times when you may have to dynamically construct an object. You know as a programmer that all the keys will have values, but because you have to dynamically construct the values, the type system doesn’t know that the object is complete:

/**
 * An example interface to demonstrate
 */
interface KnownCodes {
  code1: number;
  code2: number;
  code3: number;
}

function createValuesForKnownCodes(): KnownCodes {
  const knownCodes: Partial<KnownCodes> = {};

  // In a real example, these keys may come from some other object
  // or external data
  for (const key in ['code1', 'code2', 'code3']) {
     knownCodes[key as keyof KnownCodes] = dynamicValue(key);
  }

  return knownCodes as KnownCodes;
}

// Stub for the example
function dynamicValue(key: string) { return 0 };

In the above example, we know that knownCodes will have all the keys will have values for the interface KnownCodes. However, Typescript can’t infer that, so we have to cast the value.

As the function gets more complex with additional feature work, this can become brittle and lead to some type-holes where we may have accidentally forgotten to set a key.

One way to get around this is to use an assert:

type RequireAll<T> = {
  [K in keyof T]-?: T[K];
};

function ensureAllRequired<T>(obj: Partial<T>, template: RequireAll<T>): asserts obj is T {
  for (const key in template) {
    if (obj[key] === undefined) {
      throw new Error(`Missing required property: ${key} in ${JSON.stringify(obj)}`);
    }
  }
}

interface KnownCodes {
  code1: number;
  code2: number;
  code3: number;
}

const TEMPALTE_CODES: KnownCodes = {
  code1: -1,
  code2: -1,
  code3: -1,
}

function createValuesForKnownCodes(): KnownCodes {
  const knownCodes: Partial<KnownCodes> = {};

  // In a real example, these keys may come from some other object
  // or external data
  for (const key of ['code1', 'code2']) {
     knownCodes[key as keyof KnownCodes] = dynamicValue(key);
  }

  ensureAllRequired(knownCodes, TEMPALTE_CODES);

  return knownCodes;
}

createValuesForKnownCodes();

// Stub for the example
function dynamicValue(key: string) { return 0 };

Playground link

The above code does a runtime check that the object has all the keys that are defined in the template. This ensure that any missing keys are caught as well.

I have seen other examples online where only the object is passed in, but this ends up not working if the keys are not defined in the object:


function ensureAllRequired<T>(obj: Partial<T>): asserts obj is T {
  for (const key in obj) {
    if (obj[key] === undefined) {
      throw new Error(`Missing required property: ${key} in ${JSON.stringify(obj)}`);
    }
  }
}

The above will let any empty object partial to pass the assert.

Takeaway

This ends up being a lot of work to do a runtime check to improve our typings, which I’m not sure is the best approach. Most of the time when we construct objects from an empty object, it’s difficult to ensure that the full object has been safely created.

Since we have to create a template object anyway, it is almost always simpler to do the following:

interface KnownCodes {
  code1: number;
  code2: number;
  code3: number;
}

const TEMPALTE_CODES: KnownCodes = {
  code1: -1,
  code2: -1,
  code3: -1,
}

function createValuesForKnownCodes(): KnownCodes {
  const knownCodes = { ...TEMPALTE_CODES };

  // In a real example, these keys may come from some other object
  // or external data
  for (const key of ['code1', 'code2', 'code3']) {
     knownCodes[key as keyof KnownCodes] = dynamicValue(key);
  }

  return knownCodes;
}

createValuesForKnownCodes();

// Stub for the example
function dynamicValue(key: string) { return 0 };

Playground link

Here we take the easy way out and clone the template and then built the object from there. Even if we forget to add a key (like code3) to our list of keys or it's missing from our external data that we are using, we will be guaranteed that the return value is the correct shape and types.

Ensuring all of a type

Ivan Montiel — Sat, 12 Aug 2023 23:34:18 +0000

When creating more complex systems, there are times where you will want to ensure that an array contains every value of a defined type. We have a union of primitive literal types to define the possible values a type can have:

type Colors = 'red' | 'green' | 'blue';

Then, throughout our codebase, we can use the Color type to ensure functions can only be called with those values:

addColor(name: Colors);

But, we may want to make sure that when we create a new possible value for the type, we don’t forget to use that value to do some initialization:

function initColors() {
  addColor('red')
  addColor('green');
  addColor('blue');
}

There are a few ways to do this, one would be to create a record that must contain every color:

const allColors: Record<Colors, boolean> = {
    red: true,
    green: true,
    blue: true,
};

function initColorsUsingRecord() {
    (Object.keys(allColors) as Colors[]).forEach((color) => {
        addColor(color);
    });
}

In the above snippet, we create a record that will have every Colors type as a key, and Typescript will complain when we add a new literal type to the Colors union and forget to add it to the record.

Notice though that we end up just getting the list of keys in allColors as an array anyway, then casting that type to help with the type-hinting for Object.keys.

We can also ensure that we create an array with every value of a given type:

/**
 * Generator function to create functions that will throw typing exceptions when
 * the given array does not contain all values of the type
 */
function ensureAllOf<T>() {
    return <U extends T[]>(array: U & ([T] extends [U[number]] ? unknown : "Invalid")) => array;
}

type Color = 'red' | 'green' | 'blue';
const ensureAllColors = ensureAllOf<Color>();
const colors = ensureAllColors(['red', 'green', 'blue']);

function addColor(color: Color) {
    // just a stub
}

function initColorsUsingEnsure() {
    colors.forEach(color => {
        addColor(color);
    });
}

Typescript Playground

In the above example, we have a template ensureAllOf that takes a type and spits out a function that takes an array of that type and will throw a typing error if that array does not contain all of the possible values.

If we add “yellow” to the Colors type, then ensureAllColors will remind us that we need to add “yellow” to the list of values

Takeaway

While ensureAllOf may come in handy in some cases, it is almost always easier to use an enumeration:

enum Color {
    red = 'red',
    green = 'green',
    blue = 'blue'
}

function addColor(color: Color) {
    console.log('init', color);
}

const colors = Object.values(Color);

function initColorsUsingEnsure() {
    colors.forEach(color => {
        addColor(color);
    });
}
initColorsUsingEnsure();

Typescript Playground

Using an enumeration, there is no need to write a type and have to add the new value to the ensureOfAll array.

Get Class Name in Typescript

Ivan Montiel — Thu, 10 Aug 2023 16:48:43 +0000

We don’t get a lot of information using typeof in JavaScript or TypeScript. At most, it tells us whether a value is undefined, number, string, or object. If you want to get the class name using a function, you can use the following extended version of classOf that is originally from “JavaScript: The Definitive Guide”:

function classOf(obj: unknown) {
    if (obj === null) return "Null";
    if (typeof obj === "undefined") return "Undefined";

    if (typeof obj === 'object') {
        // Warning: this won't work if your Typescript is minified and class names are mangled.
        return (obj as object).constructor.name;
    }

    if (typeof obj === 'function') {
        // Warning: this won't work if your Typescript is minified and function names are mangled.
        const possibleName = (obj as CallableFunction).name;
        if (possibleName) {
            return possibleName;
        }
    }

    return Object.prototype.toString.call(obj).slice(8, -1);
}

console.log(classOf(null)); // "Null"
console.log(classOf(undefined)); // "Undefined"
console.log(classOf(1)); // "Number"
console.log(classOf("foobar")); // "String"
console.log(classOf({})); // "Object"
console.log(classOf([])); // "Array"
console.log(classOf(new Date()))

class Test {}
console.log(classOf(new Test())); // "Test"

function test() {}
console.log(classOf(test)); // "test"

console.log(classOf(function () {})) // "Function"

Playground Link

This classOf function works for any value, including numbers, strings, booleans, classes, and functions. It will return the best name for that given value that is passed. If the object has a constructor name, that value will be returned. If that value is a function, the name of that function will be returned.

Takeaways

Unfortunately, during some transpilation steps or code compression, these names get mangled or removed completely, so it’s best not to rely on the class’s actual name directly. Instead instanceof should be used, or a static name attribute that cannot be modified.

Enumerating Properties

Ivan Montiel — Wed, 09 Aug 2023 18:01:15 +0000

In “JavaScript: The Definitive Guide”, there are functions described in 6.5 Enumerating Properties that probably shouldn’t be used in production code because they modify their input parameters: extend, merge, restrict, and subtract.

Let’s re-create each one using more modern practices in Typescript that don’t modify the input parameters:

/**
 * Create a new object that returns the properties of target, overwritten with the properties in props
 */
function extend<T extends object, P extends object>(target: T, props: P): T & P {
    return {...target, ...props};
}

Even in a more modern implementation, I would never recommend this. It is almost always easier to write {...a, ...b} inline and have its meaning be more clear.

Next we have merge, not to be confused with extend:

/**
 * Create a new object that returns all the properties of target and props, but the properties
 * in target are left alone.
 */
function merge<T extends object, P extends object>(target: T, props: P): T & P {
    return {...props, ...target};
}

Same thing here, even with a more type-safe implementation, it’s almost always more clear to have an inline spread of {...b, ...a}.

A more interesting function implementation is restrict:

/**
 * Create a new object that returns all the values in target that also exist in props.
 */
function restrict<P extends object, T extends P>(target: T, props: P): Pick<T, keyof P> {
    const t: Partial<T> = { ...target };

    for (let key in target) {
        if (!(key in props)) {
            delete t[key];
        }
    }

    return t as Pick<T, keyof P>;
}

const obj1 = { a: 123, b: 222 };
const obj2 = { b: 0 };

console.log(restrict(obj1, obj2)); // { b: 222 }

Here we end up cloning our target object in order to delete keys from it later. An alternative approach might be to only construct the object with keys in props in the first place. This implementation is at least type-safe and will give you the correct typings for the object returned from restrict.

Lastly, here is our type-safe version of subtract:

/**
 * Create a new object that returns all the values in target that do not exist in props.
 */
function subtract<T extends object, P extends object>(target: T, props: P): Omit<T, keyof P> {
    const t: Partial<T> = { ...target };

    for (let key in props) {
        if (key in t) {
            delete t[key as unknown as keyof T];
        }
    }

    return t as Omit<T, keyof P>;
}

console.log(subtract(obj1, obj2)); // { a: 123 }

Both the restrict and subtract make use of type assertions to tell the compiler we know the actual types of the objects and keys when we are removing keys. Without these assertions, t is still a Partial<T>, even after we delete the keys from the object.

Takeaway

It’s almost always more clear and more type-safe to merge objects using inline spread notation than trying to use a clever utility. There are cases though, like restrict and subtract where we can leverage the type system to write safer code. There is always a balance to find when trying to write utilities between making something easier for engineers, and adding additional compile time safety.

Using Object.create to clone

Ivan Montiel — Mon, 07 Aug 2023 23:15:32 +0000

In “Javascript: The Definitive Guide” there is an example that uses Object.inherit to inherit the prototype change. JavaScript defines a method Object.create that creates a new object using the given argument as the prototype of that object. Translating the examples from The Definitive Guide to Typescript, it looks like:

function inherit<T extends object>(obj: T): T {
    return Object.create(obj);
}

class MyObject {
    public a: number;

    constructor(a: number) {
        this.a = a;
    }
}
const myObject = new MyObject(123);
const myClone = inherit(myObject);

Playground Link

However, we lied. Notice that in the above code, the myClone object was created without a being initialized.

console.log(myObject); // { a: 123 }
console.log(myClone); // {}
console.log(myClone instanceof MyObject); // true

This creates what is known as a type-hole: the Typescript compiler will not report any bugs when we try to use myClone.a. That’s because we used Object.create which returns the any type. In the above example, if we tried to use myClone.a in a case where we expected a number, but got undefined, we can end up with runtime bugs that should have been caught by the compiler.

We can make the typings a little more clear by doing the following:

function inherit<T extends object>(obj: T): Partial<T> {
    return Object.create(obj);
}

Now Typescript will report that the value of myClone.a might be undefined.

Let’s improve this a bit more and create an object that inherits and freezes the data in the given object:

function inheritAndFreeze<T extends object>(obj: T, values: Partial<T>): Readonly<Partial<T>> {
    const properties: PropertyDescriptorMap = {};

    Object.keys(obj).forEach((unsafeKey) => {
        const key = unsafeKey as keyof T;
        properties[key] = {
            value: values[key] ?? undefined,
            writable: false,
                        configurable: false,
        };
    })

    return Object.create(obj, properties);
}

class MyObject {
    public a: number;

    constructor(a: number) {
        this.a = a;
    }
}

const myObject = new MyObject(123);
const myClone = inheritAndFreeze(myObject, { a: 123 });

console.log(myClone); // { a: 123 }
myClone.a = 999; // Would throw "Cannot assign to read only property 'a' of object '#<MyObject>' "

Playground Link

If we didn’t mark the return value as Readonly<Partial<T>>, and instead just had Partial<T> we would once again have a type-hole and myClone.a = 999; would be allowed by Typescript, but would throw an exception at runtime because property a is read only as a runtime constraint.

The Takeaway

Let’s step back and really look at what inherit was doing. All it gave us was a template object, and if you read on MDN about Inheritance and prototype chaining:

You may also see some legacy code using [Object.create()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create) to build the inheritance chain. However, because this reassigns the prototype property and removes the [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) property, it can be more error-prone, while performance gains may not be apparent if the constructors haven't created any instances yet.

The key here is to be wary of using utility functions built into the language that return the any type. Be careful what the Typescript constraints are and make sure you don’t have any type-holes when you are using these generic functions.

Final Thoughts on WAX Smart Contracts

Ivan Montiel — Sun, 06 Aug 2023 23:14:00 +0000

Introduction

Throughout this tutorial, we’ve focused on using Smart Contracts on the WAX Blockchain to create interactive experiences. And while we’ve only scratched the surface on what is possible in WAX, we have seen how powerful the WAX Ecosystem is.

AtomicAssets has enabled us to create rich NFTs without dealing with the infrastructure needed to let users interact with them.

AtomicHub lets us organize and present our NFTs to a wide audience that normally wouldn’t be able to interact with our assets.

The WAX RNG Oracle bakes in a standard way for us to generate guaranteed randomness that our Smart Contracts can use and rely on.

All of this is good, but there are a lot of alternatives that this tutorial didn’t cover.

Alternative Minting Methods

Throughout the tutorials above, we focused on minting NFTs when an action is run. This is extremely useful if you want each NFT to have some unique attributes. In Dark Emblem NFT, we generate a unique image each time an NFT is minted as an example.

However you may have noticed when following along that our Smart Contract needed to have RAM purchased in order to mint those NFTs. The worst thing that could happen to a user is that they try to hatch a BabyChick and the asynchronous mint action fails when trying to mint a BabyChick.

To get around this issue you can take an alternative approach: pre-mint all the NFTs you want, and then just transfer them from the Smart Contract account to the new account owner in your actions.

This is a very common approach when doing large NFT drops. All you have to do is change any mint actions to transfers:

action(
    permission_level{get_self(), name("active")},
    atomicassets::ATOMICASSETS_ACCOUNT,
    name("transfer"),
    make_tuple(
        get_self(), from, (vector<uint64_t>){asset_id}, memo
    )
)
    .send();

And to pre-mint, you can just add onto the existing scripts we used to test minting a single NFT.

Each NFT project is unique, so you will need to think about the pros and cons of each approach before you implement your Smart Contract.

The WAX Ecosystem

Throughout your NFT journey, you may have additional questions, thoughts, or ideas beyond what we covered in this tutorial. Here are some useful places to reach out to in order to continue to learn and promote your NFTs:

The official WAX discord - https://discord.com/servers/wax-blockchain-785124017430331392. The WAX Discord server is a place for NFTs collectors worldwide to chat with each other, discuss the future of WAX, and promote projects.
The official AtomicHub discord - https://discord.com/invite/atomichub. The AtomicHub discord is a great place to discuss Smart Contract code, ask questions, give input into the future of AtomicAssets, and share your AtomicAssets projects.
The official Dark Emblem discord - https://discord.com/invite/v6GDsjuFNa. This is the Dark Emblem NFT discord which a lot of this tutorial is based on. The NFT project and work we do there gives us the knowledge to continue to write and update these tutorials. Come check it out!

There are a few more resources that you may find useful, including the EOSIO documentation since the WAX blockchain is based on EOSIO. Be warned that the documentation has a lot of parity with WAX, but the WAX C++ framework provides additional utilities and macros to make contract writing easier.

And finally, the WAX Developer portal has come a lot way in 2023 - https://developer.wax.io/. When I started worked on Dark Emblem NFT, this was probably the least helpful of all the links mentioned about, but now it has a lot of quality documentation to get started with WAX.

Don’t Forget

Lastly, I want to mention again that all the code we’ve gone through in the tutorials and examples can be found on our Github: https://github.com/CapsuleCat/wax-nft-tutorial.

The repository contains full working examples that were deployed to the WAX testnet.

E-book

Get this entire WAX tutorial as an e-book on Amazon.

Additional links

Photo by Conner Baker on Unsplash

Deploying WAX Smart Contracts to Production

Ivan Montiel — Sun, 06 Aug 2023 23:12:11 +0000

Introduction

Throughout these tutorials, we’ve created our AtomicAssets collection, schema, templates, and deployed a Smart Contract to the testnet that can interact with our AtomicAssets. In this section, we are going to go through the steps required to deploy to production.

We will need to do a few things to launch our WAX NFT to the mainnet:

Create a mainnet WAX Account
Set up our mainnet wallet
Create our AtomicAssets on the Mainnet
Update our Smart Contract
And finally, deploy our Smart Contract to production.

Create a mainnet WAX Account

When we created our WAX Account on the testnet, we were able to use the https://waxsweden.org/create-testnet-account/ site to create a new account. On mainnet, you will need to first create an account through your main WAX Account. See https://eos-amsterdam.medium.com/how-to-create-a-new-wax-account-7a23cf315ac0 for more information.

Setup Your mainnet Wallet

Now that you have a key-pair created for your new WAX account, you will want to import it into your CLI and Anchor wallets.

For the CLI, you can import like we did for the original testwallet we made:

cleos wallet create -n mainwallet --file ./mainnet-secrets

Then unlock the wallet:

cleos wallet unlock -n mainwallet --password="$(cat ./mainnet-secrets)"

And then import your key:

cleos wallet import -n mainwallet --private-key {YOUR ACTIVE_KEY PRIVATE_KEY}

Now you will be able to use your mainwallet to deploy to the mainnet.

Adding to Anchor is the same as we did with the testnet. Simply switch the WAX mainnet blockchain, and import your Private Key.

Create Your mainnet AtomicAsset Collection

When we created our testnet AtomicAsset collections, we wrote them to be flexible enough that we could reuse the same commands for the mainnet. To create the collection, we will use a public mainnet endpoint https://wax.pink.gg/:

WAX_ACCOUNT={YOUR MAINNET ACCOUNT NAME} \
WAX_PRIVATE_KEY="<YOUR WAX ACCOUNT ACTIVE PRIVATE KEY>" \
WAX_ENDPOINT=https://wax.pink.gg \
  node ./src/000-create-collection.js

Then, to create the schemas:

WAX_ACCOUNT={YOUR MAINNET ACCOUNT NAME} \
WAX_PRIVATE_KEY="<YOUR WAX ACCOUNT ACTIVE PRIVATE KEY>" \
WAX_ENDPOINT="https://wax.pink.gg" \
  node ./src/010-create-chick-egg-schema.js

WAX_ACCOUNT={YOUR MAINNET ACCOUNT NAME} \
WAX_PRIVATE_KEY="<YOUR WAX ACCOUNT ACTIVE PRIVATE KEY>" \
WAX_ENDPOINT="https://wax.pink.gg" \
  node ./src/020-create-baby-chick-schema.js

And, to create the templates:

WAX_ACCOUNT={YOUR MAINNET ACCOUNT NAME} \
WAX_PRIVATE_KEY="<YOUR WAX ACCOUNT ACTIVE PRIVATE KEY>" \
WAX_ENDPOINT=<https://wax.pink.gg> \
  node ./src/030-create-chick-egg-templates.js

WAX_ACCOUNT={YOUR MAINNET ACCOUNT NAME} \
WAX_PRIVATE_KEY="<YOUR WAX ACCOUNT ACTIVE PRIVATE KEY>" \
WAX_ENDPOINT=<https://wax.pink.gg> \
  node ./src/040-create-baby-chick-templates.js

Updating Our Smart Contract

Once you have your AtomicAssets created, go to AtomicHub, and find the template ids for the mainnet templates, and update them in the babychick header:

static constexpr name EGG_SCHEMA_NAME = name("chickegg");
static constexpr name BABY_CHICK_SCHEMA_NAME = name("babychick");
static constexpr uint32_t EGG_TEMPLATE_ID = -1; // Set to the mainnet id
static constexpr uint32_t EPIC_TEMPLATE_ID = -1; // Set to the mainnet id
static constexpr uint32_t RARE_TEMPLATE_ID = -1; // Set to the mainnet id
static constexpr uint32_t COMMON_TEMPLATE_ID = -1; // Set to the mainnet id

Once you have updated your values, you can recompile:

rm ./build/babychicks/CMakeFiles/babychicks.dir/babychicks.obj
( cd ./build && cmake .. && make )

Add the code permission to your account:

cleos set account permission <YOUR MAINNET ACCOUNT NAME active --add-code

Buy some RAM for your account:

cleos -v -u https://wax.pink.gg \
  system buyram <YOUR MAINNET ACCOUNT NAME> waxcourse123 "500" --kbytes \
  -p <YOUR MAINNET ACCOUNT NAME>@active

And finally, deploy the contract:

cleos -v -u https://wax.pink.gg set contract <YOUR MAINNET ACCOUNT NAME> ./babychicks/build/babychicks -p <YOUR MAINNET ACCOUNT NAME>@active

Conclusion

And with that, we have successfully deployed a fully functional contract to the production mainnet. This Smart Contract leverages the best-practices of using AtomicAssets to create a fully featured NFT on the WAX blockchain that anyone can interact with. It also provides interactivity, letting users purchase and hatch their NFTs without any other third-party.

This shows just a small set of the awesome experiences that can be built on the WAX Blockchain, we can’t wait to see what you build.

Next post: Final Thoughts on WAX Smart Contracts

E-book

Get this entire WAX tutorial as an e-book on Amazon.

Additional Links

Photo by SpaceX on Unsplash

Interacting with the Hatch Action

Ivan Montiel — Sun, 06 Aug 2023 23:08:41 +0000

Introduction

We’ve implemented our new contract functionality for hatching a BabyChick NFT from a ChickEgg NFT. Now we’ll deploy our contract to the testnet and interact with it to hatch our own NFT on the testnet.

Deploying Our Contract

We can deploy our now updated contract to the testnet. As before, even through we are deploying an updated contract to our account, any tables and data that existed before will not be destroyed in this process.

Let’s unlock our wallet:

cd /wax
cleos wallet open -n testwallet
cleos wallet unlock -n testwallet --password="$(cat ./secrets)"

No we will deploy our contract:

cleos -v -u https://testnet.wax.pink.gg set contract waxcourse123 ./babychicks/build/babychicks -p waxcourse123@active

This command may give you an error if you do not have enough RAM purchased for your account to use:

Reading WASM from /wax/babychicks/build/babychicks/guestbook.wasm...
Publishing contract...
Error 3080001: Account using more than allotted RAM usage
Error Details:
account waxcourse123 has insufficient ram; needs 81572 bytes has 9592 bytes
Stack Trace:
resource_limits.cpp:235 verify_account_ram_usage

In this case, we need to buy RAM for our account. This is a useful command to have bookmarked:

# Remember to change waxcourse123 to your account name
cleos -v -u https://testnet.wax.pink.gg \
  system buyram waxcourse123 waxcourse123 "500" --kbytes \
  -p waxcourse123@active

If everything succeeded, you will see similar output to the following:

In the next section, we’ll send the contract a ChickEgg NFT to test it.

Hatching an Egg

We’ll use AtomicHub for the Wax Testnet to test out our new contract functionality.

Here, we’ve minted and transferred a BabyChick to the account darkemblemts. You’ll want to create a separate account using https://waxsweden.org/create-testnet-account/ to test non-admin functionality and ensure your Smart Contract code works correctly in the context of non-admin users.

Scroll down a bit and you will see a section that says “Transfer”:

Fill in the details for the transfer: To waxcourse123 and Memo hatch:

Once you confirm through Anchor, you will see this message:

Once the wax-orng send a random value back to the contract, it will mint a BabyChick:

Conclusion

We’ve successfully implemented, deployed, and tested our NFT Smart Contract that lets users hatch their NFTs! The Smart Contract we’ve implemented in these last set of tutorials provides quite a bit of interactive functionality that you can build on to give your NFT collection its own unique properties to make it stand out.

Next post: Deploying WAX Smart Contracts to Production

E-book

Get this entire WAX tutorial as an e-book on Amazon.

Additional links

Photo by Christin Hume on Unsplash

Hatching NFTs with the WAX RNG Oracle

Ivan Montiel — Sun, 06 Aug 2023 22:44:08 +0000

Introduction

We’ve minted ChickEgg NFTs in our previous sections. Next, we’ll take those NFTs and let users “hatch” their egg by transferring it to the Smart Contract. We’ll leverage a randomness provider on the WAX blockchain in order to give accounts randomly picked BabyChick NFTs from their egg.

Hatching an Egg

We have all of templates defined, but so far we have only minted ChickEggs. Let’s add onto our existing contract to let users hatch their egg into a BabyChick!

When a user hatches an egg, we want to randomly mint a BabyChick NFT for them. We’ll mint one of the three templates we defined: Epic, Rare, and Common.

In order to do that, we will need to use the WAX RNG Native Blockchain Service which we will call the wax-orng. The flow for how the contracts will interact looks like this:

When the user sends an atomicasset NFT to our BabyChicks contract, we will request a random number from the Oracle. The Oracle will create that random number and call our BabyChick contract asynchronously. Then our BabyChicks contract can take that random value and use it to seed a random number generator. Using that random number generator, we can pick a random template to mint an NFT for the user.

Updating our atomicassets Interface

To start updating the contract, we will need to add onto our atomicassets definitions, but we will also need to add new interfaces and implementations for an orgn interface and Randomness Provider.

First, let’s add onto our existing atomicassets interface header. We’re going to continue to implement parts of the existing atomicassets-interface.hpp from the AtomicAssets Github repository.

In order to check what NFT was sent to our contract, we’ll need the following sectino of the atomicassets-interface:

// Scope: owner
struct assets_s {
    uint64_t asset_id;
    name collection_name;
    name schema_name;
    int32_t template_id;
    name ram_payer;
    std::vector<asset> backed_tokens;
    std::vector<uint8_t> immutable_serialized_data;
    std::vector<uint8_t> mutable_serialized_data;

    uint64_t primary_key() const { return asset_id; };
};
typedef multi_index<name("assets"), assets_s> assets_t;

assets_t get_assets(name acc) {
    return assets_t(ATOMICASSETS_ACCOUNT, acc.value);
}

The get_assets interface will let us find all of the assets that belong to a given account. In our case, that will the be account we deploy the BabyChicks contract too.

Adding the RNG Oracle Interface

The orng interface will provide us with the methods to interact with the wax-orng contract. We’ll need to send that contract a signing value, which will require the following definitions:

namespace orng {
static constexpr name ORNG_CONTRACT = name("orng.wax");

TABLE signvals_a {
    uint64_t signing_value;

    auto primary_key() const { return signing_value; }
};
typedef multi_index<name("signvals.a"), signvals_a> signvals_t;

signvals_t signvals = signvals_t(ORNG_CONTRACT, ORNG_CONTRACT.value);
} // namespace orng

Creating a Randomness Provider

The random oracle will send us a checksum256 random_value when creating a random value for our contract. We will need to take that checksum value and use it to create a random number generator.

Without going too deep into exactly what we are doing, here is the implementation for the RandomnessProvider:

class RandomnessProvider {
  public:
    RandomnessProvider(checksum256 random_seed) {
        raw_values = random_seed.extract_as_byte_array();
        offset = 0;
    }

    uint64_t get_uint64() {
        if (offset > 24) {
            regenerate_raw_values();
        }

        uint64_t value = 0;
        for (int i = 0; i < 8; i++) {
            value = (value << 8) + raw_values[offset];
            offset++;
        }
        return value;
    }

    uint32_t get_rand(uint32_t max_value) {
        return get_uint64() % ((uint64_t)max_value);
    }

  private:
    void regenerate_raw_values() {
        checksum256 new_hash = eosio::sha256((char *)raw_values.data(), 32);
        raw_values = new_hash.extract_as_byte_array();
        offset = 0;
    }

    std::array<uint8_t, 32> raw_values;
    int offset;
};

This class provided methods for getting a random uint64, or use the helper method to get a random value from [0, max_value).

Updating Our Contract Header

Let’s update the header with some additional constants we will need and new class definitions for our contract.

First, we’ll need the template ids for the BabyChick NFTs we will mint:

Common template: https://wax-test.atomichub.io/explorer/template/wax-testnet/babychicknft/629369
Rare template: https://wax-test.atomichub.io/explorer/template/wax-testnet/babychicknft/629368
Epic template: https://wax-test.atomichub.io/explorer/template/wax-testnet/babychicknft/629367

Let’s add to our babychick_constants:

namespace babychick_constants {
//...
static constexpr name EGG_SCHEMA_NAME = name("chickegg");
static constexpr name BABY_CHICK_SCHEMA_NAME = name("babychick");
static constexpr uint32_t EGG_TEMPLATE_ID = 629366;
static constexpr uint32_t EPIC_TEMPLATE_ID = 629367;
static constexpr uint32_t RARE_TEMPLATE_ID = 629368;
static constexpr uint32_t COMMON_TEMPLATE_ID = 629369;
}

Then, in the contract definition, we can add the following public definitions which we will cover in more depth later:

[[eosio::on_notify("atomicassets::transfer")]] void receive_asset_transfer(
    name from, name to, std::vector<uint64_t> asset_ids, std::string memo
);

ACTION receiverand(uint64_t assoc_id, checksum256 random_value);
using receiverand_action =
    action_wrapper<"receiverand"_n, &babychicks::receiverand>;

We’ll also need some new private helper functions:

void check_unbox_egg(name from, uint64_t asset_id);
void unbox_egg(name from, uint64_t asset_id);
void rng_response_unbox_egg(uint64_t assoc_id, checksum256 random_value);

uint64_t create_signing_value();

Lastly, we will need to create a table to store associate the account and NFT with the values we send to the wax-orng contract:

TABLE rngqueue_s {
    uint64_t assoc_id;
    name from;
    uint32_t timestamp;
    std::string memo;

    uint64_t primary_key() const { return assoc_id; }
    uint64_t by_from() const { return from.value; }
};
typedef multi_index<name("rngqueue"), rngqueue_s> rngqueue_t;
rngqueue_t rngqueue = rngqueue_t(get_self(), get_self().value);

This will let us store the NFT’s asset_id as the assoc_id which we will send to wax-orng. We will also store some additional metadata about the queue state.

Receiving AtomicAssets and Calling the Oracle

When we updated the header file,babychicks.hpp, we added a new definition for hooking onto atomicasset transfers. When an atomicasset NFT is transferred to our contract, this method will run:

[[eosio::on_notify("atomicassets::transfer")]] void receive_asset_transfer(
    name from, name to, vector<uint64_t> asset_ids, string memo
);

Let’s look at the implementation for that and how we will call the wax-orng contract.

/**
 * @brief Listen for NFT transfers to this contract
 *
 * @param from
 * @param to
 * @param asset_ids
 * @param memo
 */
void babychicks::receive_asset_transfer(
    name from, name to, std::vector<uint64_t> asset_ids, std::string memo
) {
    // Ignore EOSIO system account transfers
    const std::set<name> ignore = std::set<name>{
        atomicassets::ATOMICASSETS_ACCOUNT,
        // EOSIO system accounts
        name("eosio.stake"),
        name("eosio.names"),
        name("eosio.ram"),
        name("eosio.rex"),
        name("eosio")};

    if (to != get_self() || ignore.find(from) != ignore.end()) {
        return;
    }

    if (asset_ids.size() != 1) {
        check(false, "Only one asset can be transferred at a time");
    }

    if (memo == "hatch") {
        check_unbox_egg(from, asset_ids[0]);
    } else {
        check(false, "invalid memo");
    }
}

When we receive an NFT transfer, we need to verify that the transfer is coming from a normal account, so we filter out checks from EOSIO system transfers.

Our contract will only handle single NFT transfers, so we fail early if an account sends more than one NFT.

Lastly, we want to ensure that the account meant to send us the NFT, so we expect the transfer to have a memo with “hatch” in it.

You’ll notice that the transfer said nothing about the asset that was transferred to our contract. In check_unbox_egg, we will add additional guards to check that an account hasn’t sent a different NFT to our contract to try to trick us into minting a BabyChick incorrectly.

/**
 * @brief Check if the asset is a ChickEgg and unbox it
 * 
 * @param from 
 * @param asset_id 
 */
void babychicks::check_unbox_egg(name from, uint64_t asset_id) {
    atomicassets::assets_t own_assets = atomicassets::get_assets(get_self());

    // Verify that the asset the user sent us is a ChickEgg
    auto pack_asset_iter =
        own_assets.require_find(asset_id, "Asset could not be found");

    check(
        pack_asset_iter->template_id == babychick_constants::EGG_TEMPLATE_ID,
        "Asset is not a ChickEgg"
    );

    unbox_egg(from, asset_id);
}

Here we use the new atomicassets interface changes that we added to get the contract’s assets, find the asset_id that was transferred. If we find it, we additionally check that the template_id matched the template_id that we minted.

Once which guarded our contract, we can unbox the egg by sending a random request to the oracle:

/**
 * @brief Unbox an egg
 * 
 * @param from 
 * @param asset_id 
 */
void babychicks::unbox_egg(name from, uint64_t asset_id) {
    uint64_t signing_value = create_signing_value();

    rngqueue.emplace(get_self(), [&](auto &_queue) {
        _queue.assoc_id = asset_id;
        _queue.from = from;
        _queue.timestamp = now();
        _queue.memo = "hatch";
    });

    action(
        permission_level{get_self(), name("active")},
        orng::ORNG_CONTRACT,
        name("requestrand"),
        std::make_tuple(asset_id, signing_value, get_self())
    )
        .send();
}

Here we create a signing value to send to the oracle, create an entry in our own contract’s table to store the asset_id, account, plus some metadata, and then send a request random action to the wax-orng contract.

Getting a random value is an asynchronous process, which is why we store the asset_id and account information in our own contract since we will need it to look up who to mint the BabyChick NFT for when the oracle calls our contract with the random value.

The implementation for create_signing_value isn’t too important, but we need to create a unique signing value to send to the wax-orng contract:

/**
 * @brief Create a signing value to use with the oracle request
 * 
 * @return uint64_t 
 */
uint64_t babychicks::create_signing_value() {
    // Create a signing key for the pack
    size_t size = eosio::transaction_size();
    char buf[size];
    uint32_t read = eosio::read_transaction(buf, size);

    check(
        size == read, "Signing value generation: read_transaction() has failed."
    );
    checksum256 tx_id = eosio::sha256(buf, read);
    uint64_t signing_value;
    memcpy(&signing_value, tx_id.data(), sizeof(signing_value));

    // Check if the signing_value was already used.
    // If that is the case, increment the signing_value until a non-used
    // value is found
    while (orng::signvals.find(signing_value) != orng::signvals.end()) {
        signing_value++;
    }

    return signing_value;
}

Minting a BabyChick/Burning a ChickEgg

Once the wax-orng contract creates a random value for us, it will call the following definition that we added to our header file:

ACTION receiverand(uint64_t assoc_id, checksum256 random_value);
using receiverand_action =
    action_wrapper<"receiverand"_n, &babychicks::receiverand>;

The flow for how we handle random values is similar to how we handled atomicassets transfers: first we will check that the function is being called correctly, then we will burn the egg NFT and mint a BabyChick NFT.

The implementation for the receiverand function looks like:

/**
 * @brief Determine how to handle the Oracle response
 * 
 * @param assoc_id 
 * @param random_value 
 * @return ACTION 
 */
ACTION babychicks::receiverand(uint64_t assoc_id, checksum256 random_value) {
    // ensure that only the WAX RNG oracle can call this function
    check(
        has_auth(orng::ORNG_CONTRACT) || has_auth(get_self()),
        "Caller must be WAX RNG oracle"
    );

    auto randomqueue_itr = rngqueue.require_find(
        assoc_id, "Could not find associated randomness id"
    );

    if (randomqueue_itr->memo == "hatch") {
        rng_response_unbox_egg(assoc_id, random_value);
    } else {
        check(false, "invalid memo");
    }
}

First, we check that the correct account is calling this function. Only the wax-orng account or the account the contract is deployed to can call the function. We allow the contract owner to call the function to help with debugging.

Once we have checked the caller, we can verify that the assoc_id actually has an entry in our table. We used the asset_id for this.

Finally, just like how we had a memo for the initial NFT transfer, we added the memo to the table. This helps us route what to do with the random value we were given.

Next, let’s implement the rng_response_unbox_egg which will determine which template to mint, call a function to mint the BabyChick, and then burn the ChickEgg NFT:

/**
 * @brief determine a random number and mint a BabyChick
 * with a random template id
 * 
 * @param assoc_id 
 * @param random_value 
 */
void babychicks::rng_response_unbox_egg(
    uint64_t assoc_id, checksum256 random_value
) {
    auto randomqueue_itr = rngqueue.require_find(
        assoc_id, "Could not find the associated randomness id"
    );

    RandomnessProvider randomness_provider(random_value);
    uint16_t random_range = randomness_provider.get_rand(10);

    // Mint BabyChick
    if (random_range >= 9) {
        mint_baby_chick(
            randomqueue_itr->from, babychick_constants::EPIC_TEMPLATE_ID
        );
    } else if (random_range > 5) {
        mint_baby_chick(
            randomqueue_itr->from, babychick_constants::RARE_TEMPLATE_ID
        );
    } else {
        mint_baby_chick(
            randomqueue_itr->from, babychick_constants::COMMON_TEMPLATE_ID
        );
    }

    // Burn the ChickEgg
    action(
        permission_level{get_self(), name("active")},
        atomicassets::ATOMICASSETS_ACCOUNT,
        name("burnasset"),
        std::make_tuple(get_self(), assoc_id)
    )
        .send();

    // Delete table entry
    rngqueue.erase(randomqueue_itr);
}

Here, we use the RandomnessProvider to take the checksum256 value and provide a class that will let us get a random value from 0 to 10.

We the determine which template to use by using the random value. Since it is giving us a number from 0 (inclusive) to 10 (exclusive), we can check if that number is greater than some value.

In the above implementation, we have:

9 - 10% chance - Epic template
5, 6, 7, 8 - 40% - Rare template
0, 1, 2, 3, 4 - 50% - Common template

Lastly, let’s mint that BabyChick!

/**
 * @brief Mint a BabyChick NFT
 * 
 * @param receiver 
 * @param template_id 
 */
void babychicks::mint_baby_chick(name receiver, uint32_t template_id) {
    action(
        permission_level{get_self(), name("active")},
        atomicassets::ATOMICASSETS_ACCOUNT,
        name("mintasset"),
        std::make_tuple(
            get_self(),
            babychick_constants::COLLECTION_NAME.value,
            babychick_constants::BABY_CHICK_SCHEMA_NAME.value,
            template_id,
            receiver,
            // immutable data
            (atomicassets::ATTRIBUTE_MAP){{"created_at", (uint64_t)now()}},
            // mutable data
            (atomicassets::ATTRIBUTE_MAP){},
            // backing assets
            (std::vector<asset>){}
        )
    )
        .send();
}

This is very similar to how we minted a ChickEgg in the previous sections.

Building

Let’s build the contract to verify that it compiles:

( cd ./build && cmake .. && make )

If you need to rebuild the contract, you may want to delete the build targets to ensure that the build is up to date:

rm ./build/babychicks/CMakeFiles/babychicks.dir/babychicks.obj

Conclusion

In this section, we went over implementing a listener to AtomicAsset transfers, calling the RNG Oracle, and then using the random value provided to mint a random BabyChick.

Next, we’ll deploy and interact with our contract.

Next post: Interacting with the Hatch Action

E-book

Get this entire WAX tutorial as an e-book on Amazon.

Additional links

Github: https://github.com/CapsuleCat/wax-nft-tutorial/tree/main/babychicks
Photo by Ali Kazal on Unsplash

Using AtomicHub

Ivan Montiel — Sun, 06 Aug 2023 22:34:15 +0000

Introduction

Now that we have created a collection, schema, and templates, and minted some NFTs, let’s explore how those NFTs will show up in the most popular NFT platform for WAX: AtomicHub.

What is AtomicHub

Throughout these tutorials, we’ve mentioned AtomicAssets as a contract that we have used to mint NFTs. Built on top of AtomicAssets is AtomicHub - a web-based marketplace that shows collections, templates, schemas, and NFTs.

For our purposes, we are going to work with the testnet version of AtomicHub: https://wax-test.atomichub.io/.

AtomicHub allows creators, collectors, and traders to buy, sell, and trade NFTs. It acts as a marketplace as well, letting users buy, sell, and bid on NFTs.

Interacting on AtomicHub

When we created out NFT on AtomicAssets, the collection, schemas, and templates automatically show up on AtomicHub. Here we can see the collection:

https://wax-test.atomichub.io/explorer/collection/wax-testnet/babychicknft.

You can see that the IPFS images that we set up before when creating our templates are being used and displayed on the AtomicHub site.

If we click on an asset, such as this one https://wax-test.atomichub.io/explorer/asset/1099558399043, we get to see the IPFS image and all of the details as well.

By using a template with a max minting, users also get to see a nice “3 of 3 (max: 100)” for the mint number. Some users covet having lower mint numbers, and knowing how many are left is important to understanding the market for the given collection and NFT.

Conclusion

In this section, we went over AtomicHub and how collections end up being displayed on it. Making sure you setup your collection correctly so that it displays all the relevant information on AtomicHub is important. It acts as the face of your NFT to most users and AtomicHub can serve as additional advertising for your project.

Next post: Hatching NFTs with the WAX RNG Oracle

E-book

Get this entire WAX tutorial as an e-book on Amazon.