​
What is a Permissioned Foreign Call?

A Permissioned Foreign Call is a security mechanism that controls who can use specific functions from external contracts in their Rules Engine policies.

​
How it Works

  1. Contract Owner Sets Up: The owner of an external contract marks specific functions as “permissioned”
  2. Rules Engine Creates Allowlist: The Rules Engine maintains a list of addresses that are allowed to use this function
  3. Policy Creation Check: When someone tries to create a policy that uses this function, the Rules Engine checks if their address is on the allowlist
  4. Access Control: If they’re not on the list, the transaction fails

​
Why Use This?

This prevents malicious users from manipulating external contract data through Rules Engine policies. It’s especially important for contracts that store state data that gets updated by the Rules Engine.

​
Setting Up a Permissioned Foreign Call

​
Step 1: Inherit the Admin Contract

Your contract must inherit from RulesEngineForeignCallAdmin (available in the forte-rules-engine npm package): 
import "@forte-rules-engine/contracts/RulesEngineForeignCallAdmin.sol";

contract MyContract is RulesEngineForeignCallAdmin {
    // Your contract code here
}

​
Step 2: Mark Functions as Permissioned

After deployment, call setForeignCallAdmin() on your contract: 
// Parameters:
// - functionSignature: The function you want to protect (e.g., "transfer(address,uint256)")
// - adminAddress: The address that will be the Foreign Call Admin
setForeignCallAdmin("transfer(address,uint256)", adminAddress);
This immediately marks the function as permissioned in the Rules Engine.

​
Step 3: Manage the Allowlist

The Foreign Call Admin can manage who can use this function:
  • Add users: addAdminToPermissionList()
  • Update list: updatePermissionList()
  • Remove all: removeAllFromPermissionList()
Only the Foreign Call Admin can call these functions.

​
Understanding the Foreign Call Admin Role

The Foreign Call Admin is the gatekeeper for a permissioned foreign call.

​
Key Responsibilities

  • Single Admin: Each permissioned foreign call has exactly one Foreign Call Admin
  • Multiple Contracts: One address can be Foreign Call Admin for multiple different contracts
  • Transferable Role: The admin role can be transferred to another address (requires acceptance)
  • Policy Control: Only the Foreign Call Admin can decide which Policy Admins can use this foreign call

​
Role Transfer Process

  1. Current admin initiates transfer
  2. New admin must accept the role
  3. Transfer completes only after acceptance

​
Security Note

Your foreign contract should include proper access controls to ensure only the Rules Engine can call the permissioned functions. This prevents direct manipulation outside of the Rules Engine system.