Keysets

This tutorial introduces another essential feature in Pact known as keysets. We’ll discuss what keysets are, why they’re important, and how they help regulate access to Pact modules.

Tutorial Overview

Subscribe to our YouTube channel to access the latest Pact tutorials.

Pact Keysets specify authorization to different parts of the smart contract. They determine which accounts have access to and update various parts of the program.

The first step toward working with keysets is to create one. Creating a keyset can be done using the online editor within the environment section.

Navigate to pact.kadena.io

Steps to create a keyset

You should now see admin-keyset appear under your list of available keysets.

This keyset is now added into the browser’s local storage. When you begin working locally, this keyset will need to exist in the .repl file that you create along with your .pact file. You will learn more about this process in later tutorials.

After creating a keyset, you need to both define and read this keyset from within the smart contract you create. This is done using a pair of built-in functions; define-keyset and read-keyset

Here is the syntax used to define and read a keyset named “admin-keyset”.

Keysets guard the logic encoded within a module, these functions should be placed above the module and will fail if written within the module code.

The keyset you have created is meant to hold keys. These keys are used to sign and verify transactions that occur from within the module.

Steps to create a key

You should now see the key name, the public key, and the private key of the key you generated.

While one key is enough to get started, this tutorial will show you some other key options that are available to you. For that reason, take some time now to generate two more keys.

Generate two more keys

After creating these keys, notice that they are all available as checkboxes under the admin-keyset. Select each of these checkboxes now.

You’re now ready to use these keys to help understand predicate functions.

Alongside the keyset you created, you will see a dropdown that allows you to select keys-all, keys-2, and keys-any.

These options are referred to as the predicate functions in your keyset.

A predicate function is a boolean value function evaluating to either true or false. In this case, it will be one of the options keys-any, keys-2, or keys-all as you had seen in the keysets tab.

Predicate functions specify which keys need to sign the transaction for it to be valid.

The keys that the predicate function is referring to are those you selected with the checkboxes

Determining which is appropriate for your application depends on what you are trying to accomplish.

In cases where all members of a group are equal, and it is important for each of them to sign the transaction, then you will use keys-all. If there are many members of the group but only a few need to verify the transaction, keys-2 could work well. And if anyone signing is enough to verify the transaction, select keys-any.

Each key created has an equivalent JSON representation you can view from the Result tab.

Notice that this JSON object includes the name of your keyset, the public key of each of the keys you added to the keyset, and the current value of the predicate function you selected.

You can also create keysets using the JSON format rather than the user interface. Creating keysets with JSON is done using the Raw tab.

This format will be used in real dApps or in .repl files for simulation. It allows you to copy your JSON formatted keysets to test and deploy on pact-web, allowing you simply copy and paste into this box rather than re-creating everything from scratch.

To create a new key, specify a keyset name, keys, and pred, similar to the format seen in the Result tab.

While keysets tab is a simple way to create new keysets on the website, raw tab is a simpler way of inputting keysets that already exist.

Verifying transactions with keysets is important when deploying a smart contract. You can check this out for yourself from the deployment screen in the online editor.

Where to find the sign tab

You should now see the following screen, which includes the keysets and specified keys from within the module.

To deploy the smart contract, you will need to select a number of keys using the checkbox to the right as specified in the predicate function. This will ensure that your smart contract is successfully verified.

Calling a function on a deployed contract is another time where key signatures become valuable.

To get started, view the helloWorld smart contract in the module explorer and call the hello function.

Steps to call the hello function

After calling the function, you should see a screen showing the Parameters of the function.

Select the Sign tab to the right of Parameters to view the keys available to use for signatures.

Here you should again see each of the keys you have available to sign the transaction. In this case, the helloWorld contract does not have any signature restrictions so you can call the function without these. That said, it’s also fine to sign with a key now to get some practice.

Select the checkbox next to one of the admin-keys, and go back to the function parameters screen.

Type “Pact Keys” (or whatever you prefer) as a Parameter and click Call to call the function.

After calling the function, you should see “Hello Pact Keys” appear in the messages tab.

You have now verified a transaction using a key signature on a deployed smart contract. Again, it wasn’t required for this specific contract but this is a very simple way to get familiar with the process for when you need it later.

It’s helpful to go through a process where you actually have restrictions on running code based on the keysets you have available. These restrictions can affect both your ability to load a contract into the REPL and the ability to call functions on a deployed contract.

One example that does a good job exploring keysets and restrictions is the Simple Payment example.

Navigate to Simple Payment example

You will be building a smart contract like this for yourself in a later tutorial. For now, you’ll focus on a few critical areas that illustrate how to set keyset restrictions from within a module.

Throughout the module, you’ll notice the following built-in function. enforce-keyset

This function executes a guard or defined keyset name to enforce desired predicate logic.

You can find an example of this on row 28 of the Simple Payments smart contract which is summarized below.

Here is how the code sample above is working

Using this method, you can check that the caller of any function is the owner of a keyset that you specify.

When you get the following response you have successfully fixed the first error.

:::info Feeling Stuck?

Create a keyset named admin-keyset from within the Env to remove this error.

:::

In the next section, you will address the remaining errors.

Another useful built-in function for checking keysets is known as enforce-one. enforce-one

This built-in function runs a series of tests in a specific order to check that one of the following statements are true.

You can find an example of this on row row 38 of the Simple Payments contract and is summarized below.

Similar to the previous example, this example is enforcing that the caller be the owner of the admin-keyset. Unlike the previous example, it is also allowing the caller to be the owner of their account.

Notice how it is doing this using enforce-one paired with enforce-keyset.

Enforce-one starts a series of tests to check that any of the following lines are true.

If one of them is true, the caller will gain access to run the rest of the function. If neither of them is true, the caller will get a response that their request has been denied since they are not the owner of one of the required keys.

What this means is that both the admin and owner of the account can view their balance, but no one else can.

When you get the following response you have successfully fixed the first error.

:::info Solution Create two keysets from within the Env to remove this error.

:::

After creating these keysets the response signifies that you have successfully deployed the smart contract into the REPL.

You are now ready to deploy the Simple Payments smart contract. For information on deploying a smart contract, view Deploy to the Testnet from the Hello World with Pact tutorial.

Now that you have the appropriate keys and keysets, you can also run the deployed version of this smart contract.

From the module explorer, view the module deployed in the previous section.

Select the get-balance function to attempt to view James’ balance. To do this, select parameters, and type “James” as the id.

Next, sign the contract with either the admin-key or the james-key. As shown earlier, each of these should have the authority to read James’ account balance.

After selecting call, you should see the James’ balance displayed. If you’d like to test that it is working correctly, you can also try to make this function call by signing with sarah-key. When doing this, you should receive an error since Sarah is only permitted to view her own balance.

Using these ideas, you can call any function on the smart contract by giving the proper function parameters and signing the transactions with the appropriate keys.

That wraps up this tutorial on Pact Keysets.

As you learned, Pact Keysets allow you to specify authorization to different parts of the smart contract. They help determine which accounts have access to which parts of the programs you create.

Throughout this tutorial you to created, defined, and read keysets. You also created keys, were introduced to predicate functions, and learned a few other options available to work with keys from the online editor. You also saw where to go to utilize these keys both when deploying a contract and calling a function. Finally, you experimented with running an existing smart contracts that had built-in keyset restrictions.

Managing permissions can be difficult, and really depends on the needs of your application. For that reason, it’s difficult to show all of the possibilities that may come up with keysets. That said, this tutorial tried to give a strong foundation for what options are available, and variations of these ideas will come up often in later tutorials.

Take some time now to experiment with keys and keysets, and when you’re ready, move on to our next tutorial.