Kadena aims to continue building and supporting our developer community with a robust, best-in-class experience for Web3 developers. In order to do so, the team at Kadena continues to provide developer updates swiftly to ensure a smooth builder experience.

This article will inform you on how to migrate away from two guard types in Pact to safe alternatives. These deprecated guards will be removed in a future release.

Module and pact guards were designed to allow autonomous code to control funds in an era when all Pact code execution paths were known at compile time. The later introduction of module references allowed untrusted third-party code to be executed within module code, rendering module and pact guards unsound. The solution is to migrate your code to capability user guards.

While code that does not involve module references can safely use module and pact guards in some cases, capability user guards are still less bug-prone. For this reason module and pact guards are considered deprecated and all user code is recommended to exclusively employ capability user guards in cases where module and pact guards would previously have been used.

The original design of Pact offered autonomous guards largely modeled after the ownership model presented in the Ethereum EVM, where “contract accounts” simply hold ETH alongside code that can use those funds however it sees fit. In Pact, this was generalized into module guards, where the guard would pass as long as the code was being called from the module associated with the guard, and pact guards, which only pass if a specific instance of a defpact is executing.

This, of course, meant that module code invoking the guard-handling code had to be protected by other predicates and capabilities. As such, the code could have bugs as there was no explicit authorization, or scoping of said authorization. Capability-based guards solve these potential issues.

However, the later introduction of module references now brings third-party code into the mix, with the unfortunate property that anywhere the owning module calls into module reference code, that third-party code now passes the module guard. This is also true for defpact guards: while the current Pact ID is validated, invoking modrefs in any way will pass the guard.

Fortunately, building user guards using require-capability offers a truly secure mitigation. Capabilities now secure and scope guards alongside critical module code. All of the features that make Pact capabilities sound are now extended to guards for robust autonomous resource ownership.

Capability User Guards are a design pattern for safe autonomous guards in Pact. They are composed of three code elements: a capability, a predicate function, and a user guard. The latter can be offered as a “constructor function” resulting in a trio of definitions that defined together clearly present the overall guard structure.

A typical use of a module guard is to allow a smart contract to control KDA funds. For instance, the following deprecated code transfers money into an account owned by a module guard.

The problem with module and pact guards emerges when invoking the guard to do critical operations like withdrawals.

The core enabling feature of Pact powering this mitigation are capabilities, which already serve to secure critical pact code. Modules using the above bank code might have code that looks like the following:

With a module guard, there is potential for the first code block to be unsafe. However, by creating or rotating the BANK_KDA_ACCT with a capability user guard, this same withdraw code can be 100% safe with no changes.

Armed with these definitions, the original funding code can now be migrated to read:

… and the withdrawing code above will continue to function with no changes. Migration complete!

The problem with the above migration is the over-specificity of building the guard around the WITHDRAW capability: for instance, the above code only allows withdrawals of the same amount that was originally funded. If WITHDRAW is invoked with a different amount, the guard will not pass.

The opposite end of the solution spectrum is a parameter-less capability that serves only to fulfill the conditions of a capability user guard, which is then composed into the WITHDRAW capability.

You would then create the account using the BANK_DEBIT guard:

While capability user guards require the least boilerplate when using a parameter-less capability, it is best to “de-parameterize” only as much as needed to serve the indicated use cases and no more. For instance, if WITHDRAW was the only bank-debiting operation in the above example module, and was explicitly designed to withdraw exactly what was funded, then the WITHDRAW-based capability guard is actually safer by limiting cases where the guard would fire. Indeed, it suggests a design that supports UTXO-like accounts, with the WITHDRAW capability guard perfectly suited to support multiple accounts that support only a single deposit and withdrawal.

When migrating, keep an eye out for code that relies on a single resource + module guard which could be improved by decomposing into separate resources. For instance, if user and autonomous monies previously shared the same KDA bank account, using two accounts protected by the distinct capability guards is potentially a safer design.

Pact guards must be migrated to capabilities that are explicitly parameterized with the intended pact ID, and enforce equality with the current pact ID. Beyond that, they are identical to migrations for module guards.

In a marmalade-style sale, BUY guards the second step. In the first step, instead of using create-pact-guard, you would use the capability user guard with the current pact ID to guard the NFT escrow:

Now, you are all set and the pact guards have now been migrated!

We hope that you found this article to be helpful! Please share your feedback with us on our Discord channel or on our GitHub repository! Be sure to follow us on Kadena’s social media accounts for more developer updates and news as Kadena continues to drive innovation on the blockchain!