This document will walk you through all the concepts you need to know to understand how you can build and publish a Generative Token (GT) on fxhash.
Table of Contents
- Knowledge requirements
- General overview
- How to build a Generative Token
- How is a Generative Token structured
- Leverage fxhash modules for your projects
- How to publish (mint) a GT
- Guidelines
- Best practices and common mistakes
- 3 ways to start a project
- Have fun
Knowledge requirements
GT on fxhash can only be written in html/css/javascript. Ultimately, GT are documents which can be interpreted by a web browser. When someone will collect an iteration of your GT, the web document you created will be used and the unique data for the given iteration will be injected into the document. Don't worry, as an artist, the generation process is automated, and if you follow the guidelines it should be straightforward to implement a GT. However, you will need to know how to render graphics within a web document to use the platform.
General overview
This section will give you a rough overview of the Generative Tokens on fxhash. Don't worry if some informations are missing for you to properly understand the process, some particular aspects are covered in other parts of our documentation.
Upload and mint a GT
First, you upload your project and mint it as a Generative Token. This project is a tiny website which sole purpose is to generate some visual/audio based on a 51-characters base 58 encoded number (Tezos transaction hashes have the same signature). The project needs to be designed in a way that, when the same string is given to it, it always produces the same output. However, a different string should produce a different output.
Your project is stored
Your project will be stored on the IPFS network, and then stored on the tezos blockchain. It ensures its immutability.
People mint a unique token from your GT
When a GT is published on the platform, anyone will be able to mint unique iterations from it. When such an event arises, the mint transaction generates a unique hash. The hash is sent as a URL parameter to your project. A code snippet is used to get this hash from the URL so that it can be used in your code.
Image preview
When a token is minted, fxhash provides a service to generate a preview, which will be attached to the tokens as an alternate way to visualize them.
How to build a Generative Token
To facilitate the creation of fxhash projects, we have created a fully-featured development environment. We recommend its usage to remove the pain of setting up the files manually.
How is a Generative Token structured
This section covers different aspect on the structure and specifications of Generative Tokens. If you are using the fxhash boilerplate, many of the requirements are supported out-of-the-box.
Project structure
All the files needed by your project must be in the same directory, with an index.html file at its root.
Resources
When you link to a file in your index.html, paths must be relative.
src="./path/to/file.js"-> OKsrc="/path/to/file.js"-> NOT OK
You can use as many sub-directories as you see fit.
fxhash code snippet
fxhash requires projects to inject a code snippet in the <head> section of the index.html. This snippet exposes an API to interact with fxhash modules, described in the Snippet API documentation.
Zip, test & mint
Once you are done developing your GT, you will need to compress all of its content into a ZIP archive. fxhash only accepts the ZIP format. The index.html file must be located at the root of the archive.
Once you have your ZIP file, you can check that it behaves properly by uploading it to the sandbox. The sandbox can be used as a quick way to test your project.
Once you have properly tested your project, you can mint it by following the instructions on the page.
Leverage fxhash modules for your projects
fxhash is built with modularity in mind. The snippet injected into the code gives access to those various modules, listed below.
fx(params): gives artists the option to define a set of parameters collectors will modulate before minting their iterationfeatures: can be used to expose the features of an iteration
How to publish (mint) a GT
Sync your wallet
First of all, you will need to have a Tezos wallet synced with fxhash.
Mint your GT
Once your GT is ready to be published (once it's been carefully tested in the sandbox), you can open the mint page. This page will guide you through the different steps of the process:
- authoring: select who's authoring the piece: yourself alone or collaboration ?
- upload to IPFS: drop your .ZIP file and wait until it gets uploaded to IPFS through fxhash servers
- check files: check again if your project behaves properly once uploaded to IPFS. Also if you implemented features, check if they work properly. This step is also used to configure which hash will be used for the preview of your project.
- configure capture: select the capture mode and configure it. Also check if the capture is working properly
- verifications: a comparative check between the preview & the live version
- distribution: number of editions, pricing & general distribution settings
- explore variation settings: configure the variations a collector can explore when viewing your token
- project details: contextual informations about your piece
- preview & mint: a preview of your project once published, and the mint button
There are lots of steps, but each step is required for your project to be released in the best possible conditions.
You can find more information on individual steps in the following articles:
Guidelines
Some guidelines must be followed to ensure your Generative Token works properly.
Network requests
You cannot make any network request. If you need an external library/font/image, you must put it in your project folder. I know, this isn't an ideal workflow, but the point is to create self-contained tokens which can execute properly regardless of external conditions.
Respond to window size
Your web page must be responsive (ie adapt itself to any screen size). Moreover, we advise that your application should respond to the "resize" event of the "window". It may eventually happen in the lifetime of the tokens that the viewport size changes during its execution. If you want to keep a fixed size canvas, you can do so, and maybe center the canvas in the viewport.
Random numbers generation
Your program must use pseudorandom number generation with a seed, where the seed is the fxhash variable. You can use the $fx.rand() function for that matter.
Other
- the ZIP file must be <= 30 MB. Please try to optimize your projects as much as possible.
Best practices and common mistakes
A list of best practices and common mistakes (and how to fix them) to ensure that your token has as long a life as possible.
Test often
This section comes first as it's the most important in ensuring that your token is as good as you can make it. Remember that once you release, you can't edit the token, so make sure to test as often as you can when developing.
Testing often will also allow you to catch problems early that would become big issues later on. Nobody likes to get to the minting stage - or worse, selling out - only to discover that their token doesn't work properly.
Resolutions and DPRs
Ensure your token looks the same in all resolutions and DPRs.
It is ideal if your token produces the same artwork at different sizes. Make sure to test your token often at different resolutions and DPRs. One of the most common pitfalls that artists fall into is not doing so and having their tokens look different at different sizes - as well as different to the preview - as a result.
There are a number of different ways of getting your token to work in a resolution independent manor. Jump into the creator-support channel if you'd like to ask any questions.
WebGL
WebGL is a big subject and there are a number of items worth talking about in relation to it.
Power of two textures and framebuffers
Some GPUs allow you to specify non power of two textures and framebuffers, however using non power of two textures and framebuffers will break the preview system.
WebGL on different silicone
WebGL is an emulation layer on top of different graphics APIs which talk to hardware, as such implementation of basic things like sine calculation and float precision can vary.
One important thing to remember about WebGL is that you should be doing as muchof your calculation up-front, in javascript, and providing those values to WebGL as uniforms.
WebGL and previews
As of right now the preview system doesn't have a GPU. As such, rendering your scene falls to the CPU, which will render WebGL but at an extremely low framerate.
If your token is WebGL then you want to make sure that you're rendering an accepable preview in the first couple of frames.
Computational complexity and previews
If your token is computationally expensive, then it's possible that the preview system will stumble over it and the signer will not be able to sign mints! Please be aware that there exist ways to generate less complex previews for your tokens, but the implementation of this necessarily needs to fall on you, the artist. Jump into the creator-support channel if you'd like to ask any questions.
Test often
This is such an important point that it bears mentioning twice.
- Test often
- Test in many different environments
- Test using the same hash at different resolutions
- Test in the sandbox as well as standalone
3 ways to start a project
This section will provide you with some boilerplate projects to make the development on your GT easier.
Using our main boilerplate (recommended)
We encourage you to use our fxhash boilerplate, specifically designed to create projects for fxhash.
It comes with the following features:
- already setup: code snippet is injected, you can start to work on your content immediately
- local environment with Live Reload so that you can iterate faster on your projects
- fx(lens): an interface to explore your code with different hashes, and a display of controllers to modulate the params defined in your code
- javascript imports: you can import npm packages, use the import syntax, and webpack will bundle everything in a single minified javascript file
- automated deployment: run a command to build your files and create a ZIP archive ready to be deployed on fxhash
Using our simple boilerplate
We also provide a simple boilerplate, with a single html and javascript file. The snippet is already injected, but that's it. If you want to work with fx(params) you will need to provide the input bytes yourself, or use fx(lens).
Starting from scratch
You can also start from scratch, just remember to inject the snippet in the <head> of your index, before importing your scripts. Similar to the simple boilerplate, you will need fx(lens) to work with fx(params).
Have fun
We hope this guide will cover most of what you need to know to build tokens on fxhash. If you have any issues, feel free to join our Discord server.