Pact Contract Interaction¶
Welcome to this tutorial on Pact Contract Interaction!
Topics covered in this tutorial
- Pact Contract Interaction Overview
- Project Overview
- Project Environment Setup
- Auth Pact File
- Payments Pact File
- Payments REPL File
- Run the Smart Contract
The goal of this tutorial is to learn the basics of building interactions between modules in Pact. You will go over some of the fundamentals, then build a smart contract that allows users to both make and authorize payments using multiple Pact modules.
Modules can make use of functions within other modules. This is done first with use, and then by calling the functions from within the module you are using. Each of these files are then loaded into the REPL where you can specify function calls and test interactions between these modules.
Pact Contract Interaction Overview¶
Contract interaction allows you to set up more complex smart contracts by working with modules across multiple files. Having access to separate files allows you to break up your smart contracts into more manageable sizes. It also allows you to use helpful files that others have created.
In the image below, you can see that there are 2 files, module-1 and module-2. In this case, module-2 is using module-1 to call functions that exist within the module. The REPL file then loads and uses both of these modules to call functions and facilitate the interaction.
The three most helpful Pact functions to keep in mind for Contract Interaction are load, use, and function calls.
Load and evaluate a file.
Import an existing module into a namespace.
Once the interaction is set up between files, all function calls can be done the same as if the function existed within that file.
The idea of working with multiple modules and files is easiest to demonstrate with an example. For that reason, the rest of this tutorial is focused on getting you up and running with your own project.
Before getting started with this application, take a look at the visual overview. This provides a summary of each of the features you will be creating for the Pact Contract Interaction project.
The goal of this project is to write a function in auth.pact to use within payments.pact. Payments.pact will then use auth.pact to call specific functions. You will then load modules from both of these files into the payments.repl file to run the interaction between these contracts.
Each number in the image corresponds to one of the files you will work with.
|auth.pact||Responsible for authorizing users.|
|payments.pact||Responsible for handling payments between users.|
|Payments.repl||Loads and runs modules from both auth.pact and payments.pact.|
Both auth.pact and payments.pact are smart contracts that you have worked with in previous tutorials. If you would like to learn more about these smart contracts, feel free to view each of their tutorials.
There’s not much code to write for this project. Most of it has been written previously in the tutorials linked above. For this tutorial, focus on understanding the interactions between the smart contracts, and to take some time to study how the functions are interacting with each other.
Making the conceptual leap toward understanding the interactions between modules is going to be extremely valuable as you make more complicated smart contracts.
Project Environment Setup¶
To get started, choose a project directory and clone the project resources into your local environment.
git clone https://github.com/kadena-io/pact-lang.org-code.git
Change into the interaction directory to begin working on this project.
Open this directory in atom to see each of the files provided.
As you’ll see, there are a few separate folders available to you.
|start||Provides a starting point with all comments for every challenge.|
|challenges||Challenges in the demo are broken out into separate files, allowing you to build your application over time while having the flexibility to experiment with your own ideas.|
|finish||Includes all comments and code for the final application.|
|loans||Includes final application without the challenge comments.|
Each of these options are meant to help support you as you work through these challenges. Feel free to use them however you’d like.
1. Auth Pact File¶
The first step of this project is to write the function that you will call from the payments smart contract. You will write this function within the auth smart contract.
Navigate to 1-start/auth.pact or to 2-challenges/1-auth-pact depending on how you prefer to follow along.
1.1 Enforce User Auth¶
The function you will write will enforce user authentication for payments made with accounts. This will be a valuable function for restricting access to either admins or account users, ensuring each user is the only person that has control over their account.
Define a function enforce-user-auth that you can use to verify user authorization.
A function similar to this is covered in Challenge 4.2 in Project Rotatable Wallet. You can look back to this challenge for more information to help get you started.
2. Payments Pact File¶
Next, you will work on the payments.pact file.
The goal is to use the auth module, then call the function you wrote within the payments module to specify authorization for users.
Navigate to 1-start/payments.pact or to 2-challenges/2-payments-pact depending on how you prefer to follow along.
2.1 Use Auth¶
The first step is to get access to the auth module. You can do this with the Pact special form use.
The syntax for use looks like this.
It’s simple but extremely powerful! This is what will allow you to call functions from the auth module.
Take a moment now to use the auth module from within the payments module.
2.2 Create Account¶
For this application, it’s important that only the administrator has access to create an account. This is a good use case for the enforce-user-auth function you wrote in the auth module.
Since you now have access to the auth module, you can begin working with its functions. You can call these functions the same as you would call any other function.
Take some time now to add this new functionality to your smart contract.
Call enforce-user-auth from within the create-account function to authorize that the user is an administrator.
2.3 Get Balance¶
Another time you may want to authorize a user is when checking the balance of an account.
The payment modules get-balance function is an excellent use case for this. This time, both the administrator and the owner of the account should have access to view the account balance.
Similar to before, check for authorization within the get-balance function.
Call enforce-user-auth from within the get-balance function to authorize that function is called by the administrator.
Finally, it’s important that payments are authorized by the owner of the account. This will ensure that only the person who has the money is able to send it to others.
Finish off the payment module by authorizing that the payment is being sent by the owner of the account.
That completes the payment module.
You are now ready to set up this contract interaction using the payments.repl file!
3. Payments REPL File¶
You can now finish this project by completing on the payments.repl file.
Navigate to 1-start/payments.repl or to 2-challenges/3-payments-repl depending on how you prefer to follow along.
The goal is to use both the auth and payments module, then coordinate interactions between them.
3.1 Load Auth Module¶
To get started, you need access to the auth module from within the payments.repl file.
This is done using load.
Try using load to complete the code challenge.
Transactions and loading are covered in more detail in Testing Pact Code in the SDK.
3.2 Load Payments Module¶
Next, you need to load the payments module into the payments.repl file.
This can be done the same way as you did with the auth module.
3.3 Use Auth Module¶
You now have access to both the auth and payments module from within the payments.repl file. After loading each file, you also need to specify that you are using them.
Like before, this can be done with the special form use.
3.4 Use Payments Module¶
Finally, you need to use the payments module. Write one final line of code that uses the payments module and completes your set up for contract interaction.
You are now finished setting up your contract interaction. Congratulations!
4. Run REPL File¶
After completing your contract interaction project, you can now see it all work together.
To do this, navigate back to your terminal.
From the terminal, you can navigate into 1-start folder if you have worked within this directory. If not, you can also navigate to the 3-finish folder for an example of the completed application.
Load the payments.repl file.
The output to your terminal should look similar to the image shown below.
For more information on running files from the terminal, view Testing Pact Code in the SDK.
Congratulations on completing this introduction to Pact Contract Interaction!
In this tutorial, you learned the basics of contract interaction and built a smart contract that allowed users to both make and authorize payments. This allowed you to extend the functionality of your smart contract to include multiple files, and you can now use this to build more complex smart contracts in any project.
Take a look back at some of the modules you have written or examples that you’ve come across. Are there any interesting new ways that you think these contracts could work together? Give it a try and see if you can come up with an entirely new smart contract that combines these interesting features in new ways!