Add Built-in Actors

docs/developing-contracts/builtinactors/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Built-in Actors",
+    "position": 12
+  }
+

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.
+:::

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::<T>::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.

docs/developing-contracts/deploy.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Upload Program
-sidebar_position: 12
+sidebar_position: 13
 ---
 
 # Upload program

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.
 

docs/developing-contracts/standards/_category_.json

@@ -1,5 +1,5 @@
 {
     "label": "Standards",
-    "position": 16
+    "position": 17
   }
 

docs/developing-contracts/testing-gclient.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 16
 ---
 
 import Tabs from '@theme/Tabs';

docs/developing-contracts/testing-gtest.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 15
 ---
 
 # Testing with `gtest`

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

docs/gear/features/_category_.json

@@ -0,0 +1,4 @@
+  {
+    "label": "Gear Distinctive Features",
+    "position": 2
+  }

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.

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.

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.