Merge pull request #155 from UniqueNetwork/evm-docs

docs: add precompiles and sponsoring docs

docs/.vuepress/configs/sidebar.ts

@@ -72,6 +72,7 @@ export const sidebar: Record<string, SidebarConfig> = {
             '/build/sdk/tokens.md',
             '/build/sdk/examples-nesting.md',
             '/build/sdk/refungible.md',
+            '/build/sdk/sponsoring.md',
         ]
       },
       {
@@ -80,8 +81,18 @@ export const sidebar: Record<string, SidebarConfig> = {
           '/build/evm',
           '/build/evm/accounts.md',
           '/build/evm/evm-from-substrate.md',
+          {
+            text: 'Precompiles',
+            link: '/build/evm/precompiles/index.md',
+            collapsible: true,
+            children: [
+              '/build/evm/precompiles/index.md',
+              '/build/evm/precompiles/contract-helpers.md',
+              '/build/evm/precompiles/collection-helpers.md',
+            ],
+          },
           '/build/evm/smart_contracts.md',
-          '/build/evm/UniqueNFT.md'
+          '/build/evm/UniqueNFT.md',
         ],
       }
     ],
@@ -204,7 +215,9 @@ export const sidebar: Record<string, SidebarConfig> = {
           '/reference/blockchain/owner-admin-roles.md',
           '/reference/blockchain/rpc.md',
           '/reference/blockchain/extrinsics.md',
-          '/reference/blockchain/events.md',        ],
+          '/reference/blockchain/events.md',
+          '/reference/blockchain/contract-helpers.md'
+        ],
       },
       {
         text: 'Schemas',

docs/build/evm/index.md

@@ -6,6 +6,12 @@ Unique Network employs Substrate’s flexibility to deliver native NFT features,
 
 This documentation will guide you through deploying and interacting with NFTs via the EVM layer, offering a comprehensive toolkit for both Substrate and Ethereum developers.
 
+## Navigation
+
+1. To understand how compatibility between Substrate and Ethereum accounts is achieved, see the [Account mirrors](./accounts.md) section.
+2. To learn how Ethereum smart contracts can be called from Substrate, visit the [EVM from Substrate](./evm-from-substrate.md) section.
+3. If you're interested in advanced features like creating native NFTs, nesting, and providing a gasless experience, explore the [Precompiles](/build/evm/precompiles/index.md) section.
+
 ## Connect to the EVM on Unique Network
 
 You can connect to Unique utilizing familiar tools such as MetaMask and Ethers.js. These tools allow developers to interact with and deploy smart contracts as they would on any Ethereum-compatible network.

docs/build/evm/precompiles/collection-helpers.md

@@ -0,0 +1,23 @@
+# Collection Helpers
+
+Address: **0x6c4e9fe1ae37a41e93cee429e8e1881abdcbb54f**
+
+This precompiled contract enables the creation of native collections and tokens via the Ethereum interface.
+
+## Code examples
+
+Below are examples of how to use this precompiled contract with ethers.js and hardhat.
+
+> If you're unfamiliar with setting up a Hardhat project, refer to the official documentation: https://hardhat.org/docs
+
+### Connect to contract
+
+```ts
+import { ethers } from 'hardhat';
+import { CollectionHelpers__factory } from '@unique-nft/solidity-interfaces';
+
+const [signer] = await ethers.getSigners();
+
+const collectionHelpers = CollectionHelpers__factory
+  .connect("0x6c4e9fe1ae37a41e93cee429e8e1881abdcbb54f", signer);
+```

docs/build/evm/precompiles/contract-helpers.md

@@ -0,0 +1,98 @@
+# Contract Helpers
+
+Address: **0x842899ecf380553e8a4de75bf534cdf6fbf64049**
+
+This precompiled contract allows the owner to manage the sponsorship of their contract.
+
+In Unique Network, transactions can be sponsored, allowing for a gasless experience where the sponsor covers the transaction fees. This enables seamless and cost-free transfers of NFTs and the execution of smart contracts, even for accounts without native tokens.
+
+[[toc]]
+
+## Interface
+
+Check the [reference section](/reference/blockchain/contract-helpers.md) for the complete interface details
+
+## Code examples
+
+Below are examples of how to use this precompiled contract with ethers.js and hardhat.
+
+> If you're unfamiliar with setting up a Hardhat project, refer to the official documentation: https://hardhat.org/docs
+
+### Connect to contract
+
+First, let's deploy the smart contract to be sponsored and connect to ContractHelpers precompile. We assume you have developed a contract called MyContract.sol and want to sponsor its calls.
+
+```ts
+import { ethers } from 'hardhat';
+import { ContractHelpers__factory } from '@unique-nft/solidity-interfaces';
+
+const [signer] = await ethers.getSigners();
+
+const MyContractFactory = await ethers.getContractFactory('MyContract', seller);
+
+// Contract to be sponsored
+const myContract = await MyContractFactory.deploy();
+myContract.waitForDeployment();
+
+const contractHelpers = ContractHelpers__factory
+  .connect("0x842899ecf380553e8a4de75bf534cdf6fbf64049", signer);
+```
+
+## Choose sponsoring mode
+
+### Self-sponsoring
+
+The simplest option is to sponsor transactions directly from the contract address itself.
+
+```ts
+await contractHelpers.selfSponsoredEnable(await myContract.getAddress());
+
+const hasSponsor = await contractHelpers.hasSponsor(myContract.getAddress());
+console.log("Self sponsoring enabled: ", hasSponsor); // true
+```
+
+### External address sponsoring
+
+You can also set up sponsorship from an arbitrary address. In this case, one additional step is required – the sponsor must confirm the sponsorship.
+
+```ts
+await contractHelpers.selfSponsoredEnable(await myContract.getAddress());
+
+const hasSponsor = await contractHelpers.hasSponsor(myContract.getAddress());
+console.log("Self sponsoring enabled: ", hasSponsor); // true
+```
+
+### Enable sponsoring
+
+There are a couple more steps to enable gasless transactions.
+
+1. There are three sponsoring modes:
+
+- 0: Disabled (default)
+- 1: Allowlisted (Only users from allowlist will be sponsored)
+- 2: Generous (All users will be sponsored)
+
+Let's configure the contract to sponsor transactions for all users.
+
+2. By default, not every block is sponsored due to a timeout. Let's adjust this setting.
+
+```ts
+// Sponsoring is Disabled by default:
+const sponsoringEnabled = await contractHelpers.sponsoringEnabled(myContract.getAddress());
+console.log("Is sponsoring enabled?", sponsoringEnabled);
+
+// Set to 2 - Generous mode
+await contractHelpers.setSponsoringMode(myContract.getAddress(), 2);
+// Set to 0 - Sponsor transactions in every block
+await contractHelpers.setSponsoringRateLimit(myContract.getAddress(), 0);
+
+// Optionally, you can limit the maximum fee amount you want to sponsor
+// await contractHelpers.setSponsoringFeeLimit(myContract.getAddress(), ...);
+
+const sponsoringEnabledAfter = await contractHelpers.sponsoringEnabled(myContract.getAddress());
+console.log("Sponsoring enabled now:", sponsoringEnabledAfter);
+```
+
+## Setting up Metamask
+
+When sending transactions through Metamask, it initially verifies if the user has sufficient balance to cover gas fees. To enable sponsoring with Metamask, we need to bypass this gas check. Use the following [library](https://github.com/UniqueNetwork/web3-provider-sponsoring).

docs/build/evm/precompiles/index.md

@@ -0,0 +1,10 @@
+# Intro
+
+Unique Network offers a suite of precompiled contracts that enable interaction with advanced features through the Ethereum interface.
+
+To integrate these capabilities into your application, use the [@unique-nft/solidity-interfaces](https://www.npmjs.com/package/@unique-nft/solidity-interfaces) library.
+
+|Precompile|Features|Address|
+|:-|:------|:---|
+|[Contract Helpers](./contract-helpers.md)|Manage contract sponsoring|0x842899ecf380553e8a4de75bf534cdf6fbf64049|
+|[Collection Helpers](./collection-helpers.md)|Create native collection and tokens|0x6c4e9fe1ae37a41e93cee429e8e1881abdcbb54f|