What's new with Sage
And what to expect in the future
A new Sage release is out, but it’s been a while since the last one so I figured I should explain what’s been worked on over the past couple months. You may be surprised to hear that over 25,000 lines of code (which is roughly 50% of the codebase at the time of writing this) have been affected between the last version and now!
I want to give a huge thanks to Don Kackman for all of the help with the project and for making it possible to get this release across the finish line.
You can download binaries for MacOS, Windows, and Linux on GitHub or download the app for desktop, Android, or iOS on the Sage website (although the mobile versions need to go through their respective approval processes first).
The biggest two changes are architectural, but a lot of features and bug fixes have been slipped in along the way.
Action System
We’ve fully transitioned from manually constructing transactions to using the new Action System introduced in the Wallet SDK. The action system (not to be confused with Yakuhito’s new Action Layer which itself will power many awesome primitives) is a major simplification to how coins can be spent on the Chia blockchain. If you’re interested in a high level explanation of how actions work, I’ve attached my presentation (in fact, the first formal presentation I’ve done before) from Chia Toronto.
Database Redesign
The wallet’s entire database schema has been rewritten from the ground up. There were a lot of motivators for this change:
Since the database had been designed alongside the wallet, a lot of outdated or less informed decisions went into it. This led to unnecessary complexity, bloat, and tech debt (such as having to copy data to multiple redundant places in the database).
It was hard to add new features to the wallet, such as non-custody p2 puzzles (including clawbacks) and revocable CATs. Adding option contracts to such a database schema (which we plan to do later) would have been a nightmare.
A lot of information that is shared between each type of asset (XCH, CATs, NFTs, DIDs) was instead sporadically stored in various places. We’ve now consolidated it into a single assets table, for the most part.
Because natural keys (coin ids, puzzle hashes, etc) were the primary key in the database, queries with lots of joins became slow. This has been fixed by using surrogate keys (auto incrementing numeric ids) instead.
Revocable CATs
A new Revocable CAT primitive has been introduced, and will first be used by Permuto Capital. This is an add-on to the CAT standard that enables the issuer to revoke coins if needed. The S-1 filing details why and when this might happen, but in summary it’s due to legal compliance reasons. Almost all CATs that are not securities will continue to not be revocable (ie only the current holder has the right to spend the coin).
The Chia Cloud Wallet supports Revocable CATs already, so Sage now supports the standard as well for feature parity. However, due to the potential security risks of someone sending you a revocable CAT and misleading you into thinking it’s not revocable, there are various warnings and safeguards in place to make sure users are aware of which type of CAT they are looking at.
Clawback v2
A preliminary implementation of Clawback v2 has been implemented in Sage. This might not be the clawback standard you are used to from the Chia reference wallet. Essentially, rather than the sender being able to claw back forever, they have a fixed time at which the ability to claw back expires (the same instant at which the recipient can spend the coins). This also means that the recipient no longer has to “claim” the coin by sending it to themselves.
While this new clawback standard can provide a better user experience, it comes with a couple drawbacks:
If you forget to claw back in time before the expiration, you will not be able to. Make sure you set your clawback expiration time far enough into the future that you have enough time to react (and don’t forget)!
If you send a clawback coin to a recipient that doesn’t support the Clawback v2 standard (ie any wallet other than Sage at the time of writing this, but exchange wallets are known to not support clawbacks), you will have until the expiration to claw the funds back, since they won’t be able to receive it naturally. If you forget to do this, however, there is an additional way to spend the coins to “push through” the coin to the receiver. So the coins aren’t lost even if the receiver doesn’t support Clawback v2, it’s just more work to get it through to them.
The original clawback standard remains unsupported at this time, however it may be implemented in the future depending on demand for it.
Resyncing
We all wish it weren’t the case, but unfortunately the wallet will sometimes fall out of sync with the current state of your wallet on the blockchain. Although improvements are constantly being made to Sage to reduce the need for a resync, it’s still required from time to time if something goes wrong.
However, there are a few major improvements to resyncing in this release:
The default behavior for resyncing is now to preserve coin and asset data. This means that it will typically only take a few seconds rather than waiting for a long time for all of your coins to trickle back in. Instead of re-indexing everything from scratch it will only check for coins that are missing or out of date. However, you can still decide to delete additional data while resyncing if that’s not sufficient.
There’s a new “Delta Sync” option. The default behavior in Sage is to only look for and sync coins that are after the previous block height that you were synced to. However, if things happen in the wrong order and you end up with some coins missing (due to a race condition), you may need to resync. If you turn off Delta Sync, the wallet will check for coins it owns every time it’s started. This comes with a slight performance tradeoff, so it’s up to you whether you want to turn it off or not.
RPC API
There is still no formal documentation for the RPC API, however I’d like to point out that there have been some breaking changes as a result of the refactors made in this release. Please check the Sage RPC crate for more details if you rely on these API endpoints. This API is not yet stable, so please use it with caution and pay attention to updates.
Other Features
There have been various other additions in this release, including:
Support for viewing offers with chia-offers.com short URLs
CSV export and offer sharing on mobile
You can now mint multiple editions of a single NFT at once
Offers work with fast forward (ie offer involving vaults)
Bug Fixes
The following bugs have been fixed:
You will now get an error in the UI if a transaction fails. Additionally, bugs relating to unconfirmed coins being left behind or coins you should own mistakenly disappearing until a resync should now be resolved.
NFT collections will now no longer be displayed if you don’t own any NFTs in them anymore.
The app would crash about every other time it was opened on iOS. This should be entirely resolved now, but please report any further crashes you run into.
Some UI errors could lead to blank screens. Known issues have been resolved, but if anything new comes up, please let us know.
Conclusion
Now that all of this has been finished, I feel a lot better about being able to add new features in a shorter amount of time like we used to. You can expect more frequent Sage releases going forward.
The next feature that is yet to be released is Option Contracts. I was originally planning on including it in this release, but due to the amount of other changes being made and the complexity of the feature, I decided to punt on it for now so that it could be ironed out more.
Let us know on Discord if you have any feature requests or find any bugs with the latest release!