Create a new smart contract project using hardhat.
mkdir rasp_erc20_example_upgradeable_hardhat
cd rasp_erc20_example_upgradeable_hardhat
npm init
npx tsc --init
npm install --save-dev hardhat
npx hardhat init //select empty hardhat config and update the extenstion to .ts
mkdir contracts
mkdir scripts && echo > scripts/deploy.ts
touch contracts/Cube3ProtectedErc20.sol
Install Cube3Protection interface using Hardhat
npm i @cube3/protection-solidity
Now setup your Cube3ProtectedErc20UUPS.sol to be an empty contract:
// SPDX-License-Identifier: MIT
pragma solidity 0.8.19;
contract Cube3ProtectedErc20UUPS {
}
Most common interactions with ERC-20 are either transfer or mint. In the next section, we are going to protect these methods using the CUBE3 RASP product.
Protecting transfer and mint methods
Import Cube3ProtectionUpgradeable, UUPSUpgradeable and ERC20Upgradeable interfaces:
Now run npx hardhat compile to make sure it compiles successfully.
Extend our Cube3ProtectedErc20UUPS to implement UUPS interfaces and setup the initialize function (read more here):
contract Cube3ProtectedErc20UUPS is Cube3ProtectionUpgradeable, OwnableUpgradeable, ERC20Upgradeable, UUPSUpgradeable {
function initialize(address router, address admin, bool checkProtection) initializer public {
// In this scenario, the contract owner is the same account as the integration's admin, which
// has privileged access to the router.
__Cube3ProtectionUpgradeable_init(router, admin, checkProtection);
__UUPSUpgradeable_init();
__ERC20_init("Cube3ProtectedToken", "CTK");
_mint(admin, 10000 * 10**decimals());
}
function _authorizeUpgrade(address newImplementation)
internal
virtual
override
onlyOwner
{}
}
Add two new methods transferCube3Protected and mintCube3Protected:
function transferCube3Protected(
address to,
uint256 amount,
bytes calldata cube3SecurePayload
) public cube3Protected(cube3SecurePayload) returns (bool) {
super.transfer(to, amount);
return true;
}
function mintCube3Protected(
address to,
uint256 amount,
bytes calldata cube3SecurePayload
) public cube3Protected(cube3SecurePayload) {
_mint(to, amount);
}
Looking at our function signatures we can see that both transferCube3Protected and mintCube3Protectedhave an additional parameter called cube3SecurePayload and uses cube3Protected modifier, which decodes cube3SecurePayload and reverts if it finds it malicious. We will see how to fetch the payload later.
Since transfer is still a public function that can be accessed by anyone, we need to hide it from anyone else other than the admin (deployer) of the contract using onlyOwner modifier (we won't need to do the same with mint, because it is not public).
contract Cube3ProtectedErc20UUPS is Cube3ProtectionUpgradeable, ERC20Upgradeable, UUPSUpgradeable, OwnableUpgradeable {
//<...> previous code
//Hide public methods that we have previously protected
function transfer(address to, uint256 amount) public override onlyOwner returns (bool) {
return super.transfer(to, amount);
}
}
And we are done protecting our contract!
Final implementation of CUBE3 Protected Upgradeable ERC-20 contract
// SPDX-License-Identifier: MIT
pragma solidity 0.8.19;
import "@openzeppelin-upgradeable/contracts/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin-upgradeable/contracts/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin-upgradeable/contracts/access/OwnableUpgradeable.sol";
import "@cube3/upgradeable/Cube3ProtectionUpgradeable.sol";
contract Cube3ProtectedErc20UUPS is Cube3ProtectionUpgradeable, ERC20Upgradeable, UUPSUpgradeable, OwnableUpgradeable {
function initialize(address router, address admin, bool checkProtection) initializer public {
// In this scenario, the contract owner is the same account as the integration's admin, which
// has privileged access to the router.
__Cube3ProtectionUpgradeable_init(router, admin, checkProtection);
__UUPSUpgradeable_init();
__ERC20_init("Cube3ProtectedToken", "CTK");
_mint(admin, 10000 * 10**decimals());
}
function _authorizeUpgrade(address newImplementation)
internal
virtual
override
onlyOwner
{}
function transferCube3Protected(
address to,
uint256 amount,
bytes calldata cube3SecurePayload
) public cube3Protected(cube3SecurePayload) returns (bool) {
super.transfer(to, amount);
return true;
}
function mintCube3Protected(
address to,
uint256 amount,
bytes calldata cube3SecurePayload
) public cube3Protected(cube3SecurePayload) {
_mint(to, amount);
}
//Hide public methods that we have previously protected
function transfer(address to, uint256 amount) public override onlyOwner returns (bool) {
return super.transfer(to, amount);
}
}
2. Deployment
To deploy, we are going to utilize ethers.js plugin. Run the following cmd:
You will be prompted with the Registration form, add the information:
Give your contract a name (for example Cube3ProtectedToken)
Add your deployed ERC1967Proxy contract address
Select the chain you deployed your contract on
and press Add contract
Initially, your contractIntegration Status will be Pending until we detect your contract on-chain, eventually it will process and say Not Registered. Click on your contract to expand it:
Click Reveal Registration Token and save it somewhere, we will use it in the next step.
2. Registering with CUBE3 Protocol (on-chain)
To register your contract with CUBE3 Protocol on-chain, you will need to call registerIntegrationWithCube3 function on the CUBE3 router contract.
Registration token (the one you saved on the previous registration step)
Function selectors that you wish to protect (you will be able to disable protection later).
To generate function selectors simply run in your console:
cast sig "mintCube3Protected(address,uint256,bytes)" //0xdfda26cd
cast sig "transferCube3Protected(address,uint256,bytes)" //0x11fb5122
Add necessary information and press Write. Make sure you do the transaction as the deployer of the contract (Admin) otherwise, it will revert.
Registration on both CUBE3 backend and CUBE3 Protocol is now done.
Go back to your RASP dashboard and you will see Integration Status of your contract to Registered and function protection On. If you expand your contract you will be able to see function selectors that are protected.
Next, we will be doing CUBE3 protected transactions to our protected upgradeable smart contract.
Ideally, interacting with your protected smart contract would be in conjunction with the frontend and backend - the user presses a button (i.e. does a transaction to your protected smart contract) which initiates a backend call, the frontend receives payload from it and proceeds to submit it to the blockchain.
But for the sake of simplicity, let's just create a simple nodejs application that executes a transaction on our protected function.
create src/index.ts file where we will write our implementation. Initially, add this inside:
async function generatePayload() {
//all of the code will go here
}
// Wrapping the call in an IIFE
(async () => {
await generatePayload();
})();
From your rasp_erc20_example_upgradeable_hardhat project directory, copy out/Cube3ProtectedErc20.sol/Cube3ProtectedErc20.json the file and paste it into cube3_transaction_executer/src the directory. We will need to access your protected contracts ABI.
2. Installing necessary packages
Install CUBE3 packages:
npm i @cube3/sdk-nodejs
npm i @cube3/sdk-ui
For blockchain interactions, we will use ethers.js:
npm install ethers@6.9.0
3. Setup contract object
To generate a payload, you need to do an HTTP request to the CUBE3 validation service. For that, we will use CUBE3 sdk. Let's begin.
First, import all necessary functions, Cube3ProtectedErc20 and setup constants:
For CUBE3 to generate a payload, it needs transaction data. For this, we will need to create a transaction object and pass it to CUBE3 sdk.
The code bellow goes into generatePayload() function.
For any interaction with a smart contract, we need to create a Wallet and Contract objects.
const provider = new JsonRpcProvider(rpcURL);
const signer = new Wallet(yourWalletPrivateKey, provider)
const cube3TokenContract = new ethers.Contract(yourProtectedContractAddress, Cube3ProtectedErc20.abi, signer);
At this point, we have an ability to call our protected contract. Let's move to payload generation.
4. Payload generation
These are the steps:
Before we send an HTTP request to the CUBE3 validation endpoint, we need to generate transaction data without actually executing the transaction. For this, we are going to utilize ethers populateTransactionto create the transaction object which stores information about the transaction.
Pass it into constructCube3Validation function which will extract the necessary data for payload generation.
Do an HTTP request to the CUBE3 validation endpoint using cube3ValidateTransaction function, which will return us whether this transaction is safe and the payload along with other information (to learn more about what the validation service returns, read more here).
In the previous step, we generated the payload for our protected mintCube3Protected function. Now all that is left is executing the transaction on blockchain.
if (validation.valid) {
const mintFuncDataWithPayload = await cube3TokenContract.mintCube3Protected(
mintTokensTo,
mintAmount,
validation.payload,
{
gasLimit: BigInt(400000),
}
);
const mintTxReceipt = await signer.sendTransaction(mintFuncDataWithPayload);
console.log("mintTxReceipt", mintTxReceipt)
//lastly, save your transaction to view it on panorama dashboard
await cube3SaveTransaction(saveTransactionUrl, validationApiKey, mintTxReceipt.hash, validation.cube3TxId)
}
From the project root directory, in cmd run:
npx ts-node src/index.ts
And the transaction receipt will appear. Copy the transaction hash and paste it into etherscan (for example sepolia) https://sepolia.etherscan.io/tx/<your-hash> on which you should see a successful transaction
Lastly, you can analyze any protected transaction on the Panorama dashboard:
To learn more about the transaction dashboard, read here.
