Creating Smart Contract File-Driven Policy via the Desktop
The content here only impacts users who are permitted to interact with smart contracts.
Introduction
Custody Infrastructure allows you to exercise granular control over which users can do what actions with which smart contracts. This granularity goes much deeper than what can be configured directly via the MPC (via either the GUI or SDK), but utilizing it requires writing and uploading a custom .txt file written utilizing a specific format for the language.
The process involves creating a file outlining specific functions on a contract and uploading that file via the MPC desktop. Once uploaded, the rules outlined in the file can be included in a smart contract policy and used to govern what interactions policy initiators can have with the contract(s) indicated in the file.
The rules described by the file only cover the policy initiators; the policy file doesn't change anything for other users on the system.
Capabilities
The granularity allows you to control any type of function used in the smart contract.
The policy file identifies a smart contract by its chain ID and address on chain. Once identified by a policy file, the Custody Infrastructure system prevents ALL functions from being performed on that contract except those explicitly listed in the file.
Functions listed in the file use static Solidity types and are paired with parameters. Only function-parameter pairs that are listed are permitted by the Custody Infrastructure system.
Logical Flow
When a user tries to call a smart contract, the system performs the following checks:
- Does the user have a specific policy including a policy file? If yes, continue. If no, stop the transaction.
- Is the policy file(s) for the specific chain/address? If yes, continue. If no, allow the transaction.
- Is the function being called included in the file? If yes, continue. If no, error out.
- Does the function specify values in the file? If yes, continue. If no, send the transaction. A function without values allows all values!
- Is the value being used listed? If yes, send the transaction. If no, error out.
Use Cases
If you want to control whether an MPC user can interact with smart contracts at all, you can do that through the standard Transaction Policies menu of the MPC desktop.
If you need to govern exactly how your users can interact with specific smart contracts, you will need to create and upload a policy file. Once uploaded, you then create a transaction policy (any interaction with a smart contract is a transaction) that references the uploaded file and applies its rules to all policy initiators.
Writing the Policy
Follow the guidance in Writing a Smart Contract Policy FileWriting a Smart Contract Policy File to prepare your policy file. The file uses a syntax developed in-house by Custody Infrastructure, and any deviation renders the file unusable. Please consult the reference material the first couple of times you create policy files.
Creating Policy Based on Policy Files via the MPC Desktop
The procedures in this step must be performed by a user with admin privlege. The system must be running in MPC-Driven mode, and the user must be logged into the MPC with full access.
Before beginning the process of creating a smart contract policy based on a prepared .txt file, make sure the file is located in a folder on your system that can be seen by the Galaxy Custody Desktop app on your computer.
Before a file can be used to drive policy, it needs to be uploaded. Uploading is not a stand-alone procedure; it's part of the transaction policy creation flow. For an overall view of the flow, see Transaction Policies.
Once the file is prepared, the entire policy creation process happens in the MPC desktop application.
The Process has three phases:
- Add the smart contract as a contact on the account's allowlist.
- Upload the Policy File.
- Create the policy based on the uploaded file.
Adding the Contract to the Allowlist
For a deep dive into addresses and address groups, see Addresses and Address Groups.
A smart contract contact is added just like any other.
Navigate to the Addresses section of the MPC desktop app by clicking the Addresses button.
Ensure you are in the Addresses tab.
Click the Create New Contact button.
The Add a new contact menu opens.
Fill out all the required information for your smart contract. Make sure to set the contact type to Authorized.
Click Create. Your new contact has been successfully added to a change request.
Once the contact change is approved, you can create your file-based policy to govern interactions with the smart contract.
Uploading the Smart Contract Policy
Navigate to the Policy Management section of the MPC desktop app by clicking the Policy button.
Ensure you are in the Transactions Policies tab.
Click the Create New Policy button.
The New Policy menu opens.
Input a name for the Policy.
Set the policy type to Transfer. The Allow smart contract function calls option appears.
Click the toggle to Allow smart contract function calls.
Click Upload File. The Smart contract function creation file upload dialog appears.
Click the image in the center of the dialog box to open the file selection menu. Navigate the selection menu to find your file.
Click the file and select Open. The selection dialog closes and the file appears listed in the dialog box.
Click Upload file. You are given a chance to review the file contents. If everything is in order, click Add. The dialog disappears; the contract has been uploaded sucessfully.
Once uploaded, continue with creating your Transaction Policy.
Error Handling
The MPC runs a simple verification check on the file as part of the uploading process. If it runs into any problem, it will display an error. For details on how to resolve any errors you encounter, see Troubleshooting a Smart Contract Policy FileTroubleshooting a Smart Contract Policy File.
Building a Policy based on the Smart Contract Policy File
Creating the actual policy is very similar to creating any other transaction policy, but some options are automatically set by the uploaded policy file and can no longer be set by the desktop interface.
Select which originating Account(s) will be covered by the policy.
The To address is set by the uploaded policy file.
Click Next.
The Currencies selection is set by the uploaded policy file. You can remove any currencies you want at this point but don't. Click Next.
Select your Initiators. These users will be governed by the policy file you uploaded.
Set one or more ranges. These are only measured when a smart contract interaction involves sending assets out from the account to the smart contract. Each range can have a unique set of approvers.
Click Create.
After the standard approval process, your new policy is in effect and your governed users will be able to utilize the chosen smart contract only in the manner you described in the file.
Transaction Results
Once a policy file has been uploaded and a policy built around it, the system treats it like any other policy. The MPC cannot tell how any policy was created; every policy appears identical.
Following a smart contract transaction on the transaction page will show it move through the same flow of approvals, mempool, and confirmations. If the Custody Infrastructure system blocks the transaction, it will show the same "Failed - policy" as any other blocked transaction.