You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 8, 2026. It is now read-only.
Copy file name to clipboardExpand all lines: docs/onboarding.md
+72-19Lines changed: 72 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,26 @@
1
1
# Onboarding (Self-service)
2
2
3
+
## Pre-requisites
4
+
5
+
- Node.js v18 (LTS) or later.
6
+
- An Alchemy API key. You can create an account and get an API key following this [quickstart guide](https://docs.alchemy.com/docs/alchemy-quickstart-guide).
7
+
- A MetaMask wallet with some Sepolia testnet ETH. You can get testnet ETH from the [Etherem Sepolia faucet](https://www.alchemy.com/faucets/ethereum-sepolia).
8
+
- Alternatively, you can use the [Sepolia PoW faucet](https://sepolia-faucet.pk910.de/).
9
+
- You will need to export the private key of the wallet you want to use for onboarding.
10
+
- A collection contract deployed on Immutable X. You can deploy a collection contract following this [guide](https://github.com/immutable/contracts/blob/main/deploy/x/README.md)
11
+
12
+
### Immutable Developer Hub
13
+
14
+
Register with your email address at the [Immutable Developer Hub](https://hub.immutable.com) to get access to customized documentation in the hub as well as the ability to create Immutable X and Immutable zkEVM projects on Immutable.
15
+
16
+
You must first have a project in order to create collections that you can mint assets from on Immutable (L2).
17
+
18
+
For this onboarding guide, we will need to create an **Immutable X** project. Make sure you note down the Legacy ID of the project from the project overview page.
19
+
20
+
If you have already created an account, and have a Immutable X project, you can skip this step.
21
+
22
+
## Getting started
23
+
3
24
To begin, clone this repository:
4
25
5
26
```sh
@@ -14,30 +35,22 @@ Copy environment file
14
35
cp .env.example .env
15
36
```
16
37
17
-
Set the onboarding private key in `.env`. Your private key will be used to create a signed payload only and will not be sent to our backend services.
18
-
19
-
```sh
20
-
OWNER_ACCOUNT_PRIVATE_KEY=YOUR_PRIVATE_KEY
21
-
```
22
-
23
-
Set the `API_KEY` in the `.env` file. You can create and manage your API key in the [Immutable Hub](https://hub.immutable.com/). The Immutable Hub serves as a portal for creating, displaying, and refreshing API keys. Navigate to the "API Keys" menu item within your chosen project and environment to manage or create your API keys.
38
+
Set the environment variables in the `.env` file:
24
39
25
-
```sh
26
-
API_KEY=YOUR_SECRET_API_KEY
27
-
```
40
+
| Field Name | Description |
41
+
| ----------------------------- | ----------- |
42
+
|`ALCHEMY_API_KEY`| The Alchemy API key. |
43
+
|`API_KEY`| The API key generated from your environment's API Key page in the Immutable Hub. |
## 0. Register with your email for the Immutable Developer Hub
36
-
37
-
Register with your email address at the [Immutable Developer Hub](https://hub.immutable.com) to get access to customized documentation in the hub as well as the ability to create projects on Immutable via the [Public API](https://docs.x.immutable.com/reference#/operations/createProject) or the CLI in this repo.
38
-
39
-
You must first have a project in order to create collections that you can mint assets from on Immutable (L2).
40
-
41
54
## 1. Register as a user with Immutable X
42
55
43
56
We provide an authentication service to protect your administrative level assets from being accessed or updated by someone else. This is done using a simliar technique as described [here](https://link.medium.com/CVTcj7YfQkb).
@@ -56,11 +69,15 @@ npm run onboarding:user-registration
56
69
57
70
Follow the guide at [here](https://docs.immutable.com/docs/x/launch-collection/register-project) to create a project in the [Immutable Hub](https://hub.immutable.com).
58
71
59
-
## 3. Add a collection
72
+
- Ensure you create a project for the **`Immutable X`** rollup.
73
+
74
+
## 3. Create a collection
60
75
61
76
A collection refers to a smart contract you have deployed. Minted assets belong to a collection. In order to mint assets on L2
62
77
you must first register your collection (smart contract) with Immutable X.
63
78
79
+
If you have not deployed a collection contract, you can follow the guide [here](https://github.com/immutable/contracts/blob/main/deploy/x/README.md) to deploy a Asset collection contract.
80
+
64
81
Add the collection contract address to the environment variable `COLLECTION_CONTRACT_ADDRESS`.
65
82
66
83
Set `COLLECTION_PROJECT_ID` to the legacy ID in your created environment's overview page from step 2.
@@ -81,9 +98,19 @@ npm run onboarding:create-collection
81
98
82
99
If you see a `replacement transaction underpriced` error message when trying to run `create-collection` please try again in 5 minutes.
83
100
101
+
There is a convenience script to get the info of the newly created collection:
102
+
103
+
```sh
104
+
npm run public:get-collection-info
105
+
```
106
+
107
+
The collection should also be visible in the [Immutable Hub](https://hub.immutable.com).
108
+
84
109
## 4. Add metadata schema to your collection
85
110
86
-
Update the values in file `4-add-metadata-schema.ts` with the values of the metadata you want to define.
111
+
Update the `4-add-metadata-schema.ts` file with the metadata schema values you want to define. The metadata schema is used to define the structure of the metadata that will be associated with the NFTs in your collection.
112
+
113
+
Descriptions of the metadata schema fields can be found [here](https://docs.immutable.com/docs/x/launch-collection/register-metadata-schema#metadata-schema).
87
114
88
115
Once updated, run the following script to create your collection:
89
116
@@ -92,3 +119,29 @@ _Requires environment variables `OWNER_ACCOUNT_PRIVATE_KEY` and `COLLECTION_CONT
92
119
```sh
93
120
npm run onboarding:add-metadata-schema
94
121
```
122
+
123
+
If you want to add additional metadata schemas, you can do so by adding more objects to the `metadata` array, and remove any existing metadata schemas from the `metadata` array, and then run the script again.
124
+
125
+
If you want to change the properties of an existing field, you can use the `updateMetadataSchemaByName` function instead. There is an example of this in the `4-add-metadata-schema.ts` file.
126
+
127
+
## 5. Mint NFTs
128
+
129
+
There is an minting example script, `5-mint-nfts.ts`, which is used to mint example NFTs to a wallet.
130
+
131
+
The default behaviour is to mint the NFTs to the wallet that owns the `OWNER_ACCOUNT_PRIVATE_KEY`. If you want to mint the NFTs to a different wallet, you can uncomment and update the `mintRecipient` value passed to the `mint` function in the script.
132
+
133
+
Also take a look at the example token objects in `tokens` array and update the blueprint values to your liking.
134
+
135
+
For a deeper explanation of the blueprint string, see the [Deep dive into metadata section] in the Immutable X documentation(https://docs.immutable.com/docs/x/deep-dive-metadata#providing-a-blueprint-string-when-token-is-minted-on-l2).
136
+
137
+
_Requires environment variables `OWNER_ACCOUNT_PRIVATE_KEY` and `COLLECTION_CONTRACT_ADDRESS` to be set._
138
+
139
+
```sh
140
+
npm run onboarding:mint
141
+
```
142
+
143
+
Once the NFTs have been minted, you can run the following script to get the info of the minted NFTs in the collection:
0 commit comments