Links
Comment on page

Launch your Chainlet

Introduction

To launch a chainlet, you will need the following:
To launch a chainlet, you will need the following:
  1. 1.
    Chainlet type you wish to launch
  2. 2.
    Chainlet type version you wish to launch
  3. 3.
    An account in sagacli that has funds to cover the chainlet launch and the subsequent billing of the chainlet.

Chainlet Types

Ok, let's take this one step at a time! In order to list the chainlet types and versions that are available to be launched on SAGA Platform, you can use the following command:
sagacli chainlet list-types
This command will have a similar output to this:
$ sagacli chainlet list-types
DisplayName Description Creator Version SetupCost EpochCost
----------- ----------- ------- ------- --------- ---------
SagaOS SagaOS Chainlet Stack saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 0.5.2 10000000upsaga 10000000upsaga/day
Chainlet types are added at the moment by admins, members of the SAGA engineering team. In the near future, this will be done in a decentralized manner via a community governance process

Launching a Chainlet

All chainlets launched will require a setup fee and a 30-day upfront deposit of the epoch fee
Please ensure you have sufficient funds available in the launcher's wallet to successfully launch a chainlet
See Chainlet Billing for details
To launch a chainlet of type sagaos, you would execute the following command:
$ sagacli chainlet launch SagaOS 0.5.2 magicwarriors --dac-enable --genesis-account 1B610FA944818999B476BAB267145BF5D923B552:10000000000 --denom mpt --fees 2500upsaga
You are about to sign and broadcast a transaction, with the following configurations:
* Keyname: shan
* Keyring: os
* Address: saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju
* Network RPC: https://spc.testnet-sp1.sagarpc.io
* Platform chain id: spc-testnet-1
* Ledger: false
* Message Detail:
creator:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju"
maintainers:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju"
chainletStackName:"SagaOS"
chainletStackVersion:"0.5.2"
chainId:"magicwarriors_1698442321102101-1"
chainletName:"magicwarriors"
params:<denom:"mpt"
gasLimit:10000000
genAcctBalances:<list:<address:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju"
balance:"100000000"
>
>
>
Do you want to proceed? (y/N):
y
2023-03-25T01:12:22-05:00 INF tx broadcasted to the remote node code=0 gas_used=125370 gas_wanted=200000 hash=1AA884883BE6A92D3CC5C50DCBAD82A988A5CD8BBEB22CC9505357C45ABF1143
That was a lot to take in at the same time! Let's break that down and take a look at each parameter provided to the command we executed above. Here is the command again:
sagacli chainlet launch SagaOS 0.5.2 magicwarriors --dac-enable \
--genesis-account 1B610FA944818999B476BAB267145BF5D923B552:10000000000 --denom mpt
sagacli chainlet launch
enables access to the chainlet launch capability of sagacli
SagaOS
indicates the chainlet type we are launching
0.5.2
indicates the version of the chainlet type we want to use for the chainlet. Note that there can be multiple versions of a chainlet type, which often happens when the chainlet of a specific type is updated and enhanced, or patched
magicwarriors
this is what we want to call the chainlet i.e. the chainlet's name, it will be part of the new chainlet chain-id and will be used for the RPC endpoints and Explorer URLs of this new chainlet
--dac-enable
this flag enables deployment access control for the chainlet so that multiple users (sagacli accounts) can be tagged as chainlet admins and/or as accounts that are allowed to deploy smart contracts on the chainlet (see hint below this table). No other account will be allowed to deploy smart contracts on this chainlet if this flag is provided!
--genesis-account
this is a list of hex addresses along with their respective balances that we want to allocate at chainlet genesis i.e. the chainlet will be launched with these addresses holding the specified balance in tokens.
--fees
The fee to pay for this chainlet launch transaction
To add additional admins to your chainlet, add their addresses using the --maintainers flag when launching the chainlet.
This flag is a comma separated list of chainlet admins. The address following the maintainer flag is the account that will be added as a chainlet admin, giving this address the ability to deploy smart contracts.
IMPORTANT: The above chainlet has been launched by the address associated with the default key (refer to Configuring a Default Key in sagacli). If you wish to use a different key to sign the launch chainlet transaction (which will set the address of that key as the chainlet owner), simply append the --from <keyname> flag to the sagacli chainlet launch command.
Example: sagacli chainlet launch <chainlet launch parms> --from mykey2

Chainlet Launch Options

Chainlets can be launched using some powerful tools and options. They are explained in detail in this section.
Note that all flags are passed prefixed with double-dashs e.g. --denom for passing the denom flag.
IMPORTANT: These are important parameters that are set ONLY at creation time and can't be changed after the chainlet has been launched and genesis happened.
Option Flag
Description
denom
Coin denomination for the chainlet e.g. mytoken.This parameter is optional.
evm-chain-id
A chain Id for your chainlet. This is a number without any other characters. This should be unique, especially if you are integrating your chainlet with MetaMask or any other wallet. [Default: Unix milliseconds since epoch]. This parameter is optional.
fee-account
An account that will collect all of the transaction fees on the chainlet. This parameter is optional.
fees
Fees to pay along with the transaction
fixed-base-fee
A configurable base fee to be paid on transactions occurring on chainlets. Warning: Setting this to 0 may open your chainlet to spam attacks. Using this setting will change the the base gas cost, which is normally changed by the protocol automatically. This parameter is optional.
gas
Gas limit to set per-transaction; set to "auto" to calculate sufficient gas automatically. Note: "auto" option doesn't always report accurate results. Set a valid coin value to adjust the result. Can be used instead of "fees". (default 200000). This parameter is optional
gas-limit
Chainlet transactions gas limit (default 10000000). This parameter is optional
genesis-account
An array of hex addresses along with their respective balances that we want to allocate at chainlet genesis i.e. the chainlet will be launched with these addresses holding the specified balance in tokens. This parameter is required.
maintainer
Maintainers of the chainlet (you can repeat this flag multiple times). The launcher is a maintaner by default. This is an optional parameter.
network-version
The chainlet's network version (defaults to 1). This parameter is optional

Example: Launching a Chainlet using the fixed-base-fee flag

This is a new feature added to Saga Realms in the Pegasus Phase I release.
As described above, you can launch a new chainlet with a fixed base fee flag set.
Using this setting may open up your chainlet to spam attacks, especially if you set it to 0
Below is an example of launching a chainlet using the fixed-base-fee flag.
sagacli chainlet launch SagaOS 0.5.2 phewchain --denom phw --genesis-account 0x0AA1012D993e497682B7e451AAF781F2C86945f7:100000000000000000000 --gas=500000 --fees 5000upsaga --fixed-base-fee=0
Enter keyring passphrase (attempt 1/3):
You are about to sign and broadcast a transaction, with the following configurations:
* Keyname: key4
* Keyring: file
* Address: saga16p4cejpaqpuha65hqyj85k5lx4umw7qzku37eg
* Network RPC:
* Platform chain id: spc-testnet-1
* Ledger: false
* Gas limit: 500000
* Message Detail:
creator:"saga16p4cejpaqpuha65hqyj85k5lx4umw7qzku37eg"
maintainers:"saga16p4cejpaqpuha65hqyj85k5lx4umw7qzku37eg"
chainletStackName:"SagaOS"
chainletStackVersion:"0.5.2"
chainId:"phewchain_1698704788823213-1"
chainletName:"phewchain"
params:<denom:"phw"
gasLimit:10000000
genAcctBalances:<list:<address:"saga1p2ssztve8eyhdq4hu3g64aup7tyxj30hfk2lwj"
balance:"100000000000000000000"
>
>
fixedBaseFee:"0"
>
Do you want to proceed? (y/N):
y
2023-10-30T23:26:32+01:00 INF tx broadcasted to the remote node code=0 gas_used=0 gas_wanted=0 hash=9D092179CBFE3792AF69CCBEF9AEDE51F6614B07A18C52FEEF290DA33B00D7D9
As can be seen, we are launching a chainlet with 0 fixed base fee (which comes with a warning that your chainlet will invite spam attacks). We can see from the image below that this transaction was a 0 fee transaction.

Example: Launching a Chainlet using the fee-account flag

This is a new feature added to Saga Realms in the Pegasus Phase I release.
Using the fee account flag allows you to specify an account to be used to collect all fees associated with the chainlet.
Below is an example of launching a chainlet using this flag.
$ sagacli chainlet launch SagaOS 0.5.2 duckchain --denom dck --genesis-account 0x0AA1012D993e497682B7e451AAF781F2C86945f7:100000000000000000000 --gas=500000 --fee-account 0x64f11D00a71285231934246908406d7B75fa976f
Enter keyring passphrase (attempt 1/3):
password must be at least 8 characters
Enter keyring passphrase (attempt 2/3):
You are about to sign and broadcast a transaction, with the following configurations:
* Keyname: key4
* Keyring: file
* Address: saga16p4cejpaqpuha65hqyj85k5lx4umw7qzku37eg
* Network RPC:
* Platform chain id: spc-testnet-1
* Ledger: false
* Gas limit: 500000
* Message Detail:
creator:"saga16p4cejpaqpuha65hqyj85k5lx4umw7qzku37eg"
maintainers:"saga16p4cejpaqpuha65hqyj85k5lx4umw7qzku37eg"
chainletStackName:"SagaOS"
chainletStackVersion:"0.5.2"
chainId:"duckchain_1698692919233251-1"
chainletName:"duckchain"
params:<denom:"dck"
gasLimit:10000000
genAcctBalances:<list:<address:"saga1p2ssztve8eyhdq4hu3g64aup7tyxj30hfk2lwj"
balance:"100000000000000000000"
>
>
feeAccount:"saga1vnc36q98z2zjxxf5y35sssrd0d6l49m0wq6upp"
>
Do you want to proceed? (y/N):
y
2023-10-30T20:08:47+01:00 INF tx broadcasted to the remote node code=0 gas_used=0 gas_wanted=0 hash=CE428932D994ABCEA4F4F388CAD4FB5715B32BB65A5D84B3BD1ED4C87191C55A
This chainlet was launched with the flag --fee-account 0x64f11D00a71285231934246908406d7B75fa976f so all transaction fees associated with this chainlet will end up in this account.
As an example, the following transaction caused fees associated with the transaction to be deposited into this fee account.
The red border in the image above shows the transaction fees associated with the above transaction.
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x64f11D00a71285231934246908406d7B75fa976f", "latest"],"id":1}' -H "Content-Type: application/json" http://duckchain-1698692919233251-1.jsonrpc.chainlet.eks-cluster-lt-1.sagarpc.xyz
{"jsonrpc":"2.0","id":1,"result":"0xde0f0056410e670"}
The command above queries the balance of the account 0x64f11D00a71285231934246908406d7B75fa976f and displays it in hex format. Comparing this new balance with the balance of this account prior to the above transaction, we come up with same amount displayed with a red border in the image above i.e. 0.000031500000147 dck.

Funding the Chainlet

Launching the chainlet will automatically fund the escrow account from the launcher's account. Prior to launching, you need to ensure there are enough tokens in your account. If you do not have enough tokens, you may see some error messages when launching your chainlet.
To get more tokens, follow the instructions on Getting Access.

Launching Chainlets with a Different Currency Symbol

IMPORTANT: If you need to launch a chainlet with a different currency aka token denomination, other than the default (upsaga), simply pass the --denom flag to set the token denomination for the chainlet.
Example:
sagacli chainlet launch SagaOS 0.5.2 mychain --dac-enable \
--genesis-account <your hex wallet address>:1000000 --gas-limit 100000000 --denom <your token name>
For a comprehensive list of options, including how to control naming of the chainlet, control the gas limit on each transaction, set up accounts on the chainlet genesis, please refer to
sagacli chainlet launch --help