From 75e3c719dd898ea14f0546b9f9de3f951363398d Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Thu, 25 Apr 2024 20:25:32 +0200 Subject: [PATCH 1/8] Add Built-in Actors --- .../builtinactors/_category_.json | 5 ++ .../builtinactors/bia-bls.md | 16 +++++++ .../builtinactors/builtinactors.md | 26 ++++++++++ docs/developing-contracts/deploy.md | 2 +- docs/developing-contracts/gas-reservation.md | 2 +- .../standards/_category_.json | 2 +- docs/developing-contracts/testing-gclient.mdx | 2 +- docs/developing-contracts/testing-gtest.md | 2 +- docs/developing-contracts/testing.md | 2 +- docs/gear/features/_category_.json | 4 ++ docs/gear/features/builtin-actors.md | 47 +++++++++++++++++++ docs/gear/features/features.md | 23 +++++++++ docs/gear/features/gassignless.md | 37 +++++++++++++++ .../message-automation.md} | 41 ++-------------- .../developing-contracts/gas-reservation.md | 2 +- 15 files changed, 169 insertions(+), 44 deletions(-) create mode 100644 docs/developing-contracts/builtinactors/_category_.json create mode 100644 docs/developing-contracts/builtinactors/bia-bls.md create mode 100644 docs/developing-contracts/builtinactors/builtinactors.md create mode 100644 docs/gear/features/_category_.json create mode 100644 docs/gear/features/builtin-actors.md create mode 100644 docs/gear/features/features.md create mode 100644 docs/gear/features/gassignless.md rename docs/gear/{distinctive-features.md => features/message-automation.md} (65%) diff --git a/docs/developing-contracts/builtinactors/_category_.json b/docs/developing-contracts/builtinactors/_category_.json new file mode 100644 index 000000000..9d43fc45f --- /dev/null +++ b/docs/developing-contracts/builtinactors/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Built-in Actors", + "position": 12 + } + \ No newline at end of file diff --git a/docs/developing-contracts/builtinactors/bia-bls.md b/docs/developing-contracts/builtinactors/bia-bls.md new file mode 100644 index 000000000..8a217af7c --- /dev/null +++ b/docs/developing-contracts/builtinactors/bia-bls.md @@ -0,0 +1,16 @@ +--- +sidebar_label: BLS12-381 +sidebar_position: 2 +--- + +# BLS12-381 + +[BLS12-381](https://github.com/gear-tech/gear/blob/master/pallets/gear-builtin/src/bls12_381.rs) is the first Built-in Actor integrated into the Vara runtime. It provides an interface that enables validators to perform native runtime computations of BLS cryptography methods. + +BLS cryptography facilitates efficient signature aggregation and verification at scale using Elliptic Curve cryptography. However, these operations are computationally intensive, and the Wasm VM used in Gear is not capable of processing them quickly enough to fit within the single block time of Vara’s network (which is 3 seconds). + +The BLS12-381 Built-in Actor addresses this issue. A program on the blockchain can send a message to this actor's address with the necessary arguments for a BLS method call. The validator then executes this in native mode off-chain, which does not incur additional gas fees, and subsequently returns the result to the originating program that initiated the request. + +:::note +While it is technically possible to execute BLS methods on-chain, doing so would occupy more than 30 blocks on the Vara network. This process would require complex optimization of the calculation algorithm, involving division into 30+ equivalent parts and would also result in higher gas costs. +::: diff --git a/docs/developing-contracts/builtinactors/builtinactors.md b/docs/developing-contracts/builtinactors/builtinactors.md new file mode 100644 index 000000000..765f5253a --- /dev/null +++ b/docs/developing-contracts/builtinactors/builtinactors.md @@ -0,0 +1,26 @@ +--- +sidebar_label: Built-in Actors +sidebar_position: 1 +--- + +# Built-in Actors + +## Overview + +The Built-in Actors framework is an extensible system that provides a registry of built-in actors available in the Gear node runtime. It is implemented as a runtime [pallet](https://github.com/gear-tech/gear/tree/master/pallets/gear-builtin) capable of handling messages from other actors (programs) and process them in applications built on top of blockchain logic (such as staking, governance, computationally intensive calculations and more). This framework allows for the integration of custom logic, including access to the node's operating system and native execution. + +New Built-in Actors may be added during runtime upgrades. Since the calculations for Built-in Actors are performed within the runtime interface of the node, upgrading the node client is essential to import blocks and maintain onchain functionality. + +:::note +Built-in Actors can be added by the developers of the Gear Protocol, as they are part of the runtime. They cannot be created by any other program or initiated by users. However, they are accessible to everyone like any other program through messaging. +::: + +## Usage + +Built-in actors each have a unique `BuiltinId`, similar to other actor addresses in the network (like `ProgramId`). These IDs can be used by other programs to send specifically formatted messages to perform actions related to the blockchain logic implemented in the `Runtime`. + +A set of unique `BuiltinActor`s is defined in the `pallet_gear_builtin_actor::Config` trait as an associated type — a tuple consisting of custom types, each of which must implement the `pallet_gear_builtin_actor::BuiltinActor` trait (similar to how migrations or signed extras are defined in the Runtime). These can be pallets (if access to on-chain storage is required) or any other custom types. + +The functionality provided by the `gear_builtin` pallet includes message routing to a specific built-in actor instead of stored programs. To achieve this, the actor must be registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). + +The pallet does not expose any dispatchable functions that can be called by users. \ No newline at end of file diff --git a/docs/developing-contracts/deploy.md b/docs/developing-contracts/deploy.md index 39ddf9884..aa590c14b 100644 --- a/docs/developing-contracts/deploy.md +++ b/docs/developing-contracts/deploy.md @@ -1,6 +1,6 @@ --- sidebar_label: Upload Program -sidebar_position: 12 +sidebar_position: 13 --- # Upload program diff --git a/docs/developing-contracts/gas-reservation.md b/docs/developing-contracts/gas-reservation.md index d00422069..e962eaec8 100644 --- a/docs/developing-contracts/gas-reservation.md +++ b/docs/developing-contracts/gas-reservation.md @@ -4,7 +4,7 @@ sidebar_position: 8 # Gas Reservation -Gas reservation is the powerful feature of Gear Protocol that enables the new approach programming and modern [use cases](../gear/distinctive-features). +Gas reservation is the powerful feature of Gear Protocol that enables the new approach programming and modern [use cases](/docs/gear/features/message-automation.md). Briefly, a program can send a message using gas that was reserved before instead of using gas from the currently processing message. diff --git a/docs/developing-contracts/standards/_category_.json b/docs/developing-contracts/standards/_category_.json index 7dccc30a9..635c7ca8b 100644 --- a/docs/developing-contracts/standards/_category_.json +++ b/docs/developing-contracts/standards/_category_.json @@ -1,5 +1,5 @@ { "label": "Standards", - "position": 16 + "position": 17 } \ No newline at end of file diff --git a/docs/developing-contracts/testing-gclient.mdx b/docs/developing-contracts/testing-gclient.mdx index b895c95cf..8d8f8142d 100644 --- a/docs/developing-contracts/testing-gclient.mdx +++ b/docs/developing-contracts/testing-gclient.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 --- import Tabs from '@theme/Tabs'; diff --git a/docs/developing-contracts/testing-gtest.md b/docs/developing-contracts/testing-gtest.md index d87c24e5a..6c337272c 100644 --- a/docs/developing-contracts/testing-gtest.md +++ b/docs/developing-contracts/testing-gtest.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 --- # Testing with `gtest` diff --git a/docs/developing-contracts/testing.md b/docs/developing-contracts/testing.md index 53d5457d0..daf2a403a 100644 --- a/docs/developing-contracts/testing.md +++ b/docs/developing-contracts/testing.md @@ -1,6 +1,6 @@ --- sidebar_label: Program Testing -sidebar_position: 13 +sidebar_position: 14 --- # How to test a Gear program diff --git a/docs/gear/features/_category_.json b/docs/gear/features/_category_.json new file mode 100644 index 000000000..2bac45f5b --- /dev/null +++ b/docs/gear/features/_category_.json @@ -0,0 +1,4 @@ + { + "label": "Gear Distinctive Features", + "position": 2 + } \ No newline at end of file diff --git a/docs/gear/features/builtin-actors.md b/docs/gear/features/builtin-actors.md new file mode 100644 index 000000000..edef88f46b --- /dev/null +++ b/docs/gear/features/builtin-actors.md @@ -0,0 +1,47 @@ +--- +sidebar_label: Built-in Actors +sidebar_position: 4 +--- + +# Built-in Actors + +## Overview +[Built-In Actors](/docs/developing-contracts/builtinactors/builtinactors.md) are specialized entities within the Gear runtime that execute specific business logic when programs communicate with them via messages. This feature addresses a critical limitation: while users can directly interact with pallets through extrinsics like `bond`, `nominate`, `vote`, `transfer`, etc., programs within the Gear Protocol can only send messages, not extrinsics. + +## Purpose and Operation of BIAs + +Generally, BIAs are essential for enabling programs on the blockchain (i.e., smart contracts) to access and utilize the functionalities of pallets. + +Managed by the protocol, BIAs share the same interface similar to other programs, primarily using messaging. However, unlike programs loaded onto the network, Built-In Actors are introduced and updated through runtime upgrades, maintaining synchronization with the network's evolution. + +## Applications of Built-In Actors + +### Accessing Pallet Functions + +BIAs allow programs to interact with existing Substrate pallets and others (like staking or proxy pallets). For example, a program can send a BIA a message to `bond` a certain amount or `nominate` a validator, and the BIA will execute these on behalf of the program. + +**Examples:** +- DAO members might pool funds in a program that uses a BIA to stake these funds. The staking rewards are then distributed weekly among the participants. +- In a play-to-earn game, a user could set up a program to automatically stake earned assets or transfer rewards to an external address or within the game's balance. +- For users with zero balance, a program could use a special BIA to issue vouchers from the program’s funds without needing external services. This bypasses the limitation where such actions could only be funded by the user’s own resources. +- A special BIA could grant programs access to a proxy pallet, allowing various programs to perform limited authorized operations on behalf of the proxied program. + +This provides dApp developers with a powerful mechanism for automating scenarios and implementing custom logic in programs. For instance, BIAs provides acceess to the `staking` pallet for programs, facilitating the creation of automated staking. + +### Intensive Computations +BIAs offload intensive computational tasks from the programs, efficiently handling them at the node level to minimize gas costs and execution time. This is crucial for operations that exceed the gas limit of a single block or require extensive computational resources, such as cryptographic verifications or neural network tasks. +- For instance, cryptographic computations like BLS signature verification. BIAs designed for such computations perform them efficiently and cost-effectively at the node level. +- Simple operations like SHA-256 hashing are executed much faster through a BIA than in an on-chain program. +- BIAs can also manage neural network operations, image generation, and pattern recognition from program inputs. + +### BIA as Cross-Chain Bridge + +A BIA pallet can implement a cross-chain bridge logic that receives messages from programs, queues them, and sends them to another network based on specific logic. After execution on the other side, the program receives a response indicating the success or failure of the operation. This eliminates the need for custom intermediary nodes or teleport programs. + +The BIA can also be used to accelerate primitives for verifying ZK proofs through ECC (Elliptic Curve Cryptography), performing these calculations efficiently at the node level because they are too intensive for on-chain execution within gas limits. + +### Arbitrary Storage +If a dApp developer prefers not to write data directly into the on-chain program's memory, a BIA can serve as an efficient storage solution. + +## Conclusion +BIAs elevate the capabilities of programs (smart contracts) to the user level. Features typically implemented through pallets and accessible only through extrinsics are now available to programs. This includes using balances for governance voting, issuing vouchers, allowing other actors to perform operations on behalf of the program (proxying), conducting complex computations, and much more. This expansion significantly enhances the functionality and potential applications of blockchain programs. \ No newline at end of file diff --git a/docs/gear/features/features.md b/docs/gear/features/features.md new file mode 100644 index 000000000..060c8de13 --- /dev/null +++ b/docs/gear/features/features.md @@ -0,0 +1,23 @@ +--- +sidebar_label: Gear Distinctive Features +sidebar_position: 1 +--- + +# Gear Protocol's Key Features for dApp Development + +Gear Protocol introduces a suite of advanced functionalities tailored to simplify and enhance the development of decentralized applications (dApps). These features focus on automating operations, minimizing user friction, and broadening the scope of what dApps can achieve. Here’s a more technical look at how these features could benefit dApp developers: + +## Automation via Delayed Messaging +Gear Protocol supports the automation of internal processes via delayed messages. This allows programs to schedule future actions autonomously, such as state updates or periodic tasks, without needing external inputs. This feature is crucial for developers aiming to build self-sustaining applications that require minimal maintenance and can react to changes in state or external conditions on a pre-defined schedule. + +## Gasless Transactions +To tackle the issue of user participation costs, Gear Protocol enables transactions without gas fees through the issuance of vouchers. This feature allows users with zero balance to interact with the blockchain, potentially widening the user base for dApps and removing the initial financial barrier to entry. Developers can leverage this to attract a more diverse group of users who might not want to invest in cryptocurrency initially. + +## Signless Transactions +Gear Protocol enhances user experience by enabling signless transactions. By utilizing temporary sub-accounts with limited signing permissions, this feature reduces the need for user intervention in every transaction, streamlining processes that involve frequent interactions with the blockchain. This is particularly useful for applications that require a seamless user experience, such as gaming or social media platforms on the blockchain. + +## Built-In Actors (BIAs) +The inclusion of Built-In Actors (BIAs) allows dApp developers to tap into blockchain functionalities that are typically out of reach for programs. BIAs act as intermediaries that can execute specific operations like staking, proxy management, or cross-chain communications on behalf of the program. This extends the capabilities of dApps beyond simple transactions and interactions, enabling more complex and powerful applications. + +## In Summary +Gear Protocol offers powerful tools for dApp developers, focusing on automation, cost reduction, and enhanced interaction capabilities. These features are designed to streamline the development process, enhance the functionality of applications, and improve the end-user experience, making Gear Protocol an attractive platform for developing sophisticated and user-friendly dApps. \ No newline at end of file diff --git a/docs/gear/features/gassignless.md b/docs/gear/features/gassignless.md new file mode 100644 index 000000000..6b61599ab --- /dev/null +++ b/docs/gear/features/gassignless.md @@ -0,0 +1,37 @@ +--- +sidebar_label: Gasless and Signlesss +sidebar_position: 3 +--- + +# Gasless and Signlesss Transactions + +Gear Protocol's introduction of gasless transactions, along with signless user interactions, presents a groundbreaking concept in the Web3 sphere. This innovation is revolutionizing communication within Gear-powered networks and boosting the adoption of decentralized applications. By making their usability comparable to Web2 services and applications, Gear Protocol significantly enhances user experience in the decentralized space. + +This innovative feature empowers actors to issue [vouchers](/api/vouchers.md) that enable specific users to send messages to designated programs without incurring gas fees. This paradigm-shifting approach fosters a sponsorship-like environment for users, transforming the way interactions take place in the Web3 ecosystem. + +An example of using vouchers is shown in the [Battleship](/examples/Gaming/Battleship/battleship.md) game. Users without tokens in their balance can interact with a program by sending messages using a voucher, freeing them from the need to sign every transaction when interacting with the blockchain. + +## Understanding Gasless Transactions + +At the core of the Gasless Transactions feature lies the concept of vouchers. These vouchers are crafted to grant users the ability to send messages to specific programs within the network, all without the burden of gas fees. Each voucher comes with a predetermined allocation of gas, empowering users to initiate interactions without worrying about transaction costs. + +## How Gasless Transactions Work + +1. **Voucher Issuance**: Actors within the Vara Network can issue vouchers, creating a sponsorship mechanism for users. These vouchers are tied to specific programs and include a designated gas allocation. + +2. **Message Sending**: Holders of valid vouchers can use them to send messages to the designated program. These messages can include instructions or data, enriching interactions within the network. + +3. **Gas-Free Interactions**: Users who has valid vouchers can enjoy gas-free interactions when sending messages. The allocated gas from the voucher covers the associated transaction costs. + +Learn how to create and use vouchers in [this article](/docs/api/vouchers.md). + +## Signless dApp Interactions + +The signless transaction introduces another feature: anyone can interact with the dApp without needing to sign in. The dApp transaction operates in a manner similar to the steps outlined above, with one difference — a voucher is issued not directly to a user, but to a temporarily created account (sub-account) to which the user grants temporary rights to sign transactions on their behalf in this application. + +Vara's signless transactions further enhance the user experience. These transactions allow users to interact with dApps for a certain period without the need to individually sign each transaction. By eliminating the repetitive signing process, this approach streamlines interactions and significantly improves the overall UX efficiency. + +## Benefits of Gasless and Signless Transactions + +- Improved User Experience: The signless and gasless features simplify the interaction process, making it more accessible and user-friendly, akin to Web2 experiences. This attracts new users who might be daunted by the complexities of token management. +- Enhanced User Privacy: Users are not required to disclose their token balances when interacting with dApps, thus protecting their financial privacy. Individuals can contribute health data to research studies without revealing their identities. Additionally, signless dApps could facilitate anonymous voting systems, enhancing privacy and security for voters in elections. \ No newline at end of file diff --git a/docs/gear/distinctive-features.md b/docs/gear/features/message-automation.md similarity index 65% rename from docs/gear/distinctive-features.md rename to docs/gear/features/message-automation.md index 60b50cb78..963b4710f 100644 --- a/docs/gear/distinctive-features.md +++ b/docs/gear/features/message-automation.md @@ -1,9 +1,9 @@ --- -sidebar_position: 3 -sidebar_label: Gear Distinctive Features +sidebar_position: 2 +sidebar_label: Messaging automation --- -# Gear Distinctive Features +# Messaging automation ## Truly decentralized @@ -25,39 +25,6 @@ This opens up a wide range of possibilities for the implementation of functional Applications that use delayed messages in their business logic and their source code are shown in the [Program Examples](/examples/prerequisites.mdx) section. These include applications such as: [Tamagotchi battle](/examples/Gaming/tamagotchi-battle.md), [VaraTube](/examples/Infra/varatube.md), [Dynamic NFT](/examples/NFTs/dynamic-nft.md). -## Gasless and Signlesss Transactions - -Gear Protocol's introduction of gasless transactions, along with signless user interactions, presents a groundbreaking concept in the Web3 sphere. This innovation is revolutionizing communication within Gear-powered networks and boosting the adoption of decentralized applications. By making their usability comparable to Web2 services and applications, Gear Protocol significantly enhances user experience in the decentralized space. - -This innovative feature empowers actors to issue [vouchers](/api/vouchers.md) that enable specific users to send messages to designated programs without incurring gas fees. This paradigm-shifting approach fosters a sponsorship-like environment for users, transforming the way interactions take place in the Web3 ecosystem. - -An example of using vouchers is shown in the [Battleship](/examples/Gaming/Battleship/battleship.md) game. Users without tokens in their balance can interact with a program by sending messages using a voucher, freeing them from the need to sign every transaction when interacting with the blockchain. - -### Understanding Gasless Transactions - -At the core of the Gasless Transactions feature lies the concept of vouchers. These vouchers are crafted to grant users the ability to send messages to specific programs within the network, all without the burden of gas fees. Each voucher comes with a predetermined allocation of gas, empowering users to initiate interactions without worrying about transaction costs. - -### How Gasless Transactions Work - -1. **Voucher Issuance**: Actors within the Vara Network can issue vouchers, creating a sponsorship mechanism for users. These vouchers are tied to specific programs and include a designated gas allocation. - -2. **Message Sending**: Holders of valid vouchers can use them to send messages to the designated program. These messages can include instructions or data, enriching interactions within the network. - -3. **Gas-Free Interactions**: Users who has valid vouchers can enjoy gas-free interactions when sending messages. The allocated gas from the voucher covers the associated transaction costs. - -Learn how to create and use vouchers in [this article](/docs/api/vouchers.md). - -### Signless dApp Interactions - -The signless transaction introduces another feature: anyone can interact with the dApp without needing to sign in. The dApp transaction operates in a manner similar to the steps outlined above, with one difference — a voucher is issued not directly to a user, but to a temporarily created account (sub-account) to which the user grants temporary rights to sign transactions on their behalf in this application. - -Vara's signless transactions further enhance the user experience. These transactions allow users to interact with dApps for a certain period without the need to individually sign each transaction. By eliminating the repetitive signing process, this approach streamlines interactions and significantly improves the overall UX efficiency. - -### Benefits of Gasless and Signless Transactions - -- Improved User Experience: The signless and gasless features simplify the interaction process, making it more accessible and user-friendly, akin to Web2 experiences. This attracts new users who might be daunted by the complexities of token management. -- Enhanced User Privacy: Users are not required to disclose their token balances when interacting with dApps, thus protecting their financial privacy. Individuals can contribute health data to research studies without revealing their identities. Additionally, signless dApps could facilitate anonymous voting systems, enhancing privacy and security for voters in elections. - ## Use cases For instance, let's consider some use case examples that become achievable: @@ -93,4 +60,4 @@ Decentralized finance (DeFi) applications can improve the user experience by imp With the Gear Protocol, users can enjoy a set-and-forget DeFi experience where their earnings are automatically deposited into their accounts without any manual intervention. Rewards are regularly harvested, swapped for the original vault asset, and deposited again for compound farming, allowing users to earn even more without having to take any additional action. -In general, the use of delayed messages in DeFi can greatly improve the user experience by making it easier for users to earn rewards and take advantage of the benefits of DeFi without constantly having to monitor and manage their assets. This can help drive broader adoption of DeFi and unlock new opportunities for growth in the industry. +In general, the use of delayed messages in DeFi can greatly improve the user experience by making it easier for users to earn rewards and take advantage of the benefits of DeFi without constantly having to monitor and manage their assets. This can help drive broader adoption of DeFi and unlock new opportunities for growth in the industry. \ No newline at end of file diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/developing-contracts/gas-reservation.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/developing-contracts/gas-reservation.md index 8dadad4dd..496dd3c21 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/developing-contracts/gas-reservation.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/developing-contracts/gas-reservation.md @@ -4,7 +4,7 @@ sidebar_position: 8 # Gas 预留 -Gas 预留是 Gear 协议的强大功能，它为智能合约编程和现代[用例](../gear/distinctive-features)提供了新方法。 +Gas 预留是 Gear 协议的强大功能，它为智能合约编程和现代[用例](/docs/gear/features/message-automation.md)提供了新方法。 简单地说，程序可以使用之前预留的 gas 来发送消息，而不是使用当前处理的消息中的 gas。 From 0180d959dd761963a27861bdf5c603eb98193530 Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 16:57:13 +0200 Subject: [PATCH 2/8] Update docs/developing-contracts/builtinactors/bia-bls.md Co-authored-by: Dmitrii Novikov --- docs/developing-contracts/builtinactors/bia-bls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developing-contracts/builtinactors/bia-bls.md b/docs/developing-contracts/builtinactors/bia-bls.md index 8a217af7c..0aea0e4aa 100644 --- a/docs/developing-contracts/builtinactors/bia-bls.md +++ b/docs/developing-contracts/builtinactors/bia-bls.md @@ -7,7 +7,7 @@ sidebar_position: 2 [BLS12-381](https://github.com/gear-tech/gear/blob/master/pallets/gear-builtin/src/bls12_381.rs) is the first Built-in Actor integrated into the Vara runtime. It provides an interface that enables validators to perform native runtime computations of BLS cryptography methods. -BLS cryptography facilitates efficient signature aggregation and verification at scale using Elliptic Curve cryptography. However, these operations are computationally intensive, and the Wasm VM used in Gear is not capable of processing them quickly enough to fit within the single block time of Vara’s network (which is 3 seconds). +BLS cryptography facilitates efficient signature aggregation and verification at scale using Elliptic Curve cryptography. However, these operations are computationally intensive, and the Wasm VM used in Gear is not capable (without significant increase of minimal hardware requirements) of processing them quickly enough to fit within the single block time of Vara’s network (which is 3 seconds). The BLS12-381 Built-in Actor addresses this issue. A program on the blockchain can send a message to this actor's address with the necessary arguments for a BLS method call. The validator then executes this in native mode off-chain, which does not incur additional gas fees, and subsequently returns the result to the originating program that initiated the request. From 3387ebfbe0b9d6763b8168193814d1865a776015 Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 16:59:11 +0200 Subject: [PATCH 3/8] Update docs/developing-contracts/builtinactors/bia-bls.md Co-authored-by: Dmitrii Novikov --- docs/developing-contracts/builtinactors/bia-bls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developing-contracts/builtinactors/bia-bls.md b/docs/developing-contracts/builtinactors/bia-bls.md index 0aea0e4aa..7b8c2540e 100644 --- a/docs/developing-contracts/builtinactors/bia-bls.md +++ b/docs/developing-contracts/builtinactors/bia-bls.md @@ -9,7 +9,7 @@ sidebar_position: 2 BLS cryptography facilitates efficient signature aggregation and verification at scale using Elliptic Curve cryptography. However, these operations are computationally intensive, and the Wasm VM used in Gear is not capable (without significant increase of minimal hardware requirements) of processing them quickly enough to fit within the single block time of Vara’s network (which is 3 seconds). -The BLS12-381 Built-in Actor addresses this issue. A program on the blockchain can send a message to this actor's address with the necessary arguments for a BLS method call. The validator then executes this in native mode off-chain, which does not incur additional gas fees, and subsequently returns the result to the originating program that initiated the request. +The BLS12-381 Built-in Actor addresses this issue. A program on the blockchain can send a message to this actor's address with the necessary arguments for a BLS method call. The validator then executes this in native mode off-chain, and subsequently returns the result to the originating program that initiated the request. :::note While it is technically possible to execute BLS methods on-chain, doing so would occupy more than 30 blocks on the Vara network. This process would require complex optimization of the calculation algorithm, involving division into 30+ equivalent parts and would also result in higher gas costs. From eee5ecd30eb63d7037b98bde0f02bc3b968d48d3 Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 17:18:16 +0200 Subject: [PATCH 4/8] Update docs/developing-contracts/builtinactors/builtinactors.md Co-authored-by: Dmitrii Novikov --- docs/developing-contracts/builtinactors/builtinactors.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/developing-contracts/builtinactors/builtinactors.md b/docs/developing-contracts/builtinactors/builtinactors.md index 765f5253a..6f3ce8eca 100644 --- a/docs/developing-contracts/builtinactors/builtinactors.md +++ b/docs/developing-contracts/builtinactors/builtinactors.md @@ -22,5 +22,3 @@ Built-in actors each have a unique `BuiltinId`, similar to other actor addresses A set of unique `BuiltinActor`s is defined in the `pallet_gear_builtin_actor::Config` trait as an associated type — a tuple consisting of custom types, each of which must implement the `pallet_gear_builtin_actor::BuiltinActor` trait (similar to how migrations or signed extras are defined in the Runtime). These can be pallets (if access to on-chain storage is required) or any other custom types. The functionality provided by the `gear_builtin` pallet includes message routing to a specific built-in actor instead of stored programs. To achieve this, the actor must be registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). - -The pallet does not expose any dispatchable functions that can be called by users. \ No newline at end of file From f56e0480ce973435120ad28053d6c6c6a6f6958f Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 17:18:42 +0200 Subject: [PATCH 5/8] Update docs/gear/features/builtin-actors.md Co-authored-by: Dmitrii Novikov --- docs/gear/features/builtin-actors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gear/features/builtin-actors.md b/docs/gear/features/builtin-actors.md index edef88f46b..5ef786a44 100644 --- a/docs/gear/features/builtin-actors.md +++ b/docs/gear/features/builtin-actors.md @@ -6,7 +6,7 @@ sidebar_position: 4 # Built-in Actors ## Overview -[Built-In Actors](/docs/developing-contracts/builtinactors/builtinactors.md) are specialized entities within the Gear runtime that execute specific business logic when programs communicate with them via messages. This feature addresses a critical limitation: while users can directly interact with pallets through extrinsics like `bond`, `nominate`, `vote`, `transfer`, etc., programs within the Gear Protocol can only send messages, not extrinsics. +[Built-In Actors](/docs/developing-contracts/builtinactors/builtinactors.md) are specialized entities within the Gear runtime that execute specific business logic when programs communicate with them via messages. This feature addresses a critical limitation: while users can directly interact with pallets through extrinsics like `bond`, `nominate`, `vote`, etc., programs within the Gear Protocol can only send messages, not extrinsics. ## Purpose and Operation of BIAs From 51f1bb50baf2eeb3a4987f5d8af0b302b691a66f Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 17:24:11 +0200 Subject: [PATCH 6/8] Update docs/developing-contracts/builtinactors/builtinactors.md Co-authored-by: Dmitrii Novikov --- docs/developing-contracts/builtinactors/builtinactors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developing-contracts/builtinactors/builtinactors.md b/docs/developing-contracts/builtinactors/builtinactors.md index 6f3ce8eca..fd3009650 100644 --- a/docs/developing-contracts/builtinactors/builtinactors.md +++ b/docs/developing-contracts/builtinactors/builtinactors.md @@ -19,6 +19,6 @@ Built-in Actors can be added by the developers of the Gear Protocol, as they are Built-in actors each have a unique `BuiltinId`, similar to other actor addresses in the network (like `ProgramId`). These IDs can be used by other programs to send specifically formatted messages to perform actions related to the blockchain logic implemented in the `Runtime`. -A set of unique `BuiltinActor`s is defined in the `pallet_gear_builtin_actor::Config` trait as an associated type — a tuple consisting of custom types, each of which must implement the `pallet_gear_builtin_actor::BuiltinActor` trait (similar to how migrations or signed extras are defined in the Runtime). These can be pallets (if access to on-chain storage is required) or any other custom types. +A set of unique `BuiltinActor`s is defined in the `pallet_gear_builtin_actor::Config` trait as an associated type — a tuple consisting of custom types, each of which must implement the `pallet_gear_builtin::BuiltinActor` trait (similar to how migrations or signed extras are defined in the Runtime). These can be pallets (if access to on-chain storage is required) or any other custom types. The functionality provided by the `gear_builtin` pallet includes message routing to a specific built-in actor instead of stored programs. To achieve this, the actor must be registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). From fd5c31dc3a9cc99695610a82521c4e74f03ac106 Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 17:25:57 +0200 Subject: [PATCH 7/8] Update docs/developing-contracts/builtinactors/builtinactors.md Co-authored-by: Dmitrii Novikov --- docs/developing-contracts/builtinactors/builtinactors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developing-contracts/builtinactors/builtinactors.md b/docs/developing-contracts/builtinactors/builtinactors.md index fd3009650..f089b82d0 100644 --- a/docs/developing-contracts/builtinactors/builtinactors.md +++ b/docs/developing-contracts/builtinactors/builtinactors.md @@ -21,4 +21,4 @@ Built-in actors each have a unique `BuiltinId`, similar to other actor addresses A set of unique `BuiltinActor`s is defined in the `pallet_gear_builtin_actor::Config` trait as an associated type — a tuple consisting of custom types, each of which must implement the `pallet_gear_builtin::BuiltinActor` trait (similar to how migrations or signed extras are defined in the Runtime). These can be pallets (if access to on-chain storage is required) or any other custom types. -The functionality provided by the `gear_builtin` pallet includes message routing to a specific built-in actor instead of stored programs. To achieve this, the actor must be registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). +The functionality provided by the `gear_builtin` pallet includes message routing to a specific built-in actor instead of stored programs. To achieve this, the actor is automatically registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). From 2f70a85b472e49c801ed80c84c6b9aefdbe2ce89 Mon Sep 17 00:00:00 2001 From: AndrePanin Date: Sat, 27 Apr 2024 17:34:29 +0200 Subject: [PATCH 8/8] Comments addressed --- docs/developing-contracts/builtinactors/builtinactors.md | 8 ++++---- docs/gear/features/builtin-actors.md | 5 +---- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/developing-contracts/builtinactors/builtinactors.md b/docs/developing-contracts/builtinactors/builtinactors.md index f089b82d0..28ddc6e62 100644 --- a/docs/developing-contracts/builtinactors/builtinactors.md +++ b/docs/developing-contracts/builtinactors/builtinactors.md @@ -7,9 +7,9 @@ sidebar_position: 1 ## Overview -The Built-in Actors framework is an extensible system that provides a registry of built-in actors available in the Gear node runtime. It is implemented as a runtime [pallet](https://github.com/gear-tech/gear/tree/master/pallets/gear-builtin) capable of handling messages from other actors (programs) and process them in applications built on top of blockchain logic (such as staking, governance, computationally intensive calculations and more). This framework allows for the integration of custom logic, including access to the node's operating system and native execution. +The Built-in Actors framework is an extensible system that provides a registry of built-in actors available in the Gear node runtime. Built-in Actors are programs (but not a Wasm programs) implemented as a runtime [pallet](https://github.com/gear-tech/gear/tree/master/pallets/gear-builtin) capable of handling messages from other actors (programs) and process them in applications built on top of blockchain logic (such as staking, governance, computationally intensive calculations and more). This framework allows for the integration of custom logic, including access to the node's operating system and native execution. -New Built-in Actors may be added during runtime upgrades. Since the calculations for Built-in Actors are performed within the runtime interface of the node, upgrading the node client is essential to import blocks and maintain onchain functionality. +Built-in Actors may be added, removed, updated (including address change) by the Gear Protocol's development team during runtime upgrades. If a new runtime interface added with a Built-in Actor, upgrading the node client is essential to import blocks and maintain onchain functionality. :::note Built-in Actors can be added by the developers of the Gear Protocol, as they are part of the runtime. They cannot be created by any other program or initiated by users. However, they are accessible to everyone like any other program through messaging. @@ -17,8 +17,8 @@ Built-in Actors can be added by the developers of the Gear Protocol, as they are ## Usage -Built-in actors each have a unique `BuiltinId`, similar to other actor addresses in the network (like `ProgramId`). These IDs can be used by other programs to send specifically formatted messages to perform actions related to the blockchain logic implemented in the `Runtime`. +Built-in actors each have a unique `BuiltinId`. These IDs can be used by other programs to send specifically formatted messages to perform actions related to the blockchain logic implemented in the `Runtime`. `BuiltinId` is like an index of BIA, and with special RPC call it can be converted into the `ProgramId` to get trusted and valid program id from on-chain. A set of unique `BuiltinActor`s is defined in the `pallet_gear_builtin_actor::Config` trait as an associated type — a tuple consisting of custom types, each of which must implement the `pallet_gear_builtin::BuiltinActor` trait (similar to how migrations or signed extras are defined in the Runtime). These can be pallets (if access to on-chain storage is required) or any other custom types. -The functionality provided by the `gear_builtin` pallet includes message routing to a specific built-in actor instead of stored programs. To achieve this, the actor is automatically registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). +When the next message is dequeued, a runtime checks the destination. If it is BIA, the runtime calls the respective BIA with the messages. Otherwise, it searches the storage for the Wasm program by address and executes it. The functionality of routing to a specific built-in actor instead of stored programs is provided by the `gear_builtin` pallet. To achieve this, the actor is automatically registered with the `pallet_gear::Config::::BuiltinRouter` associated type that implements the `pallet_gear::builtin::BuiltinRouter` trait and provides the `lookup()` function. This function is used to derive the respective `BuiltinId` based on the message's destination address (`ProgramId`). diff --git a/docs/gear/features/builtin-actors.md b/docs/gear/features/builtin-actors.md index 5ef786a44..58b67ee8d 100644 --- a/docs/gear/features/builtin-actors.md +++ b/docs/gear/features/builtin-actors.md @@ -29,7 +29,7 @@ BIAs allow programs to interact with existing Substrate pallets and others (like This provides dApp developers with a powerful mechanism for automating scenarios and implementing custom logic in programs. For instance, BIAs provides acceess to the `staking` pallet for programs, facilitating the creation of automated staking. ### Intensive Computations -BIAs offload intensive computational tasks from the programs, efficiently handling them at the node level to minimize gas costs and execution time. This is crucial for operations that exceed the gas limit of a single block or require extensive computational resources, such as cryptographic verifications or neural network tasks. +BIAs offload intensive computational tasks from the programs, efficiently handling them at the node level to minimize gas costs and execution time. This is crucial for operations that exceed the gas limit of a single block or require extensive computational resources, such as cryptographic verifications or neural network tasks. Some examples where BIAs can be theoretically used: - For instance, cryptographic computations like BLS signature verification. BIAs designed for such computations perform them efficiently and cost-effectively at the node level. - Simple operations like SHA-256 hashing are executed much faster through a BIA than in an on-chain program. - BIAs can also manage neural network operations, image generation, and pattern recognition from program inputs. @@ -40,8 +40,5 @@ A BIA pallet can implement a cross-chain bridge logic that receives messages fro The BIA can also be used to accelerate primitives for verifying ZK proofs through ECC (Elliptic Curve Cryptography), performing these calculations efficiently at the node level because they are too intensive for on-chain execution within gas limits. -### Arbitrary Storage -If a dApp developer prefers not to write data directly into the on-chain program's memory, a BIA can serve as an efficient storage solution. - ## Conclusion BIAs elevate the capabilities of programs (smart contracts) to the user level. Features typically implemented through pallets and accessible only through extrinsics are now available to programs. This includes using balances for governance voting, issuing vouchers, allowing other actors to perform operations on behalf of the program (proxying), conducting complex computations, and much more. This expansion significantly enhances the functionality and potential applications of blockchain programs. \ No newline at end of file