Launch your Chainlet on Testnet

Prerequisites: Download and install SagaCLI and request tokens.

To launch a chainlet, you will need the following:

To launch a chainlet, you will need the following:

1. Chainlet type you wish to launch

2. Chainlet type version you wish to launch

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.17       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

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.17 magicwarriors --dac-enable --genesis-account 1B610FA944818999B476BAB267145BF5D923B552:10000000000 --denom mpt --fees 2500upsaga --gas-limit=25000000 

Which follow:

You are about to sign and broadcast a transaction, with the following configurations:
* Keyname:                shan
* Keyring:                os
* Address:                saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju
* Network RPC:            https://spc.testnet.sagarpc.io
* Platform chain id:      spc-testnet-2
* Ledger:                 false
* Message Detail:
        creator:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju"
        maintainers:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju"
        chainletStackName:"SagaOS"
        chainletStackVersion:"0.5.17"
        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.17 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.17	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 accumulate all of the returned transaction fees on the chainlet. This parameter is optional.
fees	Fees to pay along with the transaction
fixed-base-fee	A configurable base gas 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 base-gas-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 base gas 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 base-gas-fee flag.

sagacli chainlet launch SagaOS 0.5.17 freedomchain --denom fdc --genesis-account 0x8D37cb3624e1CB8480DceCC7884330a0449Dd9f0:100000000000000000000 --gas=500000 --fees 5000upsaga --gas-limit=25000000 --fixed-base-fee=0

Which follow:

You are about to sign and broadcast a transaction, with the following configurations:
* Keyname:                testWallet
* Keyring:                os
* Address:                saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3
* Network RPC:            https://spc.testnet.sagarpc.io
* Platform chain id:      spc-testnet-2
* Ledger:                 false
* Gas limit:              500000
* Message Detail:
	creator:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3"
	maintainers:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3"
	chainletStackName:"SagaOS"
	chainletStackVersion:"0.5.17"
	chainId:"freedomchain_1712762003250914-1"
	chainletName:"freedomchain"
	params:<denom:"fdc"
	gasLimit:25000000
	genAcctBalances:<list:<address:"saga135mukd3yu89cfqxuanrcsses5pzfmk0snevgmy"
	balance:"100000000000000000000"
	>
	>
	fixedBaseFee:"0"
	>
	
Do you want to proceed? (y/N):
y
2024-04-10T17:13:25+02:00 INF tx broadcasted to the remote node code=0 gas_used=0 gas_wanted=0 hash=58EB79A250AA45D87CB40A3A4237E1DC301E66CEB30A347921D5FB1923161F52

As can be seen, we are launching a chainlet with 0 base gas 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.

You may also set the Metamask advanced option to set gas to 0.

Otherwise, you will still be paying a small amount of gas fee and not zero.

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 accumulate all of the returned transaction fees associated with the chainlet.

Below is an example of launching a chainlet using this flag.

sagacli chainlet launch SagaOS 0.5.17 omegachain --denom ome --genesis-account 0x8D37cb3624e1CB8480DceCC7884330a0449Dd9f0:10000000000000000 --gas=500000 --fees 5000upsaga --gas-limit=25000000 --fee-account 0x8D37cb3624e1CB8480DceCC7884330a0449Dd9f0

Which follow:

You are about to sign and broadcast a transaction, with the following configurations:
* Keyname:                testWallet
* Keyring:                os
* Address:                saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3
* Network RPC:            https://spc.testnet.sagarpc.io
* Platform chain id:      spc-testnet-2
* Ledger:                 false
* Gas limit:              500000
* Message Detail:
	creator:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3"
	maintainers:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3"
	chainletStackName:"SagaOS"
	chainletStackVersion:"0.5.17"
	chainId:"omegachain_1712771388991266-1"
	chainletName:"omegachain"
	params:<denom:"ome"
	gasLimit:25000000
	genAcctBalances:<list:<address:"saga135mukd3yu89cfqxuanrcsses5pzfmk0snevgmy"
	balance:"10000000000000000"
	>
	>
	feeAccount:"saga135mukd3yu89cfqxuanrcsses5pzfmk0snevgmy"
	>
	
Do you want to proceed? (y/N):
y
2024-04-10T19:49:52+02:00 INF tx broadcasted to the remote node code=0 gas_used=0 gas_wanted=0 hash=A5B623D2FFB11CB9B71AD0E78CFD0C1F2C268A256EE2FF145BE751E3725A73C1

This chainlet was launched with the flag --fee-account 0x8D37cb3624e1CB8480DceCC7884330a0449Dd9f0 so all the returned transaction fees associated with this chainlet will accumulate 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":["0x8D37cb3624e1CB8480DceCC7884330a0449Dd9f0", "latest"],"id":1}' -H "Content-Type: application/json" https://omegachain-1712771388991266-1.jsonrpc.testnet.sagarpc.io

{"jsonrpc":"2.0","id":1,"result":"0x1ed09bead87c029acd7b0589c0000"}

The command above queries the balance of the account 0x8D37cb3624e1CB8480DceCC7884330a0449Dd9f0 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.000035749098105 ome

For more details about this feature, you can check also:

• Stack Exploder: Unblocking Web3 Products With Costless Transactions

• Stack Exploder: Implementing Costless Transactions Using Recycled Gas Tokens

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 Started.

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.17 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