# Pegasus Overview Standing up your own blockchain is hard. Developers need to become experts at blockchain infrastructure and balance security, decentralization and scalability of their infrastructure themselves. In modular systems, it becomes even more complicated. The developer needs to manually piece together data availability, consensus, execution and settlement and manage the blockchain trilemma (security, decentralization and scalability) for each component separately. We need to unblock developers with an entirely different approach. Saga makes launching a dedicated blockchain, or Chainlets, as easy as deploying a smart contract. We accomplish this by offering an integrated stack of all the necessary components needed to launch a chain into a single product experience for Chainlets. We are now in the first phase of launching Pegasus, our next release. Pegasus builds on top of the work already put into our first release, maintaining a focus on security. Pegasus introduces security into the Saga system in multiple ways. {% hint style="success" %} Security is at the heart of the Pegasus Release {% endhint %} First, Pegasus introduces staking to Saga. With the release of Pegasus, assets with value can be staked to secure the Saga Mainnet. Second, Pegasus introduces shared security with Chainlets using Cross Chain Validation (CCV). Security from the Saga security chain will be shared with all of our Chainlets, allowing our developers to never worry about securing their infrastructure. Third, Pegasus decentralizes the validator set running Chainlets. With Pegasus, all infrastructure in Saga was run by a set of four validators run by the foundation. With Pegasus, we introduce key innovations in our stack to enable external validators with different infrastructure to support running Chainlets. ## Pegasus Components First revealed at the Saga Multiverse Summit in August, Pegasus has undergone accelerated development from its original roadmap to support both Saga’s Innovators and partners. The Saga Protocol offers an integrated stack of automated, high performance, gasless, interoperable and customizable chains, called Chainlets. The Saga Chainlet Realm will be the main Realm on the protocol. Earlier this year, Saga unveiled [Realms, the technical manifestation of the Saga Multiverse](https://sagaxyz.cdn.prismic.io/sagaxyz/b31ad0c2-c85c-46bc-904a-040f5105e6b8_Saga+Realm+Into+the+Multiverse+-+Dark.pdf) - Saga’s platform that allows disparate tech stacks and IPs to deploy on the protocol and interact with each other through parallelized and interoperable dedicated chains. Saga Realms enables developers to launch customizable chains on Saga with different features and services such as technology stack, security source and various obligations for those sources. Under the framework of Realms, the standard Saga Chainlet became one Realm of many that will be supported in the near future, including those for our partners at Ethereum ([Ethlets](https://medium.com/sagaxyz/improving-ethereum-scalability-with-saga-ethlets-236685a51e8c)), [Polygon](https://medium.com/sagaxyz/saga-and-polygon-announce-partnership-to-automate-supernets-polygons-appchain-solution-db82d654c43f), [Avalanche](https://medium.com/sagaxyz/saga-and-ava-labs-announce-partnership-to-further-automate-subnets-avalanches-customizable-4986b75af451), [Celestia](https://medium.com/sagaxyz/saga-announces-collaboration-with-celestia-to-implement-sequencers-as-a-service-to-scale-rollups-fda01311919f), [XPLA](https://www.prnewswire.com/in/news-releases/saga-and-com2us-announce-partnership-to-power-infrastructure-for-gaming-301677678.html) and many others. {% hint style="info" %} To support configurable Realms out of the gate, Pegasus will be divided into three components: security chain, platform chain and Chainlet. {% endhint %}
### Security Chain The security chain is the first security source for the Saga protocol. This is where the $SAGA token is minted, staked and ultimately slashed if there is validator misbehavior. Saga’s security chain is built using the Cosmos-SDK. ### Platform chain The platform chain is where the developer launches and maintains their Chainlets. The platform chain aggregates security from multiple security chains and forwards that security to the launched Chainlets. Aggregation and forwarding of security is done through[ Cross-chain Validation](https://tutorials.cosmos.network/academy/2-cosmos-concepts/14-interchain-security.html) (CCV). CCV is an innovation pioneered by Cosmos, and Saga uses a modified version of Cosmos CCV. Any misbehaviors relayed by Chainlets are ultimately forwarded back to the security chain, where slashing will ultimately occur. The first security chain that the platform chain will aggregate security from will be the Saga security chain. However, in the future, the Saga platform chain will derive security from other sources such as our partners at Ethereum, Polygon, Avalanche and other stakers and validators. The platform chain is built using the Cosmos-SDK. ### Chainlet The Chainlet is where all computation actually happens. The end user interacts with one or more Chainlets. The platform chain forwards security from the security chain to the Chainlets. Any misbehavior in Chainlets are first relayed back to the platform chain. The first supported chainlets are built using the Cosmos-SDK but there will be other types including Avalanche Subnets and Polygon Supernets. {% hint style="info" %} Pegasus is the release that will be used for Saga protocol V1 launch. For further details check out [here](https://medium.com/sagaxyz/saga-mainnet-technical-launch-plan-c084b1426acc). {% endhint %} ## Progressive Launch Roadmap To ensure a successful launch of the full Saga protocol V1, the launch will be divided into six progressive phases. Each phase builds on top of the previous, and the full-featured Saga protocol V1 will have completed launch at the end of phase six. The full progressive launch schedule is shown below.
### Phase 1 The most significant effort in Phase 1 is the launch of the security chain. During this phase, the platform chain and Chainlets launched from the platform chain will be operated by foundation validators (not the security chain validators). The security chain validators will be external and decentralized, and will almost inevitably have participated in our Incentivized Testnet. Cross-chain validation (CCV) will not be supported from the security chain to the platform chain and to the Chainlets. * **Developers** can begin launching Chainlets that will persist through all the phases. In other words, their applications and smart contracts will be live in a production environment that users can interact with. Upgrading to successive Mainnet phases will be done automatically on the backend, so developers will not need to worry about manually upgrading. {% hint style="info" %} Developers will still need to request test tokens from the foundation to launch Chainlets (Controlled Permissioned Access). Our Innovators will be provisioned with keys to have test tokens automatically fauceted to their wallets for funding their Chainlets. {% endhint %} * **Stakers** can start staking assets to secure the network and earn inflation rewards. * **Validators** need to launch and maintain the security chain only. External validators will not be running the platform chain and Chainlets. * **End Users** can begin using launched Chainlets. ### Phase 2 Phase 2 introduces basic CCV from the security chain to the platform chain. The platform chain will be secured using CCV with a hardcoded foundation key. This is the first step in converting the platform chain into a security aggregator. This phase will also test drive whether validators are able to successfully upgrade the security chain. * **Developers** (No Changes) * **Stakers** (No Changes) * **Validators** need to upgrade the security chain. * **End Users** (No Changes) ### Phase 3 Phase 3 then shares the aggregated platform chain security to the individual Chainlets. In other words, each Chainlet will now inherit the security of the platform chain. In this instance, the relayed security is still only a hardcorded foundation key. However, the subsequent phases will introduce more and more security into the platform chain. This phase will also test drive upgrading a production Chainlet and platform chain. * **Developers** (No Changes) * **Stakers** (No Changes) * **Validators** need to upgrade the security chain. * **End Users** (No Changes) ### Phase 4 Up until now, the platform chain and Chainlets were not operated by external validators. Phase 4 is where we begin onboarding validators in the security chain to start operating the platform chain. Running the platform chain means these validators will also need to run every chainlet launched by the platform chain. A proof of authority set of validators from our security chain will start operating the additional infrastructure. The platform chain will now be secured using CCV with the PoA validator keys. * **Developers** (No Changes) * **Stakers** (No Changes) * **Validators**: External validators will need to start running the platform chain and all Chainlets. * **End Users** (No Changes) ### Phase 5 Once the PoA platform chains and Chainlets are stable, we can onboard the entire set of security chain validators to run the platform chain and Chainlet infrastructure. At this point, the full security chain security is aggregated on the platform chain, which gets forwarded automatically to all Chainlets. * **Developers** (No Changes) * **Stakers** (No Changes) * **Validators** (all) will need to start running the platform chain and all Chainlets * **End Users** (No Changes) ### Phase 6 Finally, we can enable slashing on the security chain. Any misbehavior on any Chainlet is forwarded back to the platform chain, which relays it to the security chain. This is the point where audits will be finalized, and the $SAGA token will begin to be used for provisioning Chainlets. The developer portal will now be permissionless and no longer be controlled access. This will complete the progressive launch of the Saga protocol V1. * **Developers** will need to begin paying for Chainlets using $SAGA tokens instead of Testnet tokens. The developer UX will now be permissionless and no longer be controlled access. Up to this point, the incremental changes between the phases have been largely on the backend, and there would have been little to no noticeable change for the developers or their end users. {% hint style="info" %} **Now, however, there will be fast interoperability between the Chainlets and bridging out to other ecosystems, which will enable any assets to be transferred in and out of Chainlets at the speed of settlement allowed on the chain receiving the assets.** **This also means Chainlets are now fully elastically scalable and can have the same level of flexibility as typical cloud instances.** {% endhint %} * **Stakers** (No Changes) * **Validators** (No changes) * **End Users** (No Changes) ### Why is the launch structured this way? The progressive nature of this launch means that we can incrementally test out each major component to isolate issues along the way. This kind of agile launch ultimately means a faster and more secure path to achieving the full launch status. Carefully planning each step means that every stakeholder can experience a much smoother ramp up to the complete Saga protocol launch. ### Benefits for validators The onboarding experience for validators is progressive. Phase 1 requires the validators to test out the launch of a singular chain. Then, a few upgrade cycles later, certain validators will need to launch a second chain (platform chain) and make sure their infrastructure is ready to spin multiple Chainlets on demand. Finally, the whole validator set will be running the platform chain. Keep in mind that the launch process for a decentralized proof-of-stake chain on Saga is entirely permissionless and automated. We are taking a process that was previously painful and cumbersome for even one chain and allowing developers to access a completely streamlined version as many times as they want. Our engineering team has spent most of their time making sure we have the validator tooling to make this a manageable burden on our validator sets, but we are doing something entirely new. The best way to guide the validators through launch is through a phased approach. ### Benefits for developers The Saga progressive launch is designed such that Chainlets are fully production ready at Phase 1. This is the earliest possible point at which we can deliver a secure chain-to-launch-chains to developers so that their applications can go live and welcome user activity. Additional features will be added throughout the launch phases to enhance functionality, and these features will be clearly communicated to developers so they can in turn let their communities know. However, any Chainlet launched during the progressive launch process will have security automatically migrated between phases. The goal is to have minimal to no disruption to the developers’ Chainlets as the launch phases are completed. ### Benefits for stakers and hodlers The stakers and hodlers have access to the $SAGA tokens immediately at Phase 1. Saganauts can begin securing Saga before the platform chain is fully decentralized. The progressive launch significantly de-risks the stakers’ and hodlers’ assets. ### Benefits for end users of our dapps The end users of Saga can start using and interacting with their favorite Chainlet applications as soon as Phase 1 is complete. ## Features of Pegasus (Phase I) Mainnet Here are some of the main features of Pegasus (Phase I) Mainnet: * Saga Security Chain to mint the $SAGA token, allow staking and slashing, which is completely decentralized * Saga Platform Chain, used to launch chainlets, which comes with a geographically distributed set of Saga Foundation validators * A [**Saga Web App**](/saga-web-app/getting-access) for managing chainlets * A [**CLI**](/sagacli/getting-access) based wallet compatible with many types of key stores, including Ledger * Community managed escrow accounts for funding chainlet uptimes and operations * On-chain billing history for each chainlet * Ability to perform live chainlet updates for security updates or enhanced features * Dedicated RPC infrastructure for each chainlet, supporting both JsonRPC and Websockets * Dedicated Blockchain Explorers for full visibility into blocks, transactions and on-chain assets # Saga Overview ### Introduction Saga is a protocol for automatically provisioning application-specific blockchains. We are building this by rearchitecting developer and end user interactions with blockchains. Using shared security, innovations in validator orchestration, and an automated deployment pipeline, Saga makes launching a dedicated blockchain, or Chainlet, as easy as deploying a smart contract. Our network is best leveraged as a scalability layer for `web3` infrastructure. # Saga Topology The following sections will go through some of the key features of the Saga protocol. For a more extensive discussion, please see our [litepaper](https://sagaxyz.cdn.prismic.io/sagaxyz/08e727f2-88a2-4c95-ad17-b0b9579d2b69_saga-litepaper-march-2022.pdf). In Saga, smart contract developers interact with the Saga Mainnet to request a Saga Chainlet. A Saga Chainlet is an application-specific blockchain secured using [Cosmos Interchain Security](https://github.com/cosmos/interchain-security) (ICS), with the Saga Mainnet validators providing the security. The validators for the Chainlets are the same as those for Saga’s Mainnet, and they produce blocks while checking to make sure that the other validators are following a predetermined service-level agreement (SLA). The provisions of this SLA include uptime requirements, running relayers and services, and validating properly without double signing. When a validator violates the SLA for a Chainlet, the evidence is relayed by the other validators via [Inter Blockchain Communication](https://ibc.cosmos.network/) (IBC) back to the Saga Mainnet. The network then slashes the staked SAGA tokens of the validator who violated the SLA. Using ICS, every Chainlet automatically inherits the security of Saga’s Mainnet without the need for a native and individual staking token.\ \ In Saga, a Chainlet can be configured to use various [Cosmos SDK](https://v1.cosmos.network/sdk) modules, including virtual machines (i.e. EVM, Cosmwasm, SolanaVM, MoveVM) as well as different flavors of each (i.e. Juno’s version of Cosmwasm, Osmosis’s version of Cosmwasm, the Aptos MoveVM). Every Chainlet has a dedicated VM that has been deployed onto an individual chain. To deploy, a developer simply requests a Chainlet launch from Saga Mainnet. Once the request is received on the Saga Mainnet, the Saga validators provision the requested Chainlet. Once the provisioning is complete, the developer is free to deploy the smart contracts they have developed onto their Chainlet.
# Saga Chainlets In essence, a Saga Chainlet is a sovereign blockchain with a VM module running a single smart contract.
Because each Chainlet contains only the smart contracts a developer or team would like to deploy on a single chain, the developer has a flexible and usable development environment: * For the developer, the deployment of Chainlet is as easy as deploying a smart contract * Chainlet blockspace is not shared with any other application, leading to predictable fees * Saga is meant to be VM agnostic, which means developers can bring their own VM module to plug into their Chainlet. The first kind of VM Saga will support is the EVM * Chainlet components such as VM module, SDK and Tendermint Core can be upgraded independently from other applications and Saga Mainnet * Saga supports other technology stacks besides Cosmos SDK and Tendermint, including Polygon Edge Saga enables developers to manually “shard” various workflows into multiple Chainlets to leverage horizontal scaling. Deploying a Uniswap-like AMM smart contract into its own application specific Chainlet will already offer significant scalability improvements. However, once the demand for the smart contract starts exceeding the limitations of current blockchain technology, the developer could deploy multiple instances of the same smart contract focused on particular subsets of activity. In the AMM example, the developer could deploy a smart contract instance for each asset pair. The Chainlet architecture enables near limitless scalability, as long as these Chainlets can be secured properly. # Saga Shared Security One of the challenges of deploying a Cosmos-based application specific chain is the complexity around securing the chain. Each application chain requires gathering validators, distributing staking tokens and designing a token mechanism that helps secure the chain. Saga uses shared security to remove this barrier to entry. Every Saga Chainlet is secured by the Saga Mainnet validators using shared security.
There are many flavors of shared security. Saga uses a model similar to the Cosmos Hub’s version 1 interchain staking called Optimistic Coordination to ensure security of each of the Chainlets. * Every validator on the Saga Mainnet is required to validate every Chainlet provisioned * Validators agree on a set of SLA for Chainlet provisioning and maintenance such as timely deployments, guaranteed compute capacity, minimum uptime, honest consensus participation, and inter-blockchain communication relaying * An auditor monitors the Chainlet and creates a governance case in the event that a validator fails to meet service obligations * Saga Mainnet enforces any consequences needed for validators violating SLA With Optimistic Coordination, Chainlets automatically inherit the security of the Saga Mainnet. However, to make provisioning Chainlets as simple as possible, Saga requires a suite of tools to facilitate Chainlet orchestration for validators. # Validator Orchestration Tools Deploying a smart contract and provisioning a Chainlet on Saga is intended to be a fully automated process. We can expect thousands of independent Chainlets to be running at the same time. This means that Saga validators will need to be able to automatically manage thousands of independent processes on their servers and keep up with resources needed to maintain them. To facilitate this orchestration, Saga will develop validator orchestration tools that will simplify the process of placement, scheduling, releasing, installing and upgrading: * Automatically spin up new processes and server environments for each Chainlet * Automatically schedule binaries to be executed based on Chainlet subscription SLAs * Facilitate deployment of new Chainlets on multiple compute resources * Monitoring tools for validators to ensure sufficient resources are available for provisioning new Chainlets One of the more difficult tasks for validators will be predicting the required hardware necessary to service the utilization needs of all Chainlet applications. On the one hand, having too much excess compute resources is wasteful. However, not having enough resources may result in slashing due to computer SLA violations. Therefore, Saga’s validator orchestration tools will need to help validators predict when new hardware resources will be necessary. Splitting out applications into one or more Chainlets means that composability will be more difficult to achieve on Saga. Validators will be required to relay IBC messages between any two pairs of Chainlets, including the Saga Mainnet. Our IBC will additionally be more performant, by virtue of all our Chainlets being co-located in each validators' datacenter. However, more tools and development will be needed to make the IBC user experience as seamless as possible. Saga’s token mechanisms rely heavily on seamless cross-chain composability. Manually transferring assets between Chainlets and other Cosmos chains through IBC is a poor user experience for the end user. Ultimately, we want assets to seamlessly transfer between blockchains without the end user initiating IBC transactions. In addition to creating validator orchestration tools around IBC, Saga will work with the broader Cosmos ecosystem to augment features to automate and abstract the IBC experience away from end users. # Token Mechanism and Economics This section offers a brief overview of Saga's Token Mechanism and Incentives. For a more detailed description, please check out our [first token paper](https://sagaxyz.cdn.prismic.io/sagaxyz/d396b945-52ed-41d5-afef-ee27c6a8a233_Saga+-+Token+Mechanism+%26+Incentives+-+Dark+Version.pdf). We split the token economics into two conceptual components: the front end and back end. The front end is the portion of the token flow between the Chainlet end users and the Chainlet developers. The back end is the portion of the token flow between the Chainlet developers and the Saga chain. Splitting up the token mechanism into two independent parts allows for interesting usability benefits and value accrual for developers and our partner chains. ## **Front End: End User to Developer** Imagine a scenario where Uber hosts their mobile apps on Amazon’s servers. The expected user interaction flow is as follows: end users pay Uber then Uber pays Amazon for hosting their applications. It is unusual to expect end users to pay Amazon directly. However, this is the norm in most smart contract platforms today. The fees from the underlying network are paid by end users, not application developers. This results in end users needing to custody enough tokens to pay for the fees and prevents developers from exploring interesting business models such as ad-based or freemium models.
This front end model enables developers to explore interesting monetization models that were previously not possible. End users are abstracted away from network fees and the developers can implement more flexible monetization methods: * The developer can still implement fees per transaction. However, this model enables those fees to be paid in whatever tokens the developer wants. The fee tokens gathered by the developer can be any external tokens (like stablecoins), Saga tokens, or tokens created by the developer. This fee will accumulate in a wallet controlled by the developer * The developer may implement a subscription service where only whitelisted users may use the smart contracts * The developer can also choose to make their product free for end users with monetization coming from other sources like advertisements. In this scenario, the developer will need to set up some spam prevention mechanisms to prevent malicious users from utilizing the Chainlet capacity purchased by the developer. However, this can also be solved via whitelisted accounts On Saga, end users of each application interact only with the Chainlet, and all fees for provisioning Chainlets are paid by the app developers. We will discuss the token flows for how this Chainlet provisioning happens in the back-end section. ## Spam Prevention and Transaction Ordering If there are no end user fees, how does Saga deal with transaction spam and transaction ordering? Saga gives the flexibility to the developer to solve spam and transaction ordering in more creative ways. Some methods include: * Whitelisted accounts maintained by the developer * Stake-based or holdings-based transaction priority for any asset on any chain * Wallet and UI-based rate limiting * Other fees (such as swap fees or other interaction flows in the system) * NFTs that give access to a certain amount of transactions * Other developer-specified ordering using ABCI++ Of course the developer can also choose to implement traditional gas-based transaction fees in their Chainlets. However, since the network is not directly charging these fees, the developer can decide to denominate the fees in any token (i.e. USDC, ATOM, ETH, their native token or SAGA). Also, unlike other blockchains, if a developer opts to charge transaction fees, those fees will not go to Saga. The fees generated by Chainlets accumulate in a wallet controlled by the developer, allowing a developer to realize the full value of the applications they have deployed. ## **Back End: Developer to Saga Mainnet** In Saga, the developer pays for provisioning the Chainlet. The interaction flow is designed to be similar to how an Amazon EC2 instance is provisioned for web developers. In order for a developer to deploy a Chainlet, a developer must subscribe to a fee deposit, which guarantees a specified level of compute capacity for a specified amount of time for the provided Chainlet. The cost increases for higher capacity subscriptions, and there will be discounts offered based on the duration of commitment. Once the subscription is selected, the developer needs to post the necessary bond in Saga tokens to provision the Chainlet. In essence, the fee bond is a pre-pay account to provision Chainlets and will be drawn down over time. At the outset, the network will provision “free credits” akin to trial accounts offered by services like AWS and Google Cloud to allow developers to freely set up testnets or experimental chains, but these free credits will only allow for a limited amount of Chainlet capacity for a limited time.
Once the Chainlet is provisioned, the end user can directly interact with the Chainlet. The maximum utilization of the Chainlet will be restricted based on the subscription tier selected by the developer.
The subscription model prevents idle, unused Chainlets from existing forever. The only requirement for maintaining the Chainlet is the payment of the subscription fees. As the protocol depletes the fee bond balance, the developer must maintain a sufficient balance to pay for the subscription. We may also allow developers to stake the fee bond tokens. Provided the developer has enough Saga tokens staked in the fee bond, this could allow developers to automatically pay for Chainlet subscriptions from the staking rewards. Low deposit balances can be replenished by developers or broader community incentives, but once depleted, validators may halt the chain and after a predetermined grace period, remove the unused binary and underlying data. The fee generated from developers is intended to pay for the validators’ infrastructure cost of maintaining Chainlets. Saga incentivizes validators to offer the most competitive rates to developers through our validator selection mechanism. # Validator Selection ## **Saga Musical Chairs** In Saga, time is split into discrete epochs (i.e. 1 day). Developers pay for Chainlets on an epoch-by-epoch basis. Every validator in the Saga Mainnet publicly posts the price they would like to charge a developer to run a Chainlet for one epoch. Some time before the beginning of the next epoch, the validators’ bids are locked for the epoch, and a session of Musical Chairs begins to determine a universal price for running a Chainlet for the epoch. The validators’ bids are set for all future epochs until the validators indicate they would like to change their bids
Musical Chairs terms and definitions: * Total Set: The set of validators interested in being validators in the network. Anyone interested is able to join the total set. * Player Set: The set of validators who get to participate in the musical chair session. * Player Set Count (p): The number of validators in the Player Set. * Musical Chairs Price: The resulting price from the Musical Chairs auction. Used to set the Chainlet price of the next epoch. * Winning Set: The set of validators whose bid is less than or equal to the Musical Chairs Price. * Winning Set Count (w): The number of validators in the Winning Set. * Losing Set: The set of validators whose bid is greater than the Musical Chairs Price. * Losing Set Count (l) The number of validators in the Losing Set and l = p - w. * Active Set: The set of validators who get to validate Chainlets in the next epoch. Step 1: Player Selection The first step of Musical Chairs is to determine which validators participate in the game from the Total Set. The number of validators who are included in the Player Set is determined by the network as a parameter p. The validators in the Player Set are the top p validators by delegator stake weight. Our assumption in the Musical Chairs auction is that Saga may support a very large number of validators in the Player Set. Step 2: Musical Chairs The validators in the Player Set play a round of musical chairs to determine the Winning Set and the Losing Set. The parameter of the Chainlet price that the validator has configured for their validator will be pulled in for the current Musical Chairs session. The number of validators in the Winning Set is set as a parameter w. Saga sorts the validators in the Player Set by their auction bid. The cheapest w validators get included in the Winning Set. The remaining validators with the highest prices get included in the Losing Set. Step 3: Price Setting The price for the epoch is set by the most expensive validator in the Winning Set. This guarantees that every validator in the Winning Set receives Chainlets fees that are greater than or equal to the amount they bid. Let’s go through an example system where p=10 and w=8. In the following example, there are 12 validators in the total set. Each validator’s price bid is denoted as dollar figures in the box. First, the Player Set is determined by rank ordering by stake weight: Validators 11 and 12 (the two validators with the least amount of stake) are excluded because p=10. Then, the Winning Set is determined by choosing the cheapest w validators in the Player Set. In the example, validators 2 and 7 are included in the Losing Set because their prices are the highest two bids from the player set. The Winning Set for the next epoch will be validators 1, 3, 4, 5, 6, 8, 9 and 10. Finally, the Chainlet price for the next epoch will be max(Winning Set), which is $5 in this example.
Step 4: Rewards and Punishment The final step of Musical Chairs is to reward the Winning Set and punish the Losing Set. The Saga team is evaluating a number of methods to reward and punish these validators to incentivize the validators and delegators while keeping the security assumptions of the network intact. Here is one way: * The Active Set of the network in the next epoch is the Player Set. (Validators in both the Winning and Losing Set are included.) * Everyone in the Active Set receives Chainlet fees for the Chainlets they are validating. * However, the price is set by only the winning validators. Therefore, validators in the Losing Set are receiving less than their requested price. * Delegators to the validators in the Losing Set receive zero inflation from the network for the epoch. This directly incentivizes the validator to bid lower in the next epoch or risk their delegators re-delegating to other validators. Another way the network could configure the rewards and punishment is: * The Active Set of the network in the next epoch is the Winning Set. * Validators in the Losing Set get kicked out of validating the next epoch. * Delegators to the validators in the Losing Set receive zero inflation from the network for the epoch. This directly incentivizes the validator to bid lower in the next epoch or risk their delegators re-delegating to other validators. In the first scenario, the validators in the Losing Set still validate Chainlets, but receive less reward than they would have wanted. A validator who is in the Losing Set consistently will lose delegation because the delegators are not receiving any inflation rewards, which will eventually push the validator out of the Player Set. In the second scenario, the punishment is more strict. Validators in the Losing Set are immediately kicked out of the Active Set and receive zero rewards and inflation. They also are no longer required to validate Chainlets. However, there are some security implications of removing large validators from the Active Set, and the Saga team is researching the best way to design the reward and punishment mechanism to minimize Chainlet costs (Tenet 3) while maintaining the security guarantees of a Proof of Stake network. ## Properly Setting the Parameters The parameters, w and p, and the punishment mechanisms are very important for the incentives of the network. If w is too small, too many validators will be punished. If w is set too high, the economics of commoditizing blockspace won’t function properly. There are also security implications that we need to consider. A malicious actor can Sybil attack the Saga validator set to attempt to control the network or the outcome of the Musical Chairs process. It is notable that validators can attempt to collude/Sybil attack the Winning Set (bid prices low) or the Losing Set (bid prices high). The parameters need to consider both dynamics. The Saga team’s current thought is that w needs to be approximately 75-85% of p. This makes w sufficiently large enough to ensure it is difficult to control the Winning Set. At the same time, a Losing Set size of 15-25% ensures that filling the Losing Set with Sybil validators is difficult. Another lever Saga has to prevent Sybil attacks and collusion is to make the social cost of such attacks very high. Saga can, for example, include in its upcoming Constitution that a Sybil validator will be slashed fully to disincentivize such behavior. ## Saga Chainlet Scheduler How can the network further lower prices of Chainlets for developers (Tenet 3)? The Musical Chairs process determines the amount each validator will receive for each Chainlet, but the actual price that the developer pays will be (Musical Chairs Price x number of active validators for their Chainlet). The Musical Chairs Price variable is automatically reduced as validators compete to join the Winning Set, but we can also reduce the active validators per Chainlet to decrease the price that developers pay. One way to reduce the number of active validators is to reduce the total number of validators participating in the network. However, this has decentralization and security implications that may not be ideal. There may be a way to increase the total number of validators but still reduce the number of active validators per Chainlet. Instead of requiring every validator on the Saga Mainnet to validate every Chainlet, we can relax the SLA requirement for certain validators and have a partial set validate each Chainlet. This can be accomplished using the Chainlet Scheduler. Imagine the network sets a certain threshold of quorum for each Chainlet. Let’s arbitrarily pick 70% of total staked assets. For each Chainlet prior to the beginning of each epoch, the scheduler randomly selects a set of validators whose stake weight adds up to greater than or equal to the 70% threshold. There are many different ways to randomly select this set, but an easy way to do this is to keep picking individual validators randomly based on their stake weight until the set has greater than or equal to 70% stake weight. Let’s define the validators selected as s and those not selected as n. There will be a different set of {s,n} for each Chainlet per epoch. Only those in s are required to validate the Chainlet. Conversely, the SLA for the n validators are loosened to allow those validators to not validate the Chainlet. The chart below shows the potential reduction in the number of validators per Chainlet when we apply this kind of scheduler on existing token distributions in the Cosmos ecosystem. A small reduction in quorum threshold and SLA can have a very significant impact on the number of validators.
There are some nice behaviors that result from utilizing this kind of scheduler. First, we can guarantee that every Chainlet will have the full security of the Saga Mainnet. Second, because the number of validators per Chainlet is significantly reduced, the total price for developers will also go down (Tenet 3). By setting a quorum threshold, below 100%, we are able to cut down on the steepest part of the cost curve. Third, the number of Chainlets each validator validates will be proportional to their stake weight. This means the top validators will validate all Chainlets, while validators with little stake weight will be required to validate a very small number of Chainlets. This makes validator requirements for smaller validators significantly less than those for larger validators. We can vary the total threshold level and see how many Chainlets each validator ends up validating. We can see that regardless of the threshold level, there is a much smaller number of Chainlets in the tail end validators.
There are some complications that may arise with a scheduler. First, with a lower quorum threshold, the risk of stalling due to a downed validator increases. With a threshold rate of 70%, a validator with 4% of stake may halt Chainlets if they accidentally go down since a quorum of 66% won’t be possible. In reality, this threshold will likely be set by governance targeting a minimum failure tolerance for validators going down. Second, a random sampling scheduler may vary the number of validators per Chainlet from one epoch to another. The Saga team has simulated a simple random sampling scheduler and found that the number of validators per Chainlet follows a normal distribution and is kept fairly consistent across epochs. Saga can employ a more sophisticated scheduler to make the distribution tighter, making the cost for developers less lumpy from one epoch to another. Also, in all scenarios, the scheduler reduces the number of validators vs. the whole validator set. Even if there are small variations for developers, the cost will always be less than the price without the scheduler.
Finally, every validator will be validating a different set of Chainlets every epoch. This means that we will need to implement fast-syncing of blockchain data (state and mempool) across validators to make sure there is an automatic transition of validator sets between epochs. One way to solve this problem is to require the top validators to always validate every Chainlet. The number of validators in this set can be parameterized using governance. This way, there is always a consistent set of validators to state sync as the other validators swap between Chainlets to validate. ### # Partnership Models Saga’s unique and flexible product design enables partnership models with other ecosystems that allow for accrual of value to these ecosystems’ tokens and communities even when Saga serves as the base chain. First, Saga could partner with various other layer one blockchain ecosystems to offer horizontal scalability solutions while keeping the economics of the respective tokens intact.
Imagine a scenario where a partner network is expecting a smart contract that will generate too much traffic in the partner network’s mainnet. To prevent their blockspace from being too congested, the partner network could deploy the smart contract on Saga instead. The partner network can post the Chainlet provisioning fee in Saga tokens to get the smart contract provisioned. The Chainlet can be configured to demand end users to pay fees in the partner network tokens. This way, the end user’s interaction flow is identical to the case in which the smart contract is deployed on the partner mainnet. The fees paid by the end users follow our front-end token model and get distributed to an account owned by the partner network. A portion of these fees can be converted to Saga tokens to pay for the Chainlet subscription. The remaining balance can be configured to be distributed back to the partner’s validators and stakers in the same method as smart contracts deployed on the partner’s mainnet.
Saga’s token mechanism allows for accumulated transaction fees (net of Saga Chainlet fees) to accrue value to partner stakeholders. The partner also keeps their developer and end user pipeline, maintaining brand loyalty while scaling through Saga. A second method of partnership is a revenue share between the Saga Mainnet and technology teams across the ecosystem. This structure covers cases in which developers are coming directly to Saga to build their applications. Saga is meant to be a VM agnostic chain, and numerous VM options will be available to developers who come to Saga looking for an environment to build their application in. Therefore, Saga will want strong technology partners to support and develop VM technologies on Saga. Saga can always use its Protocol Controlled Reserve to pay and incentivize these developers to continue to maintain and support their respective VM options for Saga. More specifically, the developer chooses a VM environment and deploys a smart contract on Saga. They then post the fee deposit that is needed to provision and maintain the Chainlet. Saga will provision a Chainlet for the developer that uses the native token of the VM for transaction fees.
When an end user uses the application, they call the smart contract directly on the Chainlet and pay transaction fees in the native token of the VM. These fees accumulate in a wallet controlled by the developer. The developer can convert part of the fees to pay for the required bond needed to provision the Chainlet or however they see fit. Saga can also take a portion of the fees and send them to the network affiliated with the VM technology partner as a revenue share, incentivizing value accrual for the partners’ tokens.
# Paying for Chainlets ## Chainlet Deposit Fee Collection Once the price is set by Musical Chairs, how does a developer actually pay for a Chainlet? To reiterate, the Musical Chairs process determines the amount each validator will receive for each Chainlet, but the actual price that the developer pays will be (Musical Chairs Price x number of active validators for their Chainlet). When the next epoch begins, each developer’s Chainlet fee deposit is reduced by (Musical Chairs Price x number of active validators for their Chainlet) and distributed to the addresses of the validators in the Active Set. This means each validator receives the Musical Chairs Price amount of SAGA tokens per Chainlet they validate. Once the fee deposit is collected by the validator, they are on the hook for validating and meeting the SLA requirement for that Chainlet. In the middle of this epoch, another Musical Chairs auction process begins for the subsequent epoch. Unless the validator changes their bid, their current price automatically rolls over to the next epoch. There is significant value for validators (and their delegators) to be included in the Winning Set. Therefore, those validators in the Losing Set will want to lower their bids to get back in the Winning Set for the following epoch, ultimately lowering the price of Chainlets. ## Further Improving the Developer Pricing Experience There are some further optimizations we can implement to make the developer experience better. We will go into more details with the following ideas in the future, but we wanted to leave a small glimpse into the future design of the Saga pricing mechanism. First, the Musical Chair auction mechanism ensures that the price will constantly change from epoch to epoch. One way to reduce volatility is to charge developers a moving average of the price from the last X epochs. This way, epoch by epoch, the price variation only contributes a small movement to the actual price and the developer is able to better predict the price of Chainlets ahead of time. Secondly, we can denominate Chainlet prices in USD instead of SAGA tokens. By having dollar-denominated Chainlet prices, there will be a much more predictable market for developers. Because the payments will still be made in SAGA tokens, this mechanism will require some form of price oracle system or bonding curve. # Staking on Saga Saga depends on stakers for the economic security of the Mainnet and, by extension, the security of each Chainlet. To ensure sufficient economic security for the system, Saga employs a staking inflation schedule very similar to that of the Cosmos Hub. The network targets a specific stake rate by varying the inflation rate. The annual inflation is capped between minimum and maximum rates. If more than ⅔ of SAGA is staked, the block rewards decrease gradually down to a floor of a minimum rate of annualized inflation. If less than ⅔ of SAGA is staked, the block rewards increase gradually up to a ceiling of a maximum annualized inflation. With the Cosmos Hub, each validator posts a commission that they take from each delegator. With Saga, the network determines a universal commission rate that every validator takes from their delegators. This design is due to the fact that in our system, each validator is already posting their Musical Chair auction price. We do not think asking delegators to choose between a high-cost validator with low commissions and a low-cost validator with high commissions is a productive tradeoff. Saga simplifies the validator selection process by keeping the commission rate consistent across all the validators. Selecting the right validator will be key to maximizing delegator rewards. As mentioned in the Musical Chairs section, delegators delegated to validators in the Losing Set of Musical Chairs may not earn any inflation rewards. It is important for delegators to redelegate to validators who post the cheapest prices. A commission still exists to ensure that the Saga validators have ways of economically sustaining themselves without any Chainlet activities. Over time, we expect validators to price Chainlets at-cost or below-cost, and having an inflation commission buffer helps the Chainlet price decrease to such levels. # Staking your Saga on Keplr First of all you need a [Keplr](https://www.keplr.app/) wallet which supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. To stake your SAGA, first go to your Keplr extension and click on "Manage Portfolio in Keplr Dashboard", it should bring you to
In the Keplr dashboard you should see all the information about: **Total SAGA Amount, Staking Amount, Available Balance and Claimable Rewards.** Click the **Stake** button as shown in the picture.
You should see a list of validators. Choose a validator by either typing the name of your desired validator into the search bar or by scrolling down the list.
If you select one of the **top 10 validators**, you may encounter a notice like this, don't worry, you can always choose this validator for staking. However, this notice serves as an encouragement to consider other validators for a more decentralized network.
Once you’ve selected your validator, fill out the number of $SAGA that you’d like to stake, select “Stake” once again and then approve the transaction.
If everything goes correctly, you should see your staking amount in the **Staking Amount** section.
{% hint style="info" %} Please note that staking will lock up your assets for **21 days**. You will need to undelegate to make your staked assets liquid again, which also takes **21 days** to complete. {% endhint %} ## Claiming Staking Rewards To claim the reward from your staking (after it matures a little bit), click the claim button in the Claimable Rewards section (you should have some SAGA before claim for the Tx fee).
In the end, you should have your **Available Balance** increased by the value of your claim (and ready for a another round of stake 😉).
# Auto-compound your staking rewards with Restake.app **Restake.app** provides a convenient way to automating the restaking of your staking rewards on Saga, allowing you to generate compounding interest on your investments. First of all go to
Connect your wallet (with Keplr or Leap) After you connect your wallet, you'll notice all validators that you chose for staking (in my case the same of the [Staking your Saga on Keplr](/introduction/saga-overview/staking-on-saga/staking-your-saga-on-keplr) section)
Choose one of validator and the click on **Enable REStake** to activate **auto-restake** for your wallet address.
Choose the **maximum amount** you want Auto-Restake to restake for you over time (in my example i choose unlimited) and set an expiry date for when this auto-restaking activation will automatically deactivate.
Confirm the wallet transaction to enable REStake and begin enjoying the benefits of restaking.
If everything goes correctly, you should see on the dashboard that your validator has the "green check" like this:
**Note**: You can return to Restake.app at **any time** and deactivate this auto-staking function using the same wallet you used to activate it. # Getting Access Pegasus is a multi-phase release of SAGA ## Getting Access Pegasus is a multi-stage release. In this (Phase I) phase, we will focus on documentation relevant to the Pegasus. To gain access to the Pegasus, projects need to be onboarded as Saga Innovators. {% hint style="danger" %} **Important:** If you are not a Saga Innovator, please [fill out the access form](https://saga.xyz/join). {% endhint %} After you complete the on-boarding form, our team will reach out to you to guide you through the process and give you access to our token faucet. If you are already a Saga Innovator, you can continue with the instructions, Funding Wallet w/ Tokens. # Quickstart Guide This quickstart guide will walk you through the necessary steps to request your tokens and launch your chainlet. # Testnet Quickstart Guide This quickstart guide will walk you through the necessary steps to download, install & configure the SagaCLI, request your tokens and launch your chainlet. {% hint style="warning" %} **IMPORTANT**: Pegasus Incentivized Testnet is for testing purposes only. As such, this should be used for testing ONLY, not production deployments. {% endhint %} ## **1. Faucet Airdrop Key** Your contact at Saga will send you a Faucet Airdrop Key which will auto-fund your wallet address. If you don't have your Faucet Airdrop Key, reach out to your contact at Saga. After you have the passphrase from your Saga contact, tokens from the Saga Testnet Faucet can be requested into your Saga account using the Saga Web App {% hint style="info" %} Saga Web App is now online at You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} Click the `Get Tokens!` button towards the top right. This will open your Saga wallet.
Simply fill in the received passphrase and click on `Request PSAGA Tokens`
Your Keplr wallet may prompt you to approve this request. Simply click approve and your wallet will be funded with `350 PSAGA` tokens. ## **2. Launch your chainlet** {% hint style="warning" %} 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](/saga-web-app/working-with-chainlet/chainlet-billing) for details {% endhint %} {% hint style="info" %} Saga Web App is now online at You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} To launch a chainlet, simply click on the `Launch` tab on the Saga Web App.
In the example displayed in the image above, we are launching a chainlet called `SagaWebAppTst`. You can specify * Chainlet token's denom * Number of days of credit (note that this must be a value greater than or equal to the minimum value) you wish to add to the chainlet * EVM account address * Amount of tokens to add to the EVM account at genesis (launch of the chainlet) To add additional EVM accounts and their associated token amount at chainlet launch, simply click the **+** sign next to the EVM token amount. When you are done, simply click `Launch Chainlet`
You will get a prompt from the Keplr wallet to approve this transaction. Click Approve and the chainlet is launched! ## **3.** Obtain RPC Links and Block Explorer You can view Chainlet API and Block Explorer info from the **Saga Web App** for any chainlet. To view this information, simply head on over to the `Chainlets` tab on the landing page and then click on any chainlet to view its detailed information.
As an example, in the above listing, to view the chainlet API and block explorer details for the chainlet called `freedomchain`, simply click on it.
You can see the **RPC endpoint**, the **websocket** endpoint and the **block explorer URL** in the chainlet details page shown in the image above. ## **4.** Configuring Metamask The fastest way to configure your chainlet network settings into your metamask browser plugin is by visiting your chainlet's dedicated block explorer page and clicking on the Add \ link present on the footer menus. You can also see how this looks like in the image included below:
Or if you want to configure Metamask network manually you need to navigate to go: Metamask -> Settings -> Networks -> Add Network The settings screen will look something like this:
From here, click on "Add a network manually" and type in the following settings in the required fields: * **Network Name:** This will be your Chainlet name (in this example I'm using "`freedomchain`") * **New RPC URL**: This will be your chainlet's JSON-RPC endpoint, you can get this in -> search your chainlet -> chainlet details -> **RPC Endpoint** * **Chain ID**: Here you need to input the middle **numerical** part of the ChainID, (make sure to drop the '-1') Example: `1712762003250914` * **Currency Symbol**: This is your Chainlet currency symbol. You can get this in in -> search your chainlet -> chainlet details -> on the right of the chainlet name (On the example before `freedomchain` -> `FDC`, FDC is the Currency Symbol) * **Block Explorer URL:** This will be your personal chainlet's block explorer url, you can get this in -> search your chainlet -> chainlet details -> **Block Explorer** Taken together, the output will look **SIMILAR** with what you see in the following image below:
Once this final step is complete, you're ready to deploy any EVM-based smart contract. You can deploy with tools such as Remix, Truffle, even Thirdweb. # Mainnet Quickstart Guide This quickstart guide will walk you through the necessary steps to download, install & configure the SagaCLI, request your tokens and launch your chainlet. ## **1. Faucet Airdrop Key** Your contact at Saga will send you a Faucet Airdrop Key which will auto-fund your wallet address. If you don't have your Faucet Airdrop Key, reach out to your contact at Saga. After you have the passphrase from your Saga contact, tokens from the Saga Mainnet Faucet can be requested into your Saga account using the Saga Web App {% hint style="info" %} Saga Web App is now online at [https://app.saga.xyz/](https://app.saga.xyz/launch) You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} Click the `Get Tokens!` button towards the top right. This will open your Saga wallet.
Simply fill in the received passphrase and click on `Request PSAGA Tokens`
Your Keplr wallet may prompt you to approve this request. Simply click approve and your wallet will be funded with `350 PSAGA` tokens. ## **2. Launch your chainlet** {% hint style="warning" %} 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](/saga-web-app/working-with-chainlet/chainlet-billing) for details {% endhint %} {% hint style="info" %} Saga Web App is now online at [https://app.saga.xyz/](https://app.saga.xyz/launch) You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} To launch a chainlet, simply click on the `Launch` tab on the Saga Web App.
In the example displayed in the image above, we are launching a chainlet called `SagaWebAppTst`. You can specify * Chainlet token's denom * Number of days of credit (note that this must be a value greater than or equal to the minimum value) you wish to add to the chainlet * EVM account address * Amount of tokens to add to the EVM account at genesis (launch of the chainlet) To add additional EVM accounts and their associated token amount at chainlet launch, simply click the **+** sign next to the EVM token amount. When you are done, simply click `Launch Chainlet`
You will get a prompt from the Keplr wallet to approve this transaction. Click Approve and the chainlet is launched! ## **3.** Obtain RPC Links and Block Explorer You can view Chainlet API and Block Explorer info from the **Saga Web App** for any chainlet. To view this information, simply head on over to the `Chainlets` tab on the landing page and then click on any chainlet to view its detailed information.
As an example, in the above listing, to view the chainlet API and block explorer details for the chainlet called `abstract`, simply click on it.
You can see the **RPC endpoint**, the **websocket** endpoint and the **block explorer URL** in the chainlet details page shown in the image above. ## **4.** Configuring Metamask The fastest way to configure your chainlet network settings into your metamask browser plugin is by visiting your chainlet's dedicated block explorer page and clicking on the Add \ link present on the footer menus. You can also see how this looks like in the image included below:
Or if you want to configure Metamask network manually you need to navigate to go: Metamask -> Settings -> Networks -> Add Network The settings screen will look something like this:
From here, click on "Add a network manually" and type in the following settings in the required fields: * **Network Name:** This will be your Chainlet name (in this example I'm using "`abstract`") * **New RPC URL**: This will be your chainlet's JSON-RPC endpoint, you can get this in [https://app.saga.xyz/](https://app.saga.xyz/launch) -> search your chainlet -> chainlet details -> **RPC Endpoint** * **Chain ID**: Here you need to input the middle **numerical** part of the ChainID, (make sure to drop the '-1') Example: `2712762876035000` * **Currency Symbol**: This is your Chainlet currency symbol. You can get this in in [https://app.saga.xyz/](https://app.saga.xyz/launch) -> search your chainlet -> chainlet details -> on the right of the chainlet name (On the example before `abstract` -> `ABSTR`, ABSTR is the Currency Symbol) * **Block Explorer URL:** This will be your personal chainlet's block explorer url, you can get this in [https://app.saga.xyz/](https://app.saga.xyz/launch) -> search your chainlet -> chainlet details -> **Block Explorer** Taken together, the output will look **SIMILAR** with what you see in the following image below:
Once this final step is complete, you're ready to deploy any EVM-based smart contract. You can deploy with tools such as Remix, Truffle, even Thirdweb. # Account Management Accounts in SAGA are used to manage your SAGA token balance and execute various transactions to fund operations on top of the SAGA Platform. The token denom for the Saga Platform is PSAGA {% hint style="info" %} Saga Web App is now online: **Testnet**: \ **Mainnet**: You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} You can perform most of the account management functions using the Saga Web App.
You will use your Keplr wallet to interact with the token faucet. Once you have set up your wallet using Keplr, you can connect your Keplr wallet to the Saga Web App.
Here, you can see your Saga key's address as well as it's balance. You can request addition tokens into your wallet by requesting a [passphrase](https://docs.saga.xyz/saga-web-app/pages/H7THmgLtIpUM5Ny5Ad7d#5.-faucet-airdrop-key) and submitting them by providing that passphrase to the Saga Web App. # Requesting Tokens from Saga Faucet You will need `upsaga` tokens in order to launch chainlets using the sagacli application. To request `upsaga` tokens to be deposited in your wallet, you will also need a [passphrase](https://docs.saga.xyz/saga-web-app/account-management/pages/H7THmgLtIpUM5Ny5Ad7d#5.-faucet-airdrop-key). {% hint style="warning" %} Note that the passphrase for requesting funds from the Saga Faucet is a single use passphrase. You will receive an error if you try to re-use the same passphrase. {% endhint %} Once you have a passphrase, you can request `upsaga` tokens to be deposited into your wallet. {% hint style="info" %} Saga Web App is now online: **Testnet**: \ **Mainnet**: You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} Once you have a passphrase and have connected your Keplr wallet, simply head on over to the **Saga Web App** and click on `Get Tokens!` which is towards the top right of the page.
This will open up the wallet information and you can simply provide the passphrase and click `Request PSAGA Tokens`
# Deposit Funds into Escrow You can contribute funds towards any chainlet from the Saga Web App as long as you have the requisite funds in your wallet. In the image below, we have a chainlet called `anewchain` and we would like to add funds to it's escrow account, thereby increasing the length of time the chainlet can run.
You can simply add the number of additional days you would like to fund the chainlet. The `min` and `max` buttons calculate the days of credit automatically, based on your wallet balance. In the image above, we are adding 5 additional days to the chainlet. Simply click `Fund Chainlet` and follow the approval prompts from your Keplr wallet to process the funding transaction. {% hint style="success" %} Transactions submitted via the Saga Web App will require approval in Keplr wallet. Simply follow the Keplr wallet prompts to approve and process the transactions. {% endhint %} We can see that the chainlet has been funded and it's balance has been increased to `320 PSAGA`.
**Note**: In the image above, the Funders list (bottom right) now includes the address that added funds to the chainlet, and also reflects the stake (%) the additional funds provided to the funding address. # Withdraw Funds from Escrow Similar to adding funds to a chainlet via the Saga Web App, you can also withdraw your remaining funds from the chainlet. {% hint style="warning" %} At this time, you cannot partially defund a chainlet's escrow account. Currently, 100% of any remaining funds associated with your address will be refunded to you {% endhint %} To defund a chainlet, simply select the `Defund` option and click `Defund Chainlet`
Follow the Keplr wallet prompts to approve the transaction, and the chainlet's escrow account refunds any remaining funds associated with your address.
You can see above that the chainlet's escrow balance has decreased from `320 PSAGA` to `270 PSAGA` and your address has been refunded any remaining balance associated with your address. **Note**: See the `Funders` list in the image above (bottom right). It no longer lists your address as a funder. # View Escrow Account Information You can use the **Saga Web App** to view escrow related information, in addition to other functions. To view escrow account balances, you can simply click the `Chainlet` tab on the landing page.
The last column in the image above displays the escrow account balance associated with each chainlet. You can also notice some chainlets having a `0 PSAGA` balance. Such chainlets have run out of funds and have been stopped. You can also view detailed information associated to a chainlet's escrow account. Simply click on a chainlet to bring up its details.
In the example displayed above, we have selected a chainlet called `anewchain`. You can see it's escrow account balance and also view the funders of this chainlet under the `Funders` section. {% hint style="info" %} Anyone with a sufficient balance can contribute funds towards a chainlet. These funds are added to the chainlet's escrow account. {% endhint %} In the example above, this chainlet has two funding accounts, and they are listed under the `Funders` section, along with their respective stakes (%). # Working with Chainlet The Pegasus Incentivized Testnet is the developer’s portal into the Saga ecosystem. Like most smart contracting platforms, the developer deploys their compiled smart contract binary onto the Saga testnet. Once initialized, the Saga validators automatically provision a Saga dedicated chain, or `chainlet`, containing the smart contract. A `chainlet` is literally where the rubber meets the road! It is your own dedicated blockchain with its own validator set secured by the SAGA platform main validator set. It provides dedicated blockspace for your `web3` application. {% hint style="info" %} There can be several different *types* of chainlets i.e. a pre-packaged blockchain encapsulating some custom functionality on top of an EVM. In the near future SAGA Platform will support many different *types* of chainlets that would deploy other execution environments like CosmWasm, Solana, Javascript, etc {% endhint %} Pegasus makes its own chainlet type available to developers called `SagaOS`. It runs an EVM compatible blockchain leveraging [Cosmos SDK](https://v1.cosmos.network/sdk). With **Saga Web App** you can view the types of chainlets that can be launched, launch chainlets, view all of the chainlets you have launched as well as get detailed information on each chainlet. Additionally, each chainlet comes equipped with its own RPC endpoints to integrate with your wallet or web3 application, and a block explorer that you can use in a web browser and search for transactions, view contents of blocks and other details pertaining to the activity and state of your chainlet. # Launch your Chainlet on Testnet **Prerequisites**: [request tokens](/saga-web-app/account-management/requesting-tokens-from-saga-faucet) {% hint style="warning" %} 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](/saga-web-app/working-with-chainlet/chainlet-billing) for details {% endhint %} {% hint style="info" %} Saga Web App is now online at You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} To launch a chainlet, simply click on the `Launch` tab on the Saga Web App.
In the example displayed in the image above, we are launching a chainlet called `SagaWebAppTst`. You can specify * Chainlet token's denom * Number of days of credit (note that this must be a value greater than or equal to the minimum value) you wish to add to the chainlet * EVM account address * Amount of tokens to add to the EVM account at genesis (launch of the chainlet) To add additional EVM accounts and their associated token amount at chainlet launch, simply click the **+** sign next to the EVM token amount. When you are done, simply click `Launch Chainlet`
You will get a prompt from the Keplr wallet to approve this transaction. Click Approve and the chainlet is launched!
#### Launching with Advanced Options You can turn on advanced launch option for launching chainlet by clicking on the `Settings` icon on the launch chainlet screen
Simply use the toggle switch to turn on **advanced launch options**.
In the image above, turning on advanced launch options enables me to specify a [fee return account](/sagacli/working-with-chainlet/launch-your-chainlet-on-testnet#example-launching-a-chainlet-using-the-fee-account-flag), and also turn on/off the [base gas fee](/sagacli/working-with-chainlet/launch-your-chainlet-on-testnet#example-launching-a-chainlet-using-the-base-gas-fee-flag) switch.
In the image above, turning on the `base gas fee` switch enables me to specify a base gas fee value. Below, you can see an example of a chainlet launched using these advanced options.
For more details about this feature, you can check also: * [Stack Exploder: Unblocking Web3 Products With Costless Transactions](https://medium.com/sagaxyz/stack-exploder-unblocking-web3-products-with-costless-transactions-387b9f03b7c5) * [Stack Exploder: Implementing Costless Transactions Using Recycled Gas Tokens](https://medium.com/sagaxyz/stack-exploder-implementing-costless-transactions-using-recycled-gas-tokens-ee51548b390e) # Launch your Chainlet on Mainnet **Prerequisites**: [request tokens](/saga-web-app/account-management/requesting-tokens-from-saga-faucet) {% hint style="warning" %} 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](broken://pages/Xso8YlHLkK6kZi5F3qvo) for details {% endhint %} {% hint style="info" %} Saga Web App is now online at You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} To launch a chainlet, simply click on the `Launch` tab on the Saga Web App.
In the example displayed in the image above, we are launching a chainlet called `SagaWebAppTst`. You can specify * Chainlet token's denom * Number of days of credit (note that this must be a value greater than or equal to the minimum value) you wish to add to the chainlet * EVM account address * Amount of tokens to add to the EVM account at genesis (launch of the chainlet) To add additional EVM accounts and their associated token amount at chainlet launch, simply click the **+** sign next to the EVM token amount. When you are done, simply click `Launch Chainlet`
You will get a prompt from the Keplr wallet to approve this transaction. Click Approve and the chainlet is launched!
#### Launching with Advanced Options You can turn on advanced launch option for launching chainlet by clicking on the `Settings` icon on the launch chainlet screen
Simply use the toggle switch to turn on advanced launch options.
In the image above, turning on advanced launch options enables me to specify a [fee return account](#example-launching-a-chainlet-using-the-fee-account-flag), and also turn on/off the [base gas fee](#example-launching-a-chainlet-using-the-base-gas-fee-flag) switch.
In the image above, turning on the `base gas fee` switch enables me to specify a base gas fee value. Below, you can see an example of a chainlet launched using these advanced options.
For more details about this feature, you can check also: * [Stack Exploder: Unblocking Web3 Products With Costless Transactions](https://medium.com/sagaxyz/stack-exploder-unblocking-web3-products-with-costless-transactions-387b9f03b7c5) * [Stack Exploder: Implementing Costless Transactions Using Recycled Gas Tokens](https://medium.com/sagaxyz/stack-exploder-implementing-costless-transactions-using-recycled-gas-tokens-ee51548b390e) # Get Chainlet Information You can get details chainlet information using the [Saga Web App](https://app.saga.xyz/) On the `Chainlets` listing page, simply click on any chainlet to see detailed information associated with it.
Here, you can see all of the details associated with the chainlet called `anewchain` including it's type, launch information, RPC and websocket endpoints, the block explorer URL, chainlet's balance etc. # View Listing of Chainlets Launched {% hint style="info" %} Saga Web App is now online at: **Testnet**: \ **Mainnet**: You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} You can get a listing of all chainlets (active or not) using the **Saga Web App** In the Saga Web App, simply click the `Chainlets` tab button and view a listing of all chainlets
You can filter the chainlets listed by selecting Active (running), All (running or not), and My Chainlets (chainlets you have launched or have contributed funds) All chainlets are listed. Any chainlets that are not running are shown via a red icon.
# Chainlet APIs & BlockExplorer {% hint style="info" %} Saga Web App is now online at: **Testnet**: \ **Mainnet**: You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} You can view Chainlet API and Block Explorer info from the **Saga Web App** for any chainlet. To view this information, simply head on over to the `Chainlets` tab on the landing page and then click on any chainlet to view its detailed information.
As an example, in the above listing, to view the chainlet API and block explorer details for the chainlet called `abstract`, simply click on it.
You can see the RPC endpoint, the websocket endpoint and the block explorer URL in the chainlet details page shown in the image above. # Configuring Metamask Network This page includes instructions on how to setup your chainlet network information in your Metamask wallet The fastest way to configure your chainlet network settings into your metamask browser plugin is by visiting your chainlet's dedicated block explorer page and clicking on the Add \ link present on the footer menus. You can also see how this looks like in the image included below:
## Configuring Metamask Network Manually Navigate to go: Metamask -> Settings -> Networks -> Add Network The settings screen will look something like this:
From here, click on "Add a network manually" and type in the following settings in the required fields: * **Network Name:** This will be your Chainlet name (in this example I'm using "`abstract`") * **New RPC URL**: This will be your chainlet's JSON-RPC endpoint, you can get this in [https://app.saga.xyz/](https://app.saga.xyz/launch) -> search your chainlet -> chainlet details -> **RPC Endpoint** * **Chain ID**: Here you need to input the middle **numerical** part of the ChainID, (make sure to drop the '-1') Example: `2712762876035000` * **Currency Symbol**: This is your Chainlet currency symbol. You can get this in in [https://app.saga.xyz/](https://app.saga.xyz/launch) -> search your chainlet -> chainlet details -> on the right of the chainlet name (On the example before `abstract` -> `ABSTR`, ABSTR is the Currency Symbol) * **Block Explorer URL:** This will be your personal chainlet's block explorer url, you can get this in [https://app.saga.xyz/](https://app.saga.xyz/launch) -> search your chainlet -> chainlet details -> **Block Explorer** Taken together, the output will look **SIMILAR** with what you see in the following image below:
# Chainlet Billing ## Chainlet Billing Overview Chainlets are billed at a pre-determined interval depending on the type of chainlet it is and the duration of each epoch. Typically, a chainlet would be billed each day for the resources it consumes. {% hint style="warning" %} As each billing cycle is processed, the funds available to the chainlet inside the escrow account get depleted. Make sure you keep your escrow account funded to prevent your chainlet from being shutdown. {% endhint %} {% hint style="info" %} A chainlet setup cost is a 1-time fee charged when the chainlet is initially launched. An epoch cost is the amount billed at the end of each epoch. For SagaOS, the epoch is set to 1 day {% endhint %} As can be seen in our example listing above, we have a SetupCost of 10`psaga` (1 `psaga` = 1,000,000 `upsaga`) which is charged when the chainlet is launched. We also have an EpochCost of 10`psaga` which is the amount billed to the chainlet each day. All chainlets launched are charged a setup fee and a 30-day deposit of the epoch cost, which is then decremented as the chainlet gets billed each epoch. For our example above, our chainlet launch cost would be (SetupFee 10`psaga)` + (30 days \* EpochCost 10`psaga/day`) = 310`psaga`. This amount of **310`psaga`** is charged to the chainlet launcher's wallet at chainlet launch, and deposited into the escrow account associated with the chainlet. As the chainlet is billed each epoch, this [escrow account](/saga-web-app/account-management/view-escrow-account-information) gets depleted. {% hint style="info" %} Ensure you have sufficient funds in the wallet launching the chainlet Add funds to your chainlet at any time by [depositing funds into the chainlet's escrow](/saga-web-app/account-management/deposit-funds-into-escrow) {% endhint %} # Restarting a Stopped Chainlet As your chainlet runs, it is billed periodically. See the section on [chainlet billing](/saga-web-app/working-with-chainlet/chainlet-billing) to get an understanding of how chainlets are billed, view billing history, export billing history, and other features associated with billing of chainlets. Should your chainlet run out of funds, it will be halted and it's [status](/saga-web-app/working-with-chainlet/get-chainlet-information) will show offline. Each chainlet launched is associated with an [escrow account](/saga-web-app/account-management/view-escrow-account-information) into which funds can be added or withdrawn by anyone, at any time. Chainlets are billed by depleting the funds deposited into this escrow account. If your chainlet displays a status of STATUS\_OFFLINE and your chainlet's escrow account has been depleted, your chainlet can be restarted by [adding funds to the chainlet's escrow account](/saga-web-app/account-management/deposit-funds-into-escrow). {% hint style="warning" %} If your chainlet has been stopped due to lack of funds, you will need to [deposit 30 days](/saga-web-app/working-with-chainlet) worth of funds in the chainlet's escrow account to enable it to be restarted. {% endhint %} Once you deposit the necessary funds in the chainlet's escrow account, your chainlet should restart and show a status of `STATUS_ONLINE`. If you have issues restarting your chainlet, [please contact us](/get-help-and-support) for further support. ## Restarting a chainlet {% hint style="info" %} Saga Web App is now online at: **Testnet**: [https://testnet.app.saga.xyz](https://testnet.app.saga.xyz/)\ **Mainnet**: [https://app.saga.xyz](https://app.saga.xyz/) You will need a wallet, such as [Keplr](https://www.keplr.app/), that supports Cosmos SDK based blockchains\ If this is your first time using Keplr Wallet, follow this [tutorial](https://help.keplr.app/articles/installation-guide-for-keplr-extension-for-beginners) to install and start using it. {% endhint %} You can easily restart a stopped chainlet from the **Saga Web App** as well.
In the chainlet listing above, we can see two chains that are not active, and we can also see that their escrow account balance has gone down to `0 PSAGA`. We can restart these chainlets by adding funds to their escrow account. In the example below, we will restart the chainlet called `dchain`. We can specify the number of days of balance we would like to add to this chainlet.
Here, we are adding 30 days worth of funds. Simply specify the number of days, and then click `Restart Chainlet`. You will be prompted via Keplr to approve this transactions. Simply click approve and your chainlet will begin to restart.
The chainlet is restarted and after a few minutes, all of its status indicators turn green.
# Getting Access Pegasus is a multi-phase release of SAGA ## Getting Access Pegasus is a multi-stage release. In this (Phase I) phase, we will focus on documentation relevant to the Pegasus. To gain access to the Pegasus, projects need to be onboarded as Saga Innovators. {% hint style="danger" %} **Important:** If you are not a Saga Innovator, please [fill out the access form](https://saga.xyz/join). {% endhint %} After you complete the on-boarding form, our team will reach out to you to guide you through the process and give you access to our token faucet. If you are already a Saga Innovator, you can continue with the instructions, Funding Wallet w/ Tokens. # Quickstart Guide This quickstart guide will walk you through the necessary steps to download, install & configure the SagaCLI, request your tokens and launch your chainlet. # Testnet Quickstart Guide This quickstart guide will walk you through the necessary steps to download, install & configure the SagaCLI, request your tokens and launch your chainlet. {% hint style="warning" %} **IMPORTANT**: Pegasus Incentivized Testnet is for testing purposes only. As such, this should be used for testing ONLY, not production deployments. {% endhint %} ## 1. Download & Install SagaCLI Download the SagaCLI or check if you're running the latest SagaCLI version. Download link & latest version can be found here:[ https://docs.saga.xyz/getting-started/download-saga-cli](/sagacli/download-saga-cli) After you download the correct version for your OS, open up your command line terminal, CD to the directory where you downloaded it, then install it with the following command: `tar -xzf sagacli-operatingsystem.tar.gz -C /usr/local/bin/` Example: If you downloaded the MacOS version of the SagaCLI you would run the command: `tar -xzf sagacli-darwin-arm64.tar.gz -C /usr/local/bin/` {% hint style="info" %} Note: If you encounter an error and you're on MacOS or Linux, try using 'sudo' in the command and enter your computers password when prompted {% endhint %} `sudo tar -xzf sagacli-darwin-arm64.tar.gz -C /usr/local/bin/` Then test that you can run the SagaCLI by typing `sagacli` at your command prompt. You should see the usage and available commands appear. {% hint style="info" %} Note: If you encounter 'permission denied' when trying to run `sagacli`on MacOS or Linux, then issue the full command: `sudo chmod +x /usr/local/bin/sagacli` {% endhint %} Lastly, before you start to use `sagacli`, please ensure that you have installed the correct version. You may not be able to access all of the features in `sagacli` if you are using an incorrect version. {% hint style="danger" %} **Note:** Latest `sagacli` version is: `0.4.11` to check your version, run command: `sagacli -v` {% endhint %} ## 2. Configure SagaCLI Execute the following commands provided below to configure the `sagacli` to communicate with the Saga Platform Chain: {% hint style="warning" %} If you've used sagacli in the past on Cassiopeia, we recommend carefully verifying that all of the config parameters below are set correctly otherwise your CLI might fail. {% endhint %} 
sagacli config network-rpc https://spc.testnet.sagarpc.io
sagacli config controller https://controller.testnet.sagarpc.io
sagacli config platform-chain-id spc-testnet-2
sagacli config denom upsaga
sagacli config broadcast-mode sync
sagacli config faucet https://spc-faucet.testnet.sagarpc.io
Once this is done, you can review your configuration by running ```bash sagacli config ``` ```bash { "loglevel": "info", "controller": "https://controller.testnet.sagarpc.io", "output": "text", "keyring-backend": "os", "network-rpc": "https://spc.testnet.sagarpc.io", "from": "", "platform-chain-id": "spc-testnet-2", "denom": "upsaga", "broadcast-mode": "sync", "ledger": "false", "faucet": "https://spc-faucet.testnet.sagarpc.io", "base-gas-fee": "" } ``` {% hint style="info" %} The "keyring-backend" in your config may show "os" or "file", this does NOT need to match with what's displayed above. {% endhint %} ## 3. Verify SagaCLI After completing Steps 1 & 2 run the following command to verify the `sagacli` is communicating with the Saga Platform Chain: ```bash sagacli status ``` You should see the following output: ``` Saga Platform Chain Controller ------------------- ---------- Online Online ``` ## **4. Generate Key/Address with SagaCLI** Next you'll setup your Key/Address. This is where you'll receive your `upsaga` tokens so you can launch your chainlet. 
sagacli keys add <keyname>
Example: To generate a new key and call it `mykey1` you would issue the command: ``` $ sagacli keys add mykey1 ``` You'll then be prompted with: ``` $ Enter keyring passphrase: ``` The keyring passphrase can be anything you want but you'll you need to remember it as you'll need it to launch, manage and work with your chainlet. Once completed, you should see this output. (The keyname will be different for your as well as the mnemoic phrase.) ``` $ sagacli keys add mykey1 - address: saga17tz488sq54l72mpt3ntl95gc50qtwta9l986u6 name: mykey1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AnxGYN/vnFJ0L6PXJr5aaUE+zGI+AKvNc7U+vPhu5joM"}' type: local **Important** write this mnemonic phrase in a safe place. It is the only way to recover your account if you ever forget your password. ``` ## **5. Faucet Airdrop Key** Your contact at Saga will send you a Faucet Airdrop Key which will auto-fund your wallet address. If you don't have your Faucet Airdrop Key, reach out to your contact at Saga. After you have the passphrase from your Saga contact, tokens from the Saga Testnet Faucet can be requested into your Saga account using the Saga Web App or using the `sagacli` ``` sagacli account get-tokens ``` Example: If you were provided with the Faucet Airdrop Key named "projectx-1" then issue this command and press enter: ``` $ sagacli account get-tokens projectx-1 ``` Next, you'll be prompted to enter your keyring passphrase which is the same keyring passphrase you setup in Step#4. After a few seconds, you will see a response similar to this: {% code overflow="wrap" %} ``` $ Success! Faucet funded wallet saga1f7at0lnkd89t69eltkvcvuydq9enwsa942nqw6. Tx: A581EE27B208BFDC8F497A3416B942B8BB25BB7761BF13F4258E0C7A9F8D3D3D ``` {% endcode %} ## **6. Confirm Token Airdrop** Once you receive the "Success! Faucet funded wallet" message, the Token Airdrop is complete and you can verify using the `sagacli` by issuing the command: ``` sagacli account balance ``` You should see a minimum of `350,000,000 upsaga` (350 PSAGA) in your account. ## **7. Launch Chainlet using SagaCLI** {% hint style="warning" %} Ensure you have sufficient funds in the launcher's wallet. To launch a chainlet of type SagaOS, you need at least **310,000,000 `upsaga (310 PSAGA)`**. See the [chainlet billing](/sagacli/working-with-chainlet/chainlet-billing) section for more details. {% endhint %} There are several different options for launching a Chainlet. Details can be found [here](/sagacli/working-with-chainlet/launch-your-chainlet-on-mainnet). 
sagacli chainlet launch SagaOS 0.5.17 <your project name> --genesis-account <Insert your Metamask address here>:<Tokens to be added to this account> --denom <your token denom> --fees 2500upsaga
Here's an example command that launches a chainlet called `myprojectname`: ``` sagacli chainlet launch SagaOS 0.5.17 myprojectname --genesis-account 0xFd54E1809f031727AD392445351ca2e02cA15c2A:100000000 --denom mpn --fees 2500upsaga ``` Now let's break down this command: * `sagacli chainlet launch` * The base command to launch chainlet * `SagaOS` * The chainlet type to launch. You can see the full list of chainlet types by running `sagacli chainlet list-types` * `0.5.17` * The chainlet stack version to launch. Run the command: `sagacli chainlet list-types` and you'll see that `0.5.17` is the "Version" * `myprojectname` * The name of your project, ie. if your project name is "Cool Web3 Game" then name it `coolweb3game` * `--genesis-account 0xFd54E1809f031727AD392445351ca2e02cA15c2A:100000000` * The `genesis-account` flag is composed of your EVM address, along with the number of full tokens you want in your account, separated by a colon. The address can be copied directly from Metamask * `--fees 2500upsaga` * The fee to pay for this chainlet launch transaction * `--denom mpn` * The currency symbol you'll create. This should be between 2 and 6 characters. `mpn` is just used for this example. Then press Enter and your Chainlet will launch.
## **8.** Obtain RPC Links and Block Explorer using SagaCLI {% hint style="info" %} Typically, a chainlet is launched within one minute of issuing a chainlet launch command as described above. However, it can take longer, sometimes up to 2 to 3 minutes. So, if no data is returned by the commands in this section, please try again. {% endhint %} To obtain your URL's you'll first need your ChainID. To get your ChainID, simply issue the command: ``` sagacli chainlet list ``` You will see similar output. You'll want to take note of your ChainID. In this example, my ChainID is coolapp\_1682719845971475-1 ``` $ sagacli chainlet list ChainId Name. StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- freedomchain_1712762003250914-1 freedomchain SagaOS 0.5.17 Online 230000000upsaga ``` Next you'll run the following command. Make sure to replace \ with your actual ChainID ``` sagacli chainlet apis ``` {% hint style="warning" %} It may take a few minutes for these endpoints to become available, and the Status will display as Unavailable until they do. {% endhint %} Example: ``` $ sagacli chainlet apis coolapp_1682719845971475-1 Name Endpoint Status ---- -------- ------ jsonrpc freedomchain-1712762003250914-1.jsonrpc.testnet.sagarpc.io Available ws freedomchain-1712762003250914-1.ws.testnet.sagarpc.io Available explorer freedomchain-1712762003250914-1.testnet.sagaexplorer.io Available ``` ## **9.** Configuring Metamask Network: Navigate to Metamask -> Settings -> Networks -> Add Network The settings screen will look something like this:
From here, click on "Add a network manually" and type in the following settings in the required fields: * **Network Name:** This will be your Chainlet name (in this example I'm using "coolapp") * **New RPC URL**: This will be your chainlet's JSON-RPC endpoint from the `sagacli chainlet apis` command we executed in Step 8 * ``` https://freedomchain-1712762003250914-1.jsonrpc.testnet.sagarpc.io ``` * **Chain ID**: Here you need to input the middle **numerical** part of the ChainID. First, issue the command `sagacli chainlet list` * ``` $ sagacli chainlet list ChainId Name StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- freedomchain_1712762003250914-1 freedomchain SagaOS 0.5.17 Online 230000000upsaga ``` * Second, use the middle **numerical** part of the ChainID (make sure to drop the '-1') Example below * ``` 1712762003250914 ``` * **Currency Symbol**: This is your Chainlet currency symbol. You can get that by calling the `sagacli chainlet get ` * ``` $ sagacli chainlet get coolapp_1682719845971475-1 ChainId Name StackName StackVersion Launcher Mantainers CurrencySymbol Status ------- ---- --------- ------------ -------- ---------- -------------- ------ freedomchain_1712762003250914-1 freedomchain SagaOS 0.5.17 saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3 [saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3] fdc STATUS_ONLINE ``` * **Block Explorer URL** * ``` https://freedomchain-1712762003250914-1.testnet.sagaexplorer.io ``` Taken together, the output will look similar with what you see in the following image below:
Once this final step is complete, you're ready to deploy any EVM-based smart contract. You can deploy with tools such as Remix, Truffle, even Thirdweb. # Mainnet Quickstart Guide This quickstart guide will walk you through the necessary steps to download, install & configure the SagaCLI, request your tokens and launch your chainlet. ## 1. Download & Install SagaCLI Download the SagaCLI or check if you're running the latest SagaCLI version. Download link & latest version can be found here:[ https://docs.saga.xyz/getting-started/download-saga-cli](/sagacli/download-saga-cli) After you download the correct version for your OS, open up your command line terminal, CD to the directory where you downloaded it, then install it with the following command: `tar -xzf sagacli-operatingsystem.tar.gz -C /usr/local/bin/` Example: If you downloaded the MacOS version of the SagaCLI you would run the command: `tar -xzf sagacli-darwin-arm64.tar.gz -C /usr/local/bin/` {% hint style="info" %} Note: If you encounter an error and you're on MacOS or Linux, try using 'sudo' in the command and enter your computers password when prompted {% endhint %} `sudo tar -xzf sagacli-darwin-arm64.tar.gz -C /usr/local/bin/` Then test that you can run the SagaCLI by typing `sagacli` at your command prompt. You should see the usage and available commands appear. {% hint style="info" %} Note: If you encounter 'permission denied' when trying to run `sagacli`on MacOS or Linux, then issue the full command: `sudo chmod +x /usr/local/bin/sagacli` {% endhint %} Lastly, before you start to use `sagacli`, please ensure that you have installed the correct version. You may not be able to access all of the features in `sagacli` if you are using an incorrect version. {% hint style="danger" %} **Note:** Latest `sagacli` version is: `0.4.11` to check your version, run command: `sagacli -v` {% endhint %} ## 2. Configure SagaCLI Execute the following commands provided below to configure the `sagacli` to communicate with the Saga Platform Chain: {% hint style="warning" %} If you've used sagacli in the past on Cassiopeia, we recommend carefully verifying that all of the config parameters below are set correctly otherwise your CLI might fail. {% endhint %} 
sagacli config network-rpc https://spc.sagarpc.io/
sagacli config controller https://controller.sagarpc.io/
sagacli config platform-chain-id spc-1
sagacli config denom upsaga
sagacli config broadcast-mode sync
sagacli config faucet https://spc-faucet.sagarpc.io
Once this is done, you can review your configuration by running ```bash sagacli config ``` ```bash { "loglevel": "info", "controller": "https://controller.sagarpc.io", "output": "text", "keyring-backend": "os", "network-rpc": "https://spc.sagarpc.io", "from": "", "platform-chain-id": "spc-1", "denom": "upsaga", "broadcast-mode": "sync", "ledger": "false", "faucet": "https://spc-faucet.sagarpc.io", "base-gas-fee": "" } ``` {% hint style="info" %} The "keyring-backend" in your config may show "os" or "file", this does NOT need to match with what's displayed above. {% endhint %} ## 3. Verify SagaCLI After completing Steps 1 & 2 run the following command to verify the `sagacli` is communicating with the Saga Platform Chain: ```bash sagacli status ``` You should see the following output: ``` Saga Platform Chain Controller ------------------- ---------- Online Online ``` ## **4. Generate Key/Address with SagaCLI** Next you'll setup your Key/Address. This is where you'll receive your `upsaga` tokens so you can launch your chainlet. 
sagacli keys add <keyname>
Example: To generate a new key and call it `mykey1` you would issue the command: ``` $ sagacli keys add mykey1 ``` You'll then be prompted with: ``` $ Enter keyring passphrase: ``` The keyring passphrase can be anything you want but you'll you need to remember it as you'll need it to launch, manage and work with your chainlet. Once completed, you should see this output. (The keyname will be different for your as well as the mnemoic phrase.) ``` $ sagacli keys add mykey1 - address: saga17tz488sq54l72mpt3ntl95gc50qtwta9l986u6 name: mykey1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AnxGYN/vnFJ0L6PXJr5aaUE+zGI+AKvNc7U+vPhu5joM"}' type: local **Important** write this mnemonic phrase in a safe place. It is the only way to recover your account if you ever forget your password. ``` ## **5. Faucet Airdrop Key** Your contact at Saga will send you a Faucet Airdrop Key which will auto-fund your wallet address. If you don't have your Faucet Airdrop Key, reach out to your contact at Saga. After you have the passphrase from your Saga contact, tokens from the Saga Faucet can be requested into your Saga account using the Saga Web App or using the `sagacli` ``` sagacli account get-tokens ``` Example: If you were provided with the Faucet Airdrop Key named "projectx-1" then issue this command and press enter: ``` $ sagacli account get-tokens projectx-1 ``` Next, you'll be prompted to enter your keyring passphrase which is the same keyring passphrase you setup in Step#4. After a few seconds, you will see a response similar to this: {% code overflow="wrap" %} ``` $ Success! Faucet funded wallet saga1f7at0lnkd89t69eltkvcvuydq9enwsa942nqw6. Tx: A581EE27B208BFDC8F497A3416B942B8BB25BB7761BF13F4258E0C7A9F8D3D3D ``` {% endcode %} ## **6. Confirm Token Airdrop** Once you receive the "Success! Faucet funded wallet" message, the Token Airdrop is complete and you can verify using the `sagacli` by issuing the command: ``` sagacli account balance ``` You should see a minimum of `350,000,000 upsaga` (350 PSAGA) in your account. ## **7. Launch Chainlet using SagaCLI** {% hint style="warning" %} Ensure you have sufficient funds in the launcher's wallet. To launch a chainlet of type SagaOS, you need at least **310,000,000 `upsaga (310 PSAGA)`**. See the [chainlet billing](/sagacli/working-with-chainlet/chainlet-billing) section for more details. {% endhint %} There are several different options for launching a Chainlet. Details can be found [here](/sagacli/working-with-chainlet/launch-your-chainlet-on-mainnet). 
sagacli chainlet launch SagaOS 0.5.17 <your project name> --genesis-account <Insert your Metamask address here>:<Tokens to be added to this account> --denom <your token denom> --fees 2500upsaga
Here's an example command that launches a chainlet called `myprojectname`: ``` sagacli chainlet launch SagaOS 0.5.17 myprojectname --genesis-account 0xFd54E1809f031727AD392445351ca2e02cA15c2A:100000000 --denom mpn --fees 2500upsaga ``` Now let's break down this command: * `sagacli chainlet launch` * The base command to launch chainlet * `SagaOS` * The chainlet type to launch. You can see the full list of chainlet types by running `sagacli chainlet list-types` * `0.5.17` * The chainlet stack version to launch. Run the command: `sagacli chainlet list-types` and you'll see that `0.5.17` is the "Version" * `myprojectname` * The name of your project, ie. if your project name is "Cool Web3 Game" then name it `coolweb3game` * `--genesis-account 0xFd54E1809f031727AD392445351ca2e02cA15c2A:100000000` * The `genesis-account` flag is composed of your EVM address, along with the number of full tokens you want in your account, separated by a colon. The address can be copied directly from Metamask * `--fees 2500upsaga` * The fee to pay for this chainlet launch transaction * `--denom mpn` * The currency symbol you'll create. This should be between 2 and 6 characters. `mpn` is just used for this example. Then press Enter and your Chainlet will launch.
## **8.** Obtain RPC Links and Block Explorer using SagaCLI {% hint style="info" %} Typically, a chainlet is launched within one minute of issuing a chainlet launch command as described above. However, it can take longer, sometimes up to 2 to 3 minutes. So, if no data is returned by the commands in this section, please try again. {% endhint %} To obtain your URL's you'll first need your ChainID. To get your ChainID, simply issue the command: ``` sagacli chainlet list ``` You will see similar output. You'll want to take note of your ChainID. In this example, my ChainID is coolapp\_1682719845971475-1 ``` $ sagacli chainlet list ChainId Name StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- coolapp_1682719845971475-1 coolapp SagaOS 0.5.17 Online 230000000upsaga ``` Next you'll run the following command. Make sure to replace \ with your actual ChainID ``` sagacli chainlet apis ``` {% hint style="warning" %} It may take a few minutes for these endpoints to become available, and the Status will display as Unavailable until they do. {% endhint %} Example: ``` $ sagacli chainlet apis coolapp_1682719845971475-1 Name Endpoint Status ---- -------- ------ jsonrpc coolapp-1682719845971475-1.jsonrpc.sagarpc.io Available ws coolapp-1682719845971475-1.ws.sagarpc.io Available explorer coolapp-1682719845971475-1.sagaexplorer.io Available ``` ## **9.** Configuring Metamask Network: Navigate to Metamask -> Settings -> Networks -> Add Network The settings screen will look something like this:
From here, click on "Add a network manually" and type in the following settings in the required fields: * **Network Name:** This will be your Chainlet name (in this example I'm using "coolapp") * **New RPC URL**: This will be your chainlet's JSON-RPC endpoint from the `sagacli chainlet apis` command we executed in Step 8 * 
https://coolapp-1682719845971475-1.jsonrpc.sagarpc.io
* **Chain ID**: Here you need to input the middle **numerical** part of the ChainID. First, issue the command `sagacli chainlet list` * ``` $ sagacli chainlet list ChainId Name StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- coolapp_1682719845971475-1 coolapp SagaOS 0.5.17 Online 230000000upsaga ``` * Second, use the middle **numerical** part of the ChainID (make sure to drop the '-1') Example below * ``` 1682719845971475 ``` * **Currency Symbol**: This is your Chainlet currency symbol. You can get that by calling the `sagacli chainlet get ` * ``` $ sagacli chainlet get coolapp_1682719845971475-1 ChainId Name StackName StackVersion Launcher Mantainers CurrencySymbol Status ------- ---- --------- ------------ -------- ---------- -------------- ------ coolapp_1682719845971475-1 coolapp SagaOS 0.5.17 saga1f7at0lnkd89t69eltkvcvuykq9enwsa942nqw6 [saga1f7at0lnkd89t69eltkvcvuykq9enwsa942nqw6] coolcoin STATUS_ONLINE ``` * **Block Explorer URL** * ``` https://coolapp-1682719845971475-1.sagaexplorer.io ``` Taken together, the output will look **SIMILAR** with what you see in the following image below:
Once this final step is complete, you're ready to deploy any EVM-based smart contract. You can deploy with tools such as Remix, Truffle, even Thirdweb. # Download Saga CLI Please use the links below to download the CLI binary that best suits your developer environment {% hint style="info" %} **Note:** Latest `sagacli` version is: `0.4.11` to check your version, run command: `sagacli -v` {% endhint %} {% tabs %} {% tab title="MacOS" %} ### Is your Mac Apple Silicon or Intel? To find out if your Mac is Apple Silicon or Intel, First click on the Apple logo in the top left of your screen, Second click on "About this Mac" when the window pops up, you'll either see "Chip" or "Processor" listed in the pop-up box. ### Mac with Apple Silicon - "Chip" * [sagacli-darwin-arm64.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/macos-applesilicon/sagacli-darwin-arm64.tar.gz) * [sagacli-darwin-arm64.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/macos-applesilicon/sagacli-darwin-arm64.tar.gz.md5) ### Mac with Intel - "Processor" * [sagacli-darwin-amd64.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/macos-intel/sagacli-darwin-amd64.tar.gz) * [sagacli-darwin-amd64.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/macos-intel/sagacli-darwin-amd64.tar.gz.md5) {% endtab %} {% tab title="Linux" %} ### Linux i386 Platform * [sagacli-linux-i386.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/linux-i386/sagacli-linux-386.tar.gz) * [sagacli-linux-i386.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/linux-i386/sagacli-linux-386.tar.gz.md5) ### Linux AMD64 Platform * [sagacli-linux-amd64.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/linux-amd64/sagacli-linux-amd64.tar.gz) * [sagacli-linux-amd64.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/linux-amd64/sagacli-linux-amd64.tar.gz.md5) ### Linux ARM64 Platform * [sagacli-linux-arm64.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/linux-arm64/sagacli-linux-arm64.tar.gz) * [sagacli-linux-arm64.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/linux-arm64/sagacli-linux-arm64.tar.gz.md5) {% endtab %} {% tab title="Windows" %} ### Windows i386 Platform * [sagacli-windows-386.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/windows-i386/sagacli-windows-386.tar.gz) * [sagacli-windows-386.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/windows-i386/sagacli-windows-386.tar.gz.md5) ### Windows AMD64 Platform * [sagacli-windows-amd64.tar.gz](https://cassiotestnet-download.s3.amazonaws.com/windows-amd64/sagacli-windows-amd64.tar.gz) * [sagacli-windows-amd64.tar.gz.md5](https://cassiotestnet-download.s3.amazonaws.com/windows-amd64/sagacli-windows-amd64.tar.gz.md5) {% endtab %} {% endtabs %} # Install Saga CLI {% hint style="info" %} **Good to know:** You would need a computer which has a decent and reliable connection to the internet. Additionally, if you have a firewall, you will need to ensure that outbound traffic is allowed for port 443 (HTTPS). {% endhint %} ## Installation (Linux or Mac) At the shell prompt, type to unarchive and install the cli in the desired path ``` tar -xzf -C ``` Example: ``` tar -xzf pegasus.tar.gz -C /usr/local/bin/ ``` {% hint style="info" %} Depending on the folder you decide to install `sagacli` to, you may need to use `sudo` permissions i.e. prefixing your command with sudo. Also check if the directory `` in step 1 is already in the PATH e.g. on Linux {% endhint %} If the directory is not in the `PATH`, add it to the `PATH` depending on your host operating system and shell used. Example, on Linux you would use: ``` export PATH=$PATH: ``` We recommend adding this change to your shell's profile (`~/.profile` or `~/.bashrc` or `~/.bash_profile`). {% hint style="info" %} On Linux and Mac, ensure you source the profile updates e.g. `source ~/.profile` or `source ~/.bash_profile` etc., depending on the file you updated. {% endhint %} {% hint style="warning" %} On some versions of MacOS, you will need to remove the newly downloaded binary from quarantine by using the following command in your terminal:\ \ `xattr -d com.apple.quarantine /path/to/sagacli` {% endhint %} Test that `sagacli` has been installed by running `sagacli` from any shell prompt. You should get an output like this: ``` Interact with Pegasus Usage: sagacli [command] Available Commands: account Account queries and transactions subcommands chainlet Chainlet queries and transaction subcommands completion Generate the autocompletion script for the specified shell config Create or query an application CLI configuration file help Help about any command keys Manage your application's keys status Query configured systems status tx Transactions queries subcommands Flags: --controller string controller grpc url (host:port) (default "https://controller.testnet-sp1.sagarpc.io") --from string Name of private key used to sign (default "bogdan_local") -h, --help help for sagacli --keyring-backend string Select keyring's backend (os|file|test) (default "file") --ledger Use the connected Ledger device for signing tx -l, --loglevel string commands logging level (default "info") --network-rpc string : to tendermint rpc interface for remote chain (default "https://spc.testnet-sp1.sagarpc.io") -o, --output string output type (default "text") --platform-chain-id string The SPC network chain ID (default "spc-testnet-1") -v, --version version for sagacli Use "sagacli [command] --help" for more information about a command. ``` # Configure Saga CLI ## Configure `sagacli for Saga Mainnet` The `sagacli` executable communicates with our Pegasus server applications securely over `HTTPS`. Before you can start using `sagacli`, you must configure it talk to the Saga Platform Chain as well as the Saga Controller. {% hint style="warning" %} If you've used sagacli in the past on Cassiopeia, we recommend carefully verifying that all of the config parameters below are set correctly otherwise your CLI might fail. {% endhint %} Execute the following commands provided below to configure `sagacli`: ``` sagacli config network-rpc https://spc.sagarpc.io sagacli config controller https://controller.sagarpc.io sagacli config platform-chain-id spc-1 sagacli config denom upsaga sagacli config broadcast-mode sync sagacli config faucet https://spc-faucet.sagarpc.io ``` Ok, now that we have configured the endpoints, it's time to check if they actually work. To do that, run the following command: ``` sagacli status ``` You should see the following output: ``` Saga Platform Chain Controller ------------------- ---------- Online Online ``` {% hint style="warning" %} **IMPORTANT**: If either of the two applications indicate a value of `false`, the configuration was not successful. Check your local network connection to ensure that you are connected to the internet, and that your firewall application isn't blocking outgoing traffic over `HTTPS`. {% endhint %} ## Configure `sagacli for Saga Testnet` The `sagacli` executable communicates with our Pegasus server applications securely over `HTTPS`. Before you can start using `sagacli`, you must configure it talk to the Saga Platform Chain as well as the Saga Controller. {% hint style="warning" %} If you've used sagacli in the past on Cassiopeia, we recommend carefully verifying that all of the config parameters below are set correctly otherwise your CLI might fail. {% endhint %} Execute the following commands provided below to configure `sagacli`: ``` sagacli config network-rpc https://spc.testnet.sagarpc.io sagacli config controller https://controller.testnet.sagarpc.io sagacli config platform-chain-id spc-testnet-2 sagacli config denom upsaga sagacli config broadcast-mode sync sagacli config faucet https://spc-faucet.testnet.sagarpc.io ``` Ok, now that we have configured the endpoints, it's time to check if they actually work. To do that, run the following command: ``` sagacli status ``` You should see the following output: ``` Saga Platform Chain Controller ------------------- ---------- Online Online ``` {% hint style="warning" %} **IMPORTANT**: If either of the two applications indicate a value of `false`, the configuration was not successful. Check your local network connection to ensure that you are connected to the internet, and that your firewall application isn't blocking outgoing traffic over `HTTPS`. {% endhint %} ## Next Steps To launch your very first chainlet, there are a few easy steps you will need to go through. Broadly: * [Create a key,](/sagacli/key-management/adding-keys#creating-a-new-key-in-sagacli) or [import your existing key](/sagacli/key-management/adding-keys#import-an-existing-key-into-sagacli), in `sagacli` and provide that to your Saga contact person * Your `sagacli` account will receive airdropped tokens. If you do not have tokens, please request them via the [Getting Access](/sagacli/getting-access) page * [Launch your chainlet ](/sagacli/working-with-chainlet/launch-your-chainlet-on-mainnet)and run commands against it {% hint style="info" %} You can access the help for any of the commands by running `sagacli [command?] [subcommand?] --help`. {% endhint %} # Key Management ## Sagacli and Key Management `sagacli` stores and manages your key pairs. You can either create a new key or import your existing key(s). These keys may be in any format as long as the format is supported by the Tendermint crypto library. It can be used by light-clients, full nodes, or any other application that needs to sign with a private key. ## Keyring The keyring supports the following backends:
osUses the operating system's default credentials store.
fileUses encrypted file-based keystore within the app's configuration directory. This keyring will request a password each time it is accessed, which may occur multiple times in a single command resulting in repeated password prompts.
kwalletUses KDE Wallet Manager as a credentials management application.
passUses the pass command line utility to store and retrieve keys.
testStores keys insecurely to disk. It does not prompt for a password to be unlocked and it should be use only for testing purposes.
`kwallet` and `pass` backends depend on external tools. Refer to their respective documentation for more information: see [KWallet](https://github.com/KDE/kwallet) and [pass](https://www.passwordstore.org/) The pass backend requires [GnuPG](https://gnupg.org/). ## Supported Functions To view key management functions supported by `sagacli`, look at the output below. ``` $ sagacli keys --help Usage: sagacli keys [command] Available Commands: add Add an encrypted private key (either newly generated or recovered), encrypt it, and save to file delete Delete the given keys list List all keys rename Rename an existing key show Retrieve key information by name or address Flags: -h, --help help for keys Global Flags: --controller string controller grpc url (host:port) (default "https://controller.testnet-sp1.sagarpc.io") --from string Name of private key used to sign (default "bogdan_local") --keyring-backend string Select keyring's backend (os|file|test) (default "file") --ledger Use the connected Ledger device for signing tx -l, --loglevel string commands logging level (default "info") --network-rpc string : to tendermint rpc interface for remote chain (default "https://spc.testnet-sp1.sagarpc.io") -o, --output string output type (default "text") --platform-chain-id string The SPC network chain ID (default "spc-testnet-1") Use "sagacli keys [command] --help" for more information about a command. ``` # Adding Keys ## Command Before you can create chainlets, you will need to add a public/private keypair (aka key) to `sagacli`. You have the option to either create a new key, or import a key you have already created previously. {% hint style="info" %} All of the keys are created using the `secp256k1` elliptical curve and are securely held in a keyring managed by `sagacli`. However, you also have several different options to create your keys e.g. use a different algorithm than the default of `secp256k1`. {% endhint %} A full list of options with which to add keys can be viewed by the following command: ``` $ sagacli keys add --help Derive a new private key and encrypt to disk. Optionally specify a BIP39 mnemonic, a BIP39 passphrase to further secure the mnemonic, and a bip32 HD path to derive a specific account. The key will be stored under the given name and encrypted with the given password. The only input that is required is the encryption password. If run with -i, it will prompt the user for BIP44 path, BIP39 mnemonic, and passphrase. The flag --recover allows one to recover a key from a seed passphrase. If run with --dry-run, a key would be generated (or recovered) but not stored to the local keystore. Use the --pubkey flag to add arbitrary public keys to the keystore for constructing multisig transactions. You can create and store a multisig key by passing the list of key names stored in a keyring and the minimum number of signatures required through --multisig-threshold. The keys are sorted by address, unless the flag --nosort is set. Example: keys add mymultisig --multisig "keyname1,keyname2,keyname3" --multisig-threshold 2 Usage: sagacli keys add [flags] Flags: --account uint32 Account number for HD derivation (less than equal 2147483647) --coin-type uint32 coin type number for HD derivation (default 118) --dry-run Perform action, but don't add key to local keystore --hd-path string Manual HD Path derivation (overrides BIP44 config) -h, --help help for add --index uint32 Address index number for HD derivation (less than equal 2147483647) -i, --interactive Interactively prompt user for BIP39 passphrase and mnemonic --key-type string Key signing algorithm to generate keys for (default "secp256k1") --ledger Store a local reference to a private key on a Ledger device --multisig strings List of key names stored in keyring to construct a public legacy multisig key --multisig-threshold int K out of N required signatures. For use in conjunction with --multisig (default 1) --no-backup Don't print out seed phrase (if others are watching the terminal) --nosort Keys passed to --multisig are taken in the order they're supplied --pubkey string Parse a public key in JSON format and saves key info to file. --recover Provide seed phrase to recover existing key instead of creating Global Flags: --controller string controller grpc url (host:port) (default "https://controller.testnet-sp1.sagarpc.io") --from string Name of private key used to sign (default "bogdan_local") --keyring-backend string Select keyring's backend (os|file|test) (default "file") -l, --loglevel string commands logging level (default "info") --network-rpc string : to tendermint rpc interface for remote chain (default "https://spc.testnet-sp1.sagarpc.io") -o, --output string output type (default "text") --platform-chain-id string The SPC network chain ID (default "spc-testnet-1") ``` ## Creating a New Key in `sagacli` To create a new key using the default keyring and algorithm, simply type ``` sagacli keys add ``` So, for instance, if you want to generate a new key and call it `mykey1`, then you will type ``` sagacli keys add mykey1 ``` {% hint style="info" %} **Keep in Mind**: If this is your first time creating a key in `sagacli`, you will also be prompted for a password for the `os` keyring, that secures the keys using this password. Provide a strong password to secure the keyring. {% endhint %} This will generate the following output, and store the key in the default keyring, which is `os`. ``` - address: saga1tkax73wxs047nc8kaalhfc4ar6gay2sde28crx name: mykey1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A1YCpZPIzs6MXTiMAOnlEK6Cq8+JQMii9a4vUnyQ0qGs"}' type: local **Important** write this mnemonic phrase in a safe place. It is the only way to recover your account if you ever forget your password. powder knee very truth side engine food brave distance profit pottery move labor machine apology fringe source fragile aim wedding timber since blouse brain ``` You will notice that the key `mykey1` has been generated and allocated an address, which in this case is `saga1tkax73wxs047nc8kaalhfc4ar6gay2sde28crx`. Additionally, from the output above, we can see that this key was generated using the `secp256k1` algorithm. {% hint style="danger" %} **IMPORTANT:** Make sure to copy the mnemonic phrase and save it to a safe place. As the output above indicates, should you forget your password, the only way to recover this key would be the mnemonic phrase. {% endhint %} To create a key in a different keyring (other than the default `os` keyring), you can specify the `--keyring-backend` flag. For example, to create a key in the `test` keyring, type ``` sagacli keys add test3 --keyring-backend test ``` This will create a key in the `test` keyring. ``` - address: saga1yzm4fygqehgravje290pk8ddwr8lld0g7nsn87 name: test3 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AvvszXyFvHfr2DEhLdf4lF2sQfp6fRDBXqQvxJV4hYFs"}' type: local **Important** write this mnemonic phrase in a safe place. It is the only way to recover your account if you ever forget your password. casino replace enrich sniff canyon search message together remain document verify absurd settle flame public fresh spray together tenant video suit pelican lemon opinion ``` {% hint style="info" %} Please bear in mind that not all keyrings are secure. For more information about supported keyrings and their security features, please refer to Key Management Overview. {% endhint %} ## Import an Existing Key into `sagacli` You may have keys that you already use that you want to use with `sagacli`. To do so, you will need to import your existing key into `sagacli`. You will need to have access to the BIP39 mnemonic phrase associated with the key you are trying to import. As long you have the mnemonic phrase, you can import an existing key by: ``` sagacli keys add --recover ``` For example, if you want to import an existing key called `test1` into `sagacli`, you would type ``` sagacli keys add test1 --recover ``` This will prompt you to enter the BIP39 mnemonic. ``` $ sagacli keys add test1 --recover > Enter your bip39 mnemonic friend account warrior undo biology elevator crime hole skull nuclear age beef census arena kind canvas prison visual popular love brush bicycle ecology task ``` The new key is generated and saved to the default keyring, and its address is echoed to the screen. ``` - address: saga1z0uscdcprxcun2mlnyrz5kelemmjw768sdrgz5 name: test1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+u4iLJZWZHHcRIEbme8ppbmk1jYTpZVio8anPqAIQ31"}' type: local ``` ## Configuring a Default Key in `sagacli` You can configure a default key in `sagacli` which will then be used in all transactions and queries unless you override it by using the `--address` flag. The default key can be configured using the following command: ``` sagacli config from ``` For example, if we have a key called `fundkey` and we would like to set it as the default key, we would type ``` sagacli config from fundkey ``` *Note:* Ensure that the key being tagged as default actually exists in `sagacli`. To view the default key, type ``` sagacli config from ``` This will display if a default key has been set. In this example using `fundkey`, we get ``` $ sagacli config from fundkey ``` # Listing Keys ## List All Keys To list all keys stored in `sagacli`, type ``` sagacli keys list ``` This will produce an output that displays all the keys stored in the default keyring (`os`). ``` $ sagacli keys list - address: saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re name: metamask pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A4lAzjJ4bZnZIEhYQvW+qsgg9SzwQOkOgFG+q5enEv4l"}' type: local - address: saga1tkax73wxs047nc8kaalhfc4ar6gay2sde28crx name: mykey1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A1YCpZPIzs6MXTiMAOnlEK6Cq8+JQMii9a4vUnyQ0qGs"}' type: local - address: saga1z0uscdcprxcun2mlnyrz5kelemmjw768sdrgz5 name: test1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+u4iLJZWZHHcRIEbme8ppbmk1jYTpZVio8anPqAIQ31"}' type: local ``` ## Different Keyring To list keys held in a different keyring (not the default `os`), simply pass the `--keyring-backend ` to the list command: ``` $ sagacli keys list --keyring-backend test - address: saga170ap6wma3vy6v6yjdwhq402hkccxmenng4g0rh name: test2 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AjO7X3g+CFcSAhfd77Rnf5KTBSS9pTG7BFn2jBVU1GdI"}' type: local ``` ## Further Details For a full list of options associated with listing keys, type ``` sagacli keys list --help ``` # Display Key Details ## Command To display details for a specific key, you can use the following command: ``` sagacli keys show ``` For example, to list the details associated with the key named `test1`, you would type ``` $ sagacli keys show test1 - address: saga1z0uscdcprxcun2mlnyrz5kelemmjw768sdrgz5 name: test1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+u4iLJZWZHHcRIEbme8ppbmk1jYTpZVio8anPqAIQ31"}' type: local ``` {% hint style="info" %} Use the `sagacli keys show --bech ` to see the account, validator operator and consensus components of the key. {% endhint %} ## Further Details For a full list of options supported by the `show` command, type ``` sagacli keys show --help ``` # Deleting Keys ## Command To delete a key from `sagacli`, you can use the key delete command in the following manner: ``` sagacli keys delete ``` {% hint style="danger" %} **IMPORTANT:**: Please bear in mind that before you delete a key, you should ensure that 1. There are no assets i.e. chainlets associated to the address belonging to the key being deleted. If there are any assets, you will not be able to transact with these assets as those transactions would require signatures provided by the key. 2. The address associated with the key does not have an escrow balance. If the balance exists, you can only withdraw this balance if you have a way to regenerate the key being deleted. 3. Most importantly, you should ensure that you have a way to regenecrate the key i.e. you have the mnemonic phrase used to create the key. Without this mnemonic, the key cannot be regenerated once deleted. {% endhint %} ## Deleting Key Example In the following example, we have a key called `test` that we'd like to delete from `sagacli` Here are the details of the key indicating that it is present in `sagacli` ``` $ sagacli keys show test1 - address: saga1z0uscdcprxcun2mlnyrz5kelemmjw768sdrgz5 name: test1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+u4iLJZWZHHcRIEbme8ppbmk1jYTpZVio8anPqAIQ31"}' type: local ``` {% hint style="info" %} ***Note:*** It is a good idea to get prompted for confirmation while deleting a key. However, if you do not wish to be prompted for confirmation, simply pass the `-y` flag: {% endhint %} ``` sagacli keys delete -y ``` To delete with confirmation: ``` $ sagacli keys delete test1 Key reference will be deleted. Continue? [y/N]: y Key deleted forever (uh oh!) ``` ## Checking Deletion Here we list all existing keys in `sagacli` (default `os` keyring) to check that the key named `test1` has actually been deleted. ``` $ sagacli keys list - address: saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re name: fundkey pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A4lAzjJ4bZnZIEhYQvW+qsgg9SzwQOkOgFG+q5enEv4l"}' type: local - address: saga1tkax73wxs047nc8kaalhfc4ar6gay2sde28crx name: mykey1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A1YCpZPIzs6MXTiMAOnlEK6Cq8+JQMii9a4vUnyQ0qGs"}' type: local ``` ## Further Details To get a full list of options on the keys delete command, type ``` sagacli keys delete --help ``` # Renaming Keys ## Command Sometimes you find yourself needing to rename one or more keys stored inside one of your keystores. Existing keys managed by `sagacli` can also be renamed. To rename a key, type ``` sagacli keys rename ``` For example, to rename a key called `metamask` to `fundkey`, you would type: ``` $ sagacli keys rename metamask fundkey Key reference will be renamed from metamask to fundkey. Continue? [y/N]: y Key was successfully renamed from metamask to fundkey ``` ## Confirming Success To confirm that the key was successfully renamed, you can list all of the keys managed by `sagacli` ``` $ sagacli keys list - address: saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re name: fundkey pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A4lAzjJ4bZnZIEhYQvW+qsgg9SzwQOkOgFG+q5enEv4l"}' type: local - address: saga1tkax73wxs047nc8kaalhfc4ar6gay2sde28crx name: mykey1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A1YCpZPIzs6MXTiMAOnlEK6Cq8+JQMii9a4vUnyQ0qGs"}' type: local - address: saga1z0uscdcprxcun2mlnyrz5kelemmjw768sdrgz5 name: test1 pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+u4iLJZWZHHcRIEbme8ppbmk1jYTpZVio8anPqAIQ31"}' type: local ``` You can see that we no longer have a key named `metamask` as it has been renamed to `fundkey`. ## Further Details To get a full list of options supported by the `rename` command, type ``` sagacli keys rename --help ``` # Account Management Accounts in SAGA are used to manage your SAGA token balance and execute various transactions to fund operations on top of the SAGA Platform. The token denom for the Saga Platform is PSAGA `sagacli` enables account management functions via the `account` command. You will need an account in order to transact with the Saga Platform Chain. To view and get help on account management functions, type ``` sagacli account --help ``` You will see the following: ``` Account queries and transactions subcommands Usage: sagacli account [command] Available Commands: balance Query the balance of an account deposit-escrow Deposit amount to chainlet escrow get-billing-history Get chainlet billing history get-escrow Get amount of chainlet escrow get-tokens Get tokens from secret faucet using passphrase withdraw-escrow Withdraw amount from chainlet escrow Flags: -h, --help help for account Global Flags: --controller string controller grpc url (host:port) (default "https://controller.testnet-sp1.sagarpc.io") --from string Name of private key used to sign (default "bogdan_local") --keyring-backend string Select keyring's backend (os|file|test) (default "file") --ledger Use the connected Ledger device for signing tx -l, --loglevel string commands logging level (default "info") --network-rpc string : to tendermint rpc interface for remote chain (default "https://spc.testnet-sp1.sagarpc.io") -o, --output string output type (default "text") --platform-chain-id string The SPC network chain ID (default "spc-testnet-1") Use "sagacli account [command] --help" for more information about a command. ``` # Checking Account Balances ## View Account Balance of the Default Account If you have a default key configured for `sagacli` (see [Configuring a Default Key](/sagacli/key-management/adding-keys#configuring-a-default-key-in-sagacli) in `sagacli`), you can check its balance by typing: ``` sagacli account balance ``` This will print the balance of the account associated to the default key. Example: ``` $ sagacli account balance Amount Denom ------ ----- 999999970000 upsaga ``` ## View Account Balance of any Account To check the balance of any account on the network, just type ``` sagacli account balance --address
``` For example, to check the balance of an account associated with an example key called `fundkey`, execute the following command: ``` sagacli account balance --address saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re ``` This will print the balance (in `upsaga`) associated with this account. In this case, it prints: ``` $ sagacli account balance --address saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re Amount Denom ------ ----- 0 upsaga ``` {% hint style="info" %} You can retrieve the account number associated to a key by executing `sagacli keys show -a ` {% endhint %} Example: ``` $ sagacli keys show -a fundkey saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re ``` It is also possible to combine the two commands i.e. getting the balance and getting the account number, so you do not need to execute two commands, one to get the account number from the key, and another to get the balance associated to that account. Execute: ``` sagacli account balance --address $(sagacli keys show -a ) ``` Example: ``` $ sagacli account balance --address `sagacli keys show -a fundkey` Amount Denom ------ ----- 0 upsaga ``` # Requesting Tokens from Saga Faucet To deposit funds into your default account, use the following command. ``` sagacli account get-tokens ``` `Success! Faucet funded wallet saga1rdssl22ysxyendrkh2exw8xc7hvj8d2ju346g1. Tx: 73AC089495855F84FA29938332FBB712C358D380E0FADF6CEB8FAC2B5ECC6828` {% hint style="info" %} Each request for funds from the Saga Faucet deposits **350,000,000 `upsaga`** (**350 PSAGA**) tokens into your account. {% endhint %} If you would like to request funds from the Saga Faucet and deposit them to a different account, simply pass the `--address` flag to the get-tokens command: ``` sagacli account get-tokens --address saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re ``` Once you have successfully requested funds from the Saga Faucet, you can check your account balance to confirm you have the requested funds. For additional help on requesting funds from the Saga Faucet, type ``` sagacli account get-tokens --help ``` # Deposit Funds into Escrow `sagacli` enables you to contribute funds towards a chainlet, thereby giving you a stake in the chainlet. You can use your account functions to fund your own chainlet or any other chainlet on the SAGA network. Your funding account will be made public on the SAGA network for that Escrow. {% hint style="danger" %} **IMPORTANT:** To deposit funds into an escrow account, you will need the `chain-id` associated to the chainlet you wish to contribute towards. You will also need to have an account that has enough balance to cover your deposit. {% endhint %} To make an escrow deposit, you will execute the following command: ``` sagacli account deposit-escrow --from ``` ## Deposit Example Let us see this deposit via an example. Let's say we have a chainlet with a `chain-id` of magicwarriors\_1698795593524888-1. It was launched by a user holding the key named `ash`. Now, a user with the key `fundkey` wants to contribute some funds towards this chainlet. Once the holder of key `fundkey` makes an escrow deposit, these funds will be placed in an escrow account associated to chainlet magicwarriors\_1698795593524888-1. To make this deposit, we will execute the following command: ``` $ sagacli account deposit-escrow magicwarriors_1698795593524888-1 10000000 --from fundkey You are about to sign and broadcast a transaction, with the following configurations: * Keyname: fundkey * Keyring: file * Address: saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn * Network RPC: https://spc.sagarpc.io * Platform chain id: spc-1 * Ledger: false * Gas limit: 250000 * Message Detail: creator:"saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn" amount:"10000000.0000upsaga" chainId:"magicwarriors_1698795593524888-1" Do you want to proceed? (y/N): y 2023-10-31T17:11:36-07:00 INF tx broadcasted to the remote node code=0 gas_used=0 gas_wanted=0 hash=4F60AFB3F923AB9AAD56D71B65651DBB5FC7C438777DE54D312ACD35CDF1C49E ChainId TotalBalance Funder FunderDeposit ------- ------------ ------ ------------- magicwarriors_1698795593524888-1 290000000upsaga saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn 10000000.0000upsaga magicwarriors_1698795593524888-1 290000000upsaga saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 280000000.0000upsaga ``` As you can see, the deposit was successfully made and the output above shows the balance breakdown of funds held in escrow for chainlet`magicwarriors_1679599719-1`. ## Further Deposit Details For further details on making deposits to the escrow, run ``` sagacli account deposit-escrow --help ``` # Withdraw Funds from Escrow To withdraw funds deposited previously to an escrow account associated to a chainlet, you will need the `chain-id` associated to the chainlet. {% hint style="info" %} Please note that unlike escrow deposits, that allow you to specify a specific amount, withdrawing of funds from an escrow account withdraws all the funds you deposited. This is an all-or-nothing operation. It will only allow you to withdraw funds that have been deposited from an account that you own or control. {% endhint %} To withdraw funds from an escrow account, use ``` sagacli account withdraw-escrow \ --from ``` ## Withdrawal Example Let us step through the withdrawal with the help of an example. Let us assume that we have a chainlet with a `chain-id` of `magicwarriors_1698795593524888-1` Prior to making the withdrawal, this chainlet had access to funds from two separate accounts i.e. one belonging to the chainlet owner, and the other belonging to a different user with a key named `fundkey`. ``` $ sagacli account get-escrow magicwarriors_1698795593524888-1 ChainId TotalBalance Funder FunderDeposit ------- ------------ ------ ------------- magicwarriors_1698795593524888-1 290000000upsaga saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn 10000000.0000upsaga magicwarriors_1698795593524888-1 290000000upsaga saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 280000000.0000upsaga ``` Now, the user with the key `fundkey` wishes to withdraw his/her contribution of`10,000,000,000` `upsaga` tokens from the chainlet's escrow. ### Checking the Account Balance Pre-Withdrawal Before we process this withdrawal, let us take a look at the account balance associated with the key `fundkey`: ``` $ sagacli account balance --address saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn Amount Denom ------ ----- 8000000000 upsaga ``` Account `saga14hyhswxf0shnpzup406yvjejmfsrjnvzq897re` (associated with key `fundkey`) has a balance of `8,000,000,000 upsaga` tokens. ### Process Escrow Withdrawal Now, we will process an escrow withdrawal from chainlet `magicwarriors_1698795593524888-1` To do so, we will execute a `withdraw-escrow` transaction in the following manner: ``` $ sagacli account withdraw-escrow magicwarriors_1698795593524888-1 --from saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn You are about to sign and broadcast a transaction, with the following configurations: * Keyname: fundkey * Keyring: file * Address: saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn * Network RPC: https://spc.sagarpc.io * Platform chain id: spc-1 * Ledger: false * Gas limit: 250000 * Message Detail: creator:"saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn" chainId:"magicwarriors_1698795593524888-1" Do you want to proceed? (y/N): y 2023-03-23T15:13:23-05:00 INF tx broadcasted to the remote node code=0 gas_used=69449 gas_wanted=200000 hash=DFA654213E4402D5D6B716847D83CF0F851CBF0E1891F51638D57A8386B9B67B ChainId TotalBalance Funder FunderDeposit ------- ------------ ------ ------------- magicwarriors_1698795593524888-1 280000000upsaga saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 280000000.0000upsaga ``` As can be seen from the output above, the withdrawal returned the funds to the account with the key `fundkey` whose account address is `saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn`. ### Checking the Account Post-Withdrawal We can also check whether the account address `saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn` received the funds back and that its account balance was updated: ``` $ sagacli account balance --address saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn Amount Denom ------ ----- 8010000000 upsaga ``` Yes, the account `saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn` received all of the funds (`10,000,000,000upsaga` tokens) from the escrow, and its balance was correctly updated. {% hint style="danger" %} **IMPORTANT:** Withdrawing all of the funds in a chainlet escrow account, on behalf of all funders, will change the escrow account balance to zero which will instruct the SAGA Platform to stop running the chainlet and its related RPC and Chainlet Explorer infrastructure and services. In order to keep your chainlet live, make sure the chainlet escrow account has always enough funds to pay for the epoch fees. {% endhint %} ## Further Details For further details and options on escrow withdrawal, please see ``` sagacli account withdraw-escrow --help ``` # View Escrow Account Information To view escrow account details, such as addresses of funders as well as the amount of funding provided, you need to execute the `get-escrow` command. You will need the `chain-id` of the chainlet for which you wish to get escrow account details. ``` sagacli account get-escrow ``` ### View Escrow Example As an example, we will get the escrow details associated with chainlet `magicwarriors_1679599719-1`: ``` $ sagacli account get-escrow magicwarriors_1679599719-1 ChainId TotalBalance Funder FunderDeposit ------- ------------ ------ ------------- magicwarriors_1698795593524888-1 280000000upsaga saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 280000000.0000upsaga ``` Here, in the output, you can see the total balance available in escrow (these funds are available to the chainlet) as long as the deposit made by each funder. ### Further Details For more details on the `get-escrow` command, type ``` sagacli account get-escrow --help ``` # Working with Chainlet The Pegasus Incentivized Testnet is the developer’s portal into the Saga ecosystem. Like most smart contracting platforms, the developer deploys their compiled smart contract binary onto the Saga testnet. Once initialized, the Saga validators automatically provision a Saga dedicated chain, or `chainlet`, containing the smart contract. A `chainlet` is literally where the rubber meets the road! It is your own dedicated blockchain with its own validator set secured by the SAGA platform main validator set. It provides dedicated blockspace for your `web3` application. {% hint style="info" %} There can be several different *types* of chainlets i.e. a pre-packaged blockchain encapsulating some custom functionality on top of an EVM. In the near future SAGA Platform will support many different *types* of chainlets that would deploy other execution environments like CosmWasm, Solana, Javascript, etc {% endhint %} Pegasus makes its own chainlet type available to developers called `SagaOS`. It runs an EVM compatible blockchain leveraging [Cosmos SDK](https://v1.cosmos.network/sdk). With **sagacli** you can view the types of chainlets that can be launched, launch chainlets, view all of the chainlets you have launched as well as get detailed information on each chainlet. Additionally, each chainlet comes equipped with its own RPC endpoints to integrate with your wallet or web3 application, and a block explorer that you can use in a web browser and search for transactions, view contents of blocks and other details pertaining to the activity and state of your chainlet. # View Listing of Chainlet Types ## Command You can view the chainlet types by using the following command: ``` sagacli chainlet list-types ``` ## View Listing Example ``` $ sagacli chainlet list-types DisplayName Description Creator Version SetupCost EpochCost ----------- ----------- ------- ------- --------- --------- SagaOS SagaOS Chainlet Stack saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 0.5.17 10000000upsaga 10000000upsaga/day ``` ## Chainlet Type Versions Every chainlet type also has an associated version. A version ultimately points to a different image of the chainlet type and encapsulates a set of features available to a launched chainlet. Creating a different version of the chainlet type can be necessitated by many reasons, such as security patching, adding new functionality, removing redundant functionality etc. ## Further Details For additional details and options to list chainlet types, please refer to ``` sagacli chainlet list-types --help ``` # Launch your Chainlet on Testnet **Prerequisites**: [Download and install SagaCLI and request tokens](/sagacli/quickstart-guide/testnet-quickstart-guide). To launch a chainlet, you will need the following: {% hint style="info" %} To launch a chainlet, you will need the following: 1. [Chainlet type](/sagacli/working-with-chainlet/view-listing-of-chainlet-types) 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. {% endhint %} ## 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 ``` {% hint style="info" %} 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 {% endhint %} {% hint style="warning" %} 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](/sagacli/working-with-chainlet/chainlet-billing) for details {% endhint %} 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: > > 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 launchenables access to the chainlet launch capability of sagacli
SagaOSindicates the chainlet type we are launching
0.5.17indicates 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-enablethis 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-accountthis 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.
--feesThe fee to pay for this chainlet launch transaction
{% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} **IMPORTANT**: The above chainlet has been launched by the address associated with the default key (refer to [Configuring a Default Key in `sagacli`](/sagacli/key-management/adding-keys#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 ` flag to the `sagacli chainlet launch` command. Example: `sagacli chainlet launch --from mykey2` {% endhint %} ### Chainlet Launch Options Chainlets can be launched using some powerful tools and options. They are explained in detail in this section. {% hint style="info" %} Note that all flags are passed prefixed with double-dashs e.g. `--denom` for passing the `denom` flag. {% endhint %} {% hint style="danger" %} 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. {% endhint %}
Option FlagDescription
denomCoin denomination for the chainlet e.g. mytoken.This parameter is optional.
evm-chain-idA 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-accountAn account that will accumulate all of the returned transaction fees on the chainlet. This parameter is optional.
feesFees to pay along with the transaction
fixed-base-feeA 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.
gasGas 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-limitChainlet transactions gas limit (default 10000000). This parameter is optional
genesis-accountAn 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.
maintainerMaintainers of the chainlet (you can repeat this flag multiple times). The launcher is a maintaner by default. This is an optional parameter.
network-versionThe chainlet's network version (defaults to 1). This parameter is optional
#### Example: Launching a Chainlet using the `base-gas-fee` flag {% hint style="success" %} This is a new feature added to Saga Realms in the Pegasus Phase I release. {% endhint %} As described above, you can launch a new chainlet with a base gas fee flag set. {% hint style="warning" %} Using this setting may open up your chainlet to spam attacks, especially if you set it to 0 {% endhint %} 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: > 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 {% hint style="success" %} This is a new feature added to Saga Realms in the Pegasus Phase I release. {% endhint %} 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: > 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. ```bash 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](https://medium.com/sagaxyz/stack-exploder-unblocking-web3-products-with-costless-transactions-387b9f03b7c5) * [Stack Exploder: Implementing Costless Transactions Using Recycled Gas Tokens](https://medium.com/sagaxyz/stack-exploder-implementing-costless-transactions-using-recycled-gas-tokens-ee51548b390e) ## 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](/sagacli/getting-access). ## Launching Chainlets with a Different Currency Symbol {% hint style="warning" %} **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. {% endhint %} Example: ``` sagacli chainlet launch SagaOS 0.5.17 mychain --dac-enable \ --genesis-account :1000000 --gas-limit 100000000 --denom ``` 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 ``` # Launch your Chainlet on Mainnet **Prerequisites**: [Download and install SagaCLI and request tokens](/sagacli/quickstart-guide/mainnet-quickstart-guide). To launch a chainlet, you will need the following: {% hint style="info" %} To launch a chainlet, you will need the following: 1. [Chainlet type](/sagacli/working-with-chainlet/view-listing-of-chainlet-types) 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. {% endhint %} ## 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 ``` {% hint style="info" %} 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 {% endhint %} {% hint style="warning" %} 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](/sagacli/working-with-chainlet/chainlet-billing) for details {% endhint %} 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.sagarpc.io * Platform chain id: spc-1 * Ledger: false * Message Detail: creator:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju" maintainers:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju" chainletStackName:"SagaOS" chainletStackVersion:"0.5.17" chainId:"magicwarriors_1698442321102101-1" chainletName:"magicwarriors" params: > > 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 launchenables access to the chainlet launch capability of sagacli
SagaOSindicates the chainlet type we are launching
0.5.17indicates 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-enablethis 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-accountthis 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.
--feesThe fee to pay for this chainlet launch transaction
{% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} **IMPORTANT**: The above chainlet has been launched by the address associated with the default key (refer to [Configuring a Default Key in `sagacli`](/sagacli/key-management/adding-keys#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 ` flag to the `sagacli chainlet launch` command. Example: `sagacli chainlet launch --from mykey2` {% endhint %} ### Chainlet Launch Options Chainlets can be launched using some powerful tools and options. They are explained in detail in this section. {% hint style="info" %} Note that all flags are passed prefixed with double-dashs e.g. `--denom` for passing the `denom` flag. {% endhint %} {% hint style="danger" %} 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. {% endhint %}
Option FlagDescription
denomCoin denomination for the chainlet e.g. mytoken.This parameter is optional.
evm-chain-idA 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-accountAn account that will accumulate all of the returned transaction fees on the chainlet. This parameter is optional.
feesFees to pay along with the transaction
fixed-base-feeA 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.
gasGas 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-limitChainlet transactions gas limit (default 10000000). This parameter is optional
genesis-accountAn 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.
maintainerMaintainers of the chainlet (you can repeat this flag multiple times). The launcher is a maintaner by default. This is an optional parameter.
network-versionThe chainlet's network version (defaults to 1). This parameter is optional
#### Example: Launching a Chainlet using the `base-gas-fee` flag {% hint style="success" %} This is a new feature added to Saga Realms in the Pegasus Phase I release. {% endhint %} As described above, you can launch a new chainlet with a base gas fee flag set. {% hint style="warning" %} Using this setting may open up your chainlet to spam attacks, especially if you set it to 0 {% endhint %} 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.sagarpc.io * Platform chain id: spc-1 * Ledger: false * Gas limit: 500000 * Message Detail: creator:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3" maintainers:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3" chainletStackName:"SagaOS" chainletStackVersion:"0.5.17" chainId:"freedomchain_1712762003250914-1" chainletName:"freedomchain" params: > 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 {% hint style="success" %} This is a new feature added to Saga Realms in the Pegasus Phase I release. {% endhint %} 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.sagarpc.io * Platform chain id: spc-1 * Ledger: false * Gas limit: 500000 * Message Detail: creator:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3" maintainers:"saga1qu6snpww3t6ztvnszezfv0xjq709v35vw9lgv3" chainletStackName:"SagaOS" chainletStackVersion:"0.5.17" chainId:"omegachain_1712771388991266-1" chainletName:"omegachain" params: > 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. ```bash 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.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](https://medium.com/sagaxyz/stack-exploder-unblocking-web3-products-with-costless-transactions-387b9f03b7c5) * [Stack Exploder: Implementing Costless Transactions Using Recycled Gas Tokens](https://medium.com/sagaxyz/stack-exploder-implementing-costless-transactions-using-recycled-gas-tokens-ee51548b390e) ## 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](/sagacli/getting-access). ## Launching Chainlets with a Different Currency Symbol {% hint style="warning" %} **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. {% endhint %} Example: ``` sagacli chainlet launch SagaOS 0.5.17 mychain --dac-enable \ --genesis-account :1000000 --gas-limit 100000000 --denom ``` 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 ``` # Get Chainlet Information You can get detailed information about a specific chainlet using the `chainlet get` command: ``` sagacli chainlet get ``` ### Get Chainlet Information Example 
sagacli chainlet get jargames_1679785243507504-1
ChainId                           Name           StackName     StackVersion     Launcher                                        Mantainers                                        CurrencySymbol     Status            
-------                           ----           ---------     ------------     --------                                        ----------                                        --------------     ------            
jargames_1679785243507504-1       jargames       SagaOS        0.5.17           saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3     [saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3]     jar                STATUS_ONLINE
In the above output, you can see details like * Chain ID of the chainlet * Name of the chainlet * The chainlet type aka `StackName` * The version of the chainlet type aka `StackVersion` * The launcher (owner) of the chainlet * The currency symbol i.e. token symbol aka `denom` associated with the chainlet * The status of the chainlet. Possible values are `STATUS_ONLINE` (chainlet is up and running) and `STATUS_OFFLINE` (chainlet has been stopped) ### Further Details For further details on using the `chainlet get` command, refer to ``` sagacli chainlet get --help ``` # View Listing of Chainlets Launched You can view a listing of all chainlets that have been launched by using the `list` command: `sagacli chainlet list` This command lists all of the chainlets launched by the account associated with the default key. ``` $ sagacli chainlet list ChainId Name StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- tetris_1681169675474000-1 tetris SagaOS 0.5.17 Online 280psaga ``` To view chainlets launched by another address, you can use: ``` sagacli chainlet list --address ``` ### View Listing Example For example, to view chainlets launched by the address associated with key `mykey1`, we would use ``` $ sagacli chainlet list --address saga1tkax73wxs047nc8kaalhfc4ar6gay2sde28crx ChainId Name StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- pacman_1681169675474000-1 pacman SagaOS 0.5.17 Online 280psaga ``` In the above output, we can see that the address associated with the key `mykey1` has not launched any chainlets. ### Further Details For more details on how to use the `list` command, refer to ``` sagacli chainlet list --help ``` # Chainlet APIs & BlockExplorer Every chainlet that is launched also makes additional resources available using which you can interact with the chainlet. Currently, `sagacli` provides the following types of endpoints: 1. **Websocket endpoint** - you can send websocket requests and subscribe to channels using the websockets endpoint 2. **BlockExplorer** - Paste the explorer endpoint URL in a web browser and you should be able to see a block explorer connected to your chainlet. This can be used for searcing for, and viewing, transactions, seeing commit data, blocks info, and more. 3. **JSON RPC** endpoint - use this endpoint to make `jsonrpc` calls to your chainlet The APIs can be viewed using the `chainlet apis` command: ``` sagacli chainlet apis ``` ## API Example (Testnet) ```bash $ sagacli chainlet apis chainlet_1698372536493619-1 Name Endpoint Status ---- -------- ------ explorer chainlet-1698372536493619-1.testnet.sagaexplorer.io Available ws chainlet-1698372536493619-1.ws.testnet.sagarpc.io Available jsonrpc chainlet-1698372536493619-1.jsonrpc.testnet.sagarpc.io Available ``` ## API Example (Mainnet) ```bash $ sagacli chainlet apis chainlet_1698372536493619-1 Name Endpoint Status ---- -------- ------ explorer chainlet-1698372536493619-1.sagaexplorer.io Available ws chainlet-1698372536493619-1.ws.sagarpc.io Available jsonrpc chainlet-1698372536493619-1.jsonrpc.sagarpc.io Available ``` {% hint style="info" %} The apis command will list the service names and endpoints that allow you to connect to your chainlet JsonRPC, WS or BlockExplorer. The status value will show if the service is available or is still being provisioned. {% endhint %} ## Further Details For further details and options on using the `chainlet apis` command, refer to ``` sagacli chainlet apis --help ``` # Configuring Metamask Network This page includes instructions on how to setup your chainlet network information in your Metamask wallet As we saw in the previous page, in order to optain the chainlet network RPC connection details, you will have to run the following command: ``` sagacli chainlet apis ``` ## API Example (Testnet) ``` $ sagacli chainlet apis chainlet_1698372536493619-1 Name Endpoint Status ---- -------- ------ explorer chainlet-1698372536493619-1.testnet.sagaexplorer.io Available ws chainlet-1698372536493619-1.ws.testnet.sagarpc.io Available jsonrpc chainlet-1698372536493619-1.jsonrpc.testnet.sagarpc.io Available ``` ## API Example (Mainnet) ```bash $ sagacli chainlet apis chainlet_1698372536493619-1 Name Endpoint Status ---- -------- ------ explorer chainlet-1698372536493619-1.sagaexplorer.io Available ws chainlet-1698372536493619-1.ws.sagarpc.io Available jsonrpc chainlet-1698372536493619-1.jsonrpc.sagarpc.io Available ``` We can see in the above CLI output the jsonrpc and explorer endpoints that we will need to be able to configure our chainlet network in Metamask. {% hint style="info" %} **Note:** make sure the status for all of the endpoints is "Available", otherwise you will risk running into issues with using them in your metamask wallet config. {% endhint %} ## One-click Metamask Network Setup The fastest way to configure your chainlet network settings into your metamask browser plugin is by visiting your chainlet's dedicated block explorer page and clicking on the Add \ link present on the footer menus. You can also see how this looks like in the image included below:
## Configuring Metamask Network Manually In order to do so, we will need to navigate to Metamask -> Settings -> Networks -> Add Network The settings screen will look something like this:
From here, click on "Add a network manually" and type in the following settings in the required fields: * **Network Name:** Pacman Chainlet (or you can chose a different name for this network) * **New RPC URL**: This will be your chainlet's jsonrpc endpoint from the chainlet output above * ``` https://chainlet-1698372536493619-1.jsonrpc.sagarpc.io ``` * **Chain ID**: Here you need to input the middle **numerical** part of the chainid listed in the SagaCLI * ``` 1698372536493619 ``` * **Currency Symbol**: This is your chainlet currency symbol. (You can get that also by calling the *sagacli chainlet get* \ * 
sagacli chainlet get chainlet-1698372536493619-1
  ChainId                           Name           StackName     StackVersion     Launcher                                        Mantainers                                        CurrencySymbol     Status            
  -------                           ----           ---------     ------------     --------                                        ----------                                        --------------     ------            
  chainlet-1698372536493619-1       pacman         SagaOS        0.5.17           saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3     [saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3]     pac                STATUS_ONLINE
* **Block Explorer URL** * ``` chainlet-1698372536493619-1.sagaexplorer.io ``` Everything together will look **SIMILAR** with what you see in the following image below:
# Update Chainlet Version It may happen that you will need to update the chainlet stack version to include a security patch or a new feature or for any other reason. You can update a chainlet's version by using the `chainlet update` command. Here is an example: ``` sagacli chainlet update ``` ## Available Versions To view available versions for a chainlet type, simply use the `sagacli chainlet list-types` command: ``` $ sagacli chainlet list-types DisplayName Description Creator Version SetupCost EpochCost ----------- ----------- ------- ------- --------- --------- SagaOS SagaOS Chainlet Stack saga17gk4chqd0lrkyamrxdmu62czmu0dpnemmxlymn 0.5.16 10000000upsaga 10000000upsaga/day SagaOS SagaOS Chainlet Stack saga1u2a8ktctqhpx655ysw7ru27t6hqt9wlq4fn5ca 0.5.17 10000000upsaga 10000000upsaga/day ``` We can see that we have a newer version of the chainlet type `sagaevm`. ## Update Example To update to this newer version called "SagaEVM Chainlet Latest", we would use the following command: ``` $ sagacli chainlet update jargames_1679785243507504-1 1.1 You are about to sign and broadcast a transaction, with the following configurations: * Keyname: shan * Keyring: os * Address: saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3 * Network RPC: https://spc.sagarpc.io * Platform chain id: spc-1 * Ledger: false * Message Detail: sender:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3" chainId:"jargames_1679785243507504-1" maintainers:"saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3" chainletStackName:"SagaOS" chainletStackVersion:"0.5.17" chainletName:"jargames" params: > Do you want to proceed? (y/N): y 2023-03-25T19:48:00-05:00 INF tx broadcasted to the remote node code=0 gas_used=62507 gas_wanted=200000 hash=B20F1BDDDCA619869F385B58977F470179C7C92EC784EE30310E1EAC739C4E90 ``` We can see that our request was successfully submitted. Now we can check the status of our chainlet by using the `chainlet list` or `chainlet get ` command: ``` $ sagacli chainlet list ChainId Name StackName StackVersion Status EscrowBalance ------- ---- --------- ------------ ------ ------------- jargames_1679785243507504-1 jargames SagaOS 0.5.17 Pending 28000000upsaga ``` As can be seen from the output, the chainlet's version has been upgraded to 1.1 and it is currently being upgraded (status = Pending) ## Further Details For further details and additional options on using the `chainlet update` command, refer to ``` sagacli chainlet update --help ``` # Chainlet Billing ## Chainlet Billing Overview Chainlets are billed at a pre-determined interval depending on the type of chainlet it is and the duration of each epoch. Typically, a chainlet would be billed each day for the resources it consumes. {% hint style="warning" %} As each billing cycle is processed, the funds available to the chainlet inside the escrow account get depleted. Make sure you keep your escrow account funded to prevent your chainlet from being shutdown. {% endhint %} You can view how often a chainlet gets billed, and the corresponding billing amount, by [looking up the type of chainlet](/sagacli/working-with-chainlet/view-listing-of-chainlets-launched#view-listing-example) you are running. As an example, if your chainlet type is `SagaOS`, you can view the billing details by using `sagacli` ``` $ sagacli chainlet list-types DisplayName Description Creator Version SetupCost EpochCost ----------- ----------- ------- ------- --------- --------- SagaOS SagaOS Chainlet Stack saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 0.5.17 10000000upsaga 10000000upsaga/day ``` As you can see (slide to the right of the above code block), we have two separate costs associated with this chainlet type: a setup cost and an epoch cost. {% hint style="info" %} A chainlet setup cost is a 1-time fee charged when the chainlet is initially launched. An epoch cost is the amount billed at the end of each epoch. For SagaOS, the epoch is set to 1 day {% endhint %} As can be seen in our example listing above, we have a SetupCost of 10`psaga` (1 `psaga` = 1,000,000 `upsaga`) which is charged when the chainlet is launched. We also have an EpochCost of 10`psaga` which is the amount billed to the chainlet each day. All chainlets launched are charged a setup fee and a 30-day deposit of the epoch cost, which is then decremented as the chainlet gets billed each epoch. For our example above, our chainlet launch cost would be (SetupFee 10`psaga)` + (30 days \* EpochCost 10`psaga/day`) = 310`psaga`. This amount of **310`psaga`** is charged to the chainlet launcher's wallet at chainlet launch, and deposited into the escrow account associated with the chainlet. As the chainlet is billed each epoch, this [escrow account](/sagacli/account-management/view-escrow-account-information) gets depleted. {% hint style="info" %} Ensure you have sufficient funds in the wallet launching the chainlet Add funds to your chainlet at any time by [depositing funds into the chainlet's escrow](/sagacli/account-management/deposit-funds-into-escrow) {% endhint %} ## View Billing History As a user, you can view the billing history associated with any chainlet you have launched or contributed funds toward. To view the billing history of a chainlet, simply type: ``` sagacli account get-billing-history ``` ## Billing History Example For example, to view the billing history of a chainlet with a `chain-id` of `magicwarriors_1679599719-1`: ``` $ sagacli account get-billing-history magicwarriors_1698795593524888-1 ChainletId ChainletName ChainletOwner BilledAmount EpochIdentifier EpochNumber EpochStartTime ---------- ------------ ------------- ------------ --------------- ----------- -------------- magicwarriors_1698795593524888-1 magicwarriors saga1yuvju0cztlahsf6f37z9j83vwyzgj6pzhx090f 20000000upsaga day 1 2023-10-31T23:22:01Z ``` This output shows you the chainlet information along with the amount billed and the time the chainlet was billed. This is a paginated query. Then, if you need to navigate through the chainlet billing history you have to change the value of `--page` and `--limit` flags. ## Export all billing history If for some reason you need to export all chainlet billing history in a single step, you can da that as well, just specifying the `--csv-file` flag: ``` $ sagacli account get-billing-history magicwarriors_1698795593524888-1 --csv-file /tmp/billing_history.csv ``` The csv file specified now contains all the billing history of `magicwarriors_1679599719-1` chainlet recorded so far. ## Further Details To get further details and options associated with getting billing history, please refer to ``` sagacli account get-billing-history --help ``` # Restarting a Stopped Chainlet As your chainlet runs, it is billed periodically. See the section on [chainlet billing](/sagacli/working-with-chainlet/chainlet-billing) to get an understanding of how chainlets are billed, view billing history, export billing history, and other features associated with billing of chainlets. Should your chainlet run out of funds, it will be halted and it's [status](/sagacli/working-with-chainlet/get-chainlet-information) will show offline. Each chainlet launched is associated with an [escrow account](/sagacli/account-management/view-escrow-account-information) into which funds can be added or withdrawn by anyone, at any time. Chainlets are billed by depleting the funds deposited into this escrow account. If your chainlet displays a status of STATUS\_OFFLINE and your chainlet's escrow account has been depleted, your chainlet can be restarted by [adding funds to the chainlet's escrow account](/sagacli/account-management/deposit-funds-into-escrow). {% hint style="warning" %} If your chainlet has been stopped due to lack of funds, you will need to [deposit 30 days](/sagacli/working-with-chainlet/chainlet-billing) worth of funds in the chainlet's escrow account to enable it to be restarted. {% endhint %} Once you deposit the necessary funds in the chainlet's escrow account, your chainlet should restart and show a status of `STATUS_ONLINE`. If you have issues restarting your chainlet, [please contact us](/get-help-and-support) for further support. # Configuring sagacli - A Deep Dive `sagacli` is a powerful CLI tool that is intended to offer end-to-end management of your private keys, accounts and chainlets. {% hint style="warning" %} It is imperative that `sagacli` be configured correctly in order for you to get the most out of the tool, and avoid unnecessary errors. {% endhint %} To view the current config, type: ``` sagacli config ``` The table below provides an in-depth explanation of each configuration setting.
SettingDescriptionExample ValuesDefault Value
loglevelThis setting determines the verbosity of logs produced. Possible values are debug, trace, info (default), error and criticaltraceinfo
controllerController accepts gRPC requests from sagacli and acts as the gateway for processing commands. Note: This is a critical setting and must be set correctly in order for sagacli to function properlycontroller.cassio-prod-sp1.sp1.sagarpc.io:19090https://controller.sp1.sagarpc.io
outputThis controls the formatting of output from sagacli commands. Possible values are text and jsonjsontext
keyring-backendThis setting indicates the type of keyring sagacli will use for storing private keystestfile
network-rpcThis setting specifies the endpoint for connecting to the Saga Platform Chain, which serves as the system of record for chainlets launched, as well as their current status. Note: This is a critical setting and must be set correctly in order for sagacli to function properlytcp://spc.cassio-prod-sp1.sp1.sagarpc.io:26657https://spc.sp1.sagarpc.io
fromThis setting specifies the key to be used as the default key when signing transactions. You do not need to have this set in order to be able to use sagacli and having this set is a convenience featuremykey1none
platform-chain-idThis setting specifies the chain-id of the Saga Platform Chain. Note: This is a critical setting and must be set correctly in order for sagacli to function properlyspc-testnet-1spc-testnet-1
denomThis setting specifies the token denomination symbol being used by the Saga Platform Chain. It is best to leave this to the default valuestaketsaga
broadcast-mode

This controls the submission of transactions to the Saga Platform Chain and whether sagacli should wait for the transaction to be checked and committed in a block before the command returns. Possible values are sync and async.

IMPORTANT: It is not recommended that this value be changed. If you do have a use-case for changing the default value, please contact the Saga team before making any changes

syncsync
ledgerThis setting enables the use of a connected ledger device for signing transactions. If you have an HD wallet or other such hardware device used to store your private keys, you can use this setting to force each transaction to be signed via the ledger devicetruefalse
# Searching for Transactions You can use the `sagacli tx` command to look for a specific transaction and its associated details. {% hint style="info" %} While we encourage the use of `sagacli`, you can get a better experience searching for transactions, and viewing other details, using the [block explorer](/sagacli/working-with-chainlet/chainlet-apis-and-blockexplorer). {% endhint %} To use this command: ``` sagacli tx search ``` Example: ``` $ sagacli tx search B20F1BDDDCA619869F385B58977F470179C7C92EC784EE30310E1EAC739C4E90 code: 0 codespace: "" data: 12310A2F2F7361676178797A2E7370632E636861696E6C65742E4D7367557064617465436861696E6C6574526573706F6E7365 events: - attributes: - index: true key: ZmVl value: null - index: true key: ZmVlX3BheWVy value: c2FnYTFyZHNzbDIyeXN4eWVuZHJraDJleHc5em03aHZqOGQyanUzNDZnMw== type: tx - attributes: - index: true key: YWNjX3NlcQ== value: c2FnYTFyZHNzbDIyeXN4eWVuZHJraDJleHc5em03aHZqOGQyanUzNDZnMy81 type: tx - attributes: - index: true key: c2lnbmF0dXJl value: MVVsWmZ5THUrODRWNWdQZkR0TXRNczlKVTZIbDVVY003ZjJoVlpPb256SUErb2NETXZIcW9zMU15RituNlpOdXlRZm1JMzYxeWNWY1pXc2VhangxQ3c9PQ== type: tx - attributes: - index: true key: YWN0aW9u value: L3NhZ2F4eXouc3BjLmNoYWlubGV0Lk1zZ1VwZGF0ZUNoYWlubGV0 type: message - attributes: - index: true key: Y2hhaW5JZA== value: ImNhc3Npb3NoYW4i - index: true key: c3RhY2tWZXJzaW9u value: IjIuMCI= type: sagaxyz.spc.chainlet.EventUpdateChainlet gas_used: "62507" gas_wanted: "200000" height: "2017" info: "" logs: - events: - attributes: - key: action value: /sagaxyz.spc.chainlet.MsgUpdateChainlet type: message - attributes: - key: chainId value: '"cassioshan"' - key: stackVersion value: '"2.0"' type: sagaxyz.spc.chainlet.EventUpdateChainlet log: "" msg_index: 0 raw_log: '[{"msg_index":0,"events":[{"type":"message","attributes":[{"key":"action","value":"/sagaxyz.spc.chainlet.MsgUpdateChainlet"}]},{"type":"sagaxyz.spc.chainlet.EventUpdateChainlet","attributes":[{"key":"chainId","value":"\"cassioshan\""},{"key":"stackVersion","value":"\"2.0\""}]}]}]' timestamp: "2023-03-26T00:47:54Z" tx: '@type': /cosmos.tx.v1beta1.Tx auth_info: fee: amount: [] gas_limit: "200000" granter: "" payer: "" signer_infos: - mode_info: single: mode: SIGN_MODE_DIRECT public_key: '@type': /cosmos.crypto.secp256k1.PubKey key: AwBIByzfDASI/ozaUwg1TM1p50ZfoAIy3gMKrqSey24i sequence: "5" tip: null body: extension_options: [] memo: "" messages: - '@type': /sagaxyz.spc.chainlet.MsgUpdateChainlet chainId: cassioshan_1679785243507504-1 chainletName: cassioshan chainletStackName: sagaos chainletStackVersion: "2.0" maintainers: - saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3 params: createEmptyBlocks: false dacEnable: false denom: "" gasLimit: "0" genAcctBalances: "" sender: saga1rdssl22ysxyendrkh2exw9zm7hvj8d2ju346g3 non_critical_extension_options: [] timeout_height: "0" signatures: - 1UlZfyLu+84V5gPfDtMtMs9JU6Hl5UcM7f2hVZOonzIA+ocDMvHqos1MyF+n6ZNuyQfmI361ycVcZWseajx1Cw== txhash: B20F1BDDDCA619869F385B58977F470179C7C92EC784EE30310E1EAC739C4E90 ``` Looking at the output above, you can get all the relevant details for any given transaction. The very first line of the output indicates the return code, with a value of 0 indicating that the transaction was successful. For further details on using the `tx` command, refer to: ``` sagacli tx --help ``` # Get Help & Support Support is available via our Discord server. We welcome you to join the Saga Discord Server - All technical/dev support related questions can be posted in the **innovator-dev-support** channel.