diff --git a/docs/examples/Standards/extended-vft.md b/docs/examples/Standards/extended-vft.md deleted file mode 100644 index f4e3056..0000000 --- a/docs/examples/Standards/extended-vft.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -sidebar_label: EXTENDED VFT (ERC-20) -sidebar_position: 2 ---- - -# Extended Vara Fungible Token - -This article is dedicated to the extension of the VFT standard as discussed in the paper [Vara fungible tokens - VFT](vft.md). Specifically, it will implement the mint and burn functionalities. However, this example should be considered as an illustrative implementation, as extensions to the standard may take various forms. - -For a more detailed implementation, the code related to this article can be found on [GitHub](https://github.com/gear-foundation/standards/tree/master/extended-vft). - -## Possible additional features - -``` - Mint(to, value) - Burn(from, value) - GrantAdminRole(to) - GrantBurnerRole(to) - GrantMinterRole(to) - RevokeAdminRole(from) - RevokeBurnerRole(from) - RevokeMinterRole(from) - Admins() - Burners() - Minters() -``` - -## Possible additional events - -``` - Minted(to, value) - Burned(from, value) -``` - -## Implementation details - -To extend the functionality, it is necessary to add the existing VFT standard in the `Cargo.toml` file - -```toml -vft-service = { git = "https://github.com/gear-foundation/standards" } -``` - -After adding the necessary dependency to `Cargo.toml`, a new service can be created in the extended version that includes the old one - -```rust -use vft_service::Service as VftService; - -pub struct ExtendedService { - vft: VftService, -} -``` - -In order to extend the functionality it is necessary to use the extends argument in the `#[service]` attribute, *ExtendedService* then inherits the methods and properties of *VftService*. This means that all functionality provided by the *VftService* will now be available in the *ExtendedService*. - -```rust -#[service(extends = VftService, events = Event)] -impl ExtendedService { - // Realization of new functionality -} -``` - -The `events = Event` part indicates that *ExtendedService* will handle events specified in the `Event` structure. These events can be emitted during the execution of the service’s methods. - -```rust -pub enum Event { - Minted { to: ActorId, value: U256 }, - Burned { from: ActorId, value: U256 }, -} -``` - -Overall, the implementation of new methods in the extended version takes the following form: - -```rust -#[service(extends = VftService, events = Event)] -impl ExtendedService { - pub fn new() -> Self { - Self { - vft: VftService::new(), - } - } - pub fn mint(&mut self, to: ActorId, value: U256) -> bool { - if !self.get().minters.contains(&msg::source()) { - panic!("Not allowed to mint") - }; - - let mutated = services::utils::panicking(|| { - funcs::mint(Storage::balances(), Storage::total_supply(), to, value) - }); - if mutated { - let _ = self.notify_on(Event::Minted { to, value }); - } - mutated - } - - pub fn burn(&mut self, from: ActorId, value: U256) -> bool { - if !self.get().burners.contains(&msg::source()) { - panic!("Not allowed to burn") - }; - - let mutated = services::utils::panicking(|| { - funcs::burn(Storage::balances(), Storage::total_supply(), from, value) - }); - if mutated { - let _ = self.notify_on(Event::Burned { from, value }); - } - mutated - } - - pub fn grant_admin_role(&mut self, to: ActorId) { - self.ensure_is_admin(); - self.get_mut().admins.insert(to); - } - pub fn grant_minter_role(&mut self, to: ActorId) { - self.ensure_is_admin(); - self.get_mut().minters.insert(to); - } - pub fn grant_burner_role(&mut self, to: ActorId) { - self.ensure_is_admin(); - self.get_mut().burners.insert(to); - } - - pub fn revoke_admin_role(&mut self, from: ActorId) { - self.ensure_is_admin(); - self.get_mut().admins.remove(&from); - } - pub fn revoke_minter_role(&mut self, from: ActorId) { - self.ensure_is_admin(); - self.get_mut().minters.remove(&from); - } - pub fn revoke_burner_role(&mut self, from: ActorId) { - self.ensure_is_admin(); - self.get_mut().burners.remove(&from); - } - pub fn minters(&self) -> Vec { - self.get().minters.clone().into_iter().collect() - } - - pub fn burners(&self) -> Vec { - self.get().burners.clone().into_iter().collect() - } - - pub fn admins(&self) -> Vec { - self.get().admins.clone().into_iter().collect() - } -} -``` - -## Key methods - -### `Mint` - -```rust -pub fn mint(&mut self, to: ActorId, value: U256) -> bool -``` - -Mints new tokens and assigns them to the specified actor (to). It first checks if the caller has the minter role. If the minting is successful, it triggers a `Minted` event. - -### `Burn` - -```rust -pub fn burn(&mut self, from: ActorId, value: U256) -> bool -``` - -Burns tokens from the specified actor (from). It checks if the caller has the burner role. If the burning is successful, it triggers a `Burned` event. - -### `Grant admin role` - -```rust -pub fn grant_admin_role(&mut self, to: ActorId) -``` - -Grants the admin role to the specified actor (to). This function can only be called by an existing admin. - -### `Grant minter role` - -```rust -pub fn grant_minter_role(&mut self, to: ActorId) -``` - -Grants the minter role to the specified actor (to). This function can only be called by an existing admin. - -### `Grant burner role` - -```rust -pub fn grant_burner_role(&mut self, to: ActorId) -``` - -Grants the burner role to the specified actor (to). This function can only be called by an existing admin. - -### `Revoke admin role` - -```rust -pub fn revoke_admin_role(&mut self, from: ActorId) -``` - -Revokes the admin role from the specified actor (from). This function can only be called by an existing admin. - -### `Revoke minter role` - -```rust -pub fn revoke_minter_role(&mut self, from: ActorId) -``` - -Revokes the minter role from the specified actor (from). This function can only be called by an existing admin. - -### `Revoke burner role` - -```rust -pub fn revoke_burner_role(&mut self, from: ActorId) -``` - -Revokes the burner role from the specified actor (from). This function can only be called by an existing admin. - - -## Query methods - -### `minters` - -Returns a list of all actors who have the minter role. - -```rust -pub fn minters(&self) -> Vec -``` - -### `burners` - -Returns a list of all actors who have the burner role. - -```rust -pub fn burners(&self) -> Vec -``` - -### `admins` - -Returns a list of all actors who have the admin role. - -```rust -pub fn admins(&self) -> Vec -``` - -## Contract Interface - -```rust -constructor { - New : (name: str, symbol: str, decimals: u8); -}; - -service Vft { - Burn : (from: actor_id, value: u256) -> bool; - GrantAdminRole : (to: actor_id) -> null; - GrantBurnerRole : (to: actor_id) -> null; - GrantMinterRole : (to: actor_id) -> null; - Mint : (to: actor_id, value: u256) -> bool; - RevokeAdminRole : (from: actor_id) -> null; - RevokeBurnerRole : (from: actor_id) -> null; - RevokeMinterRole : (from: actor_id) -> null; - Approve : (spender: actor_id, value: u256) -> bool; - Transfer : (to: actor_id, value: u256) -> bool; - TransferFrom : (from: actor_id, to: actor_id, value: u256) -> bool; - query Admins : () -> vec actor_id; - query Burners : () -> vec actor_id; - query Minters : () -> vec actor_id; - query Allowance : (owner: actor_id, spender: actor_id) -> u256; - query BalanceOf : (account: actor_id) -> u256; - query Decimals : () -> u8; - query Name : () -> str; - query Symbol : () -> str; - query TotalSupply : () -> u256; - - events { - Minted: struct { to: actor_id, value: u256 }; - Burned: struct { from: actor_id, value: u256 }; - Approval: struct { owner: actor_id, spender: actor_id, value: u256 }; - Transfer: struct { from: actor_id, to: actor_id, value: u256 }; - } -}; -``` - -:::note -It incorporates methods and events from the core standard, seamlessly integrating them into advanced functionality. -::: - - -## Conclusion - -This implementation exemplifies a potential extension of the standard VFT framework. It illustrates the addition of minting and burning functionalities, underscoring the flexibility for further adaptations and enhancements to the standard. Developers can leverage this example as a foundational reference for exploring and implementing custom extensions tailored to specific use cases within the VFT ecosystem. diff --git a/docs/examples/Standards/vft.md b/docs/examples/Standards/vft.md index 779f7c1..1d30dca 100644 --- a/docs/examples/Standards/vft.md +++ b/docs/examples/Standards/vft.md @@ -3,97 +3,69 @@ sidebar_label: VFT (ERC-20) sidebar_position: 1 --- -# Vara Fungible Token +# Vara Fungible Token (VFT) Standard and Extended Implementation :::note The Vara Fungible Token Standard is the analogue of ERC-20 on Ethereum. ::: -The Vara Fungible Token Standard provides a unified API for smart contracts to implement token functionalities. It encompasses critical operations like token transfer and approvals for third-party spending on the blockchain. Below, we detail the contract state, its interface, and key methods to facilitate these operations. +The Vara Fungible Token Standard outlines a unified API for implementing fungible token functionalities in programs. The initial section of this document provides a comprehensive examination of the core VFT service, which serves as a foundational framework. It covers essential operations such as token transfers and approvals for third-party spending, detailing the contract state, interface, and key methods involved. -An example implementation of the VFT standard is available on [GitHub](https://github.com/gear-foundation/standards/tree/master/vft-service). +The subsequent section expands on how to leverage and extend this core service to develop a fully functional token application. It illustrates the process of adding advanced features like minting and burning, demonstrating how to build upon the core VFT service to create a comprehensive and customizable token system. This extension highlights the flexibility and potential of the core standard, providing a pathway to develop more sophisticated and tailored token solutions. -## Functions +## Core VFT Service -``` - Approve(spender, value) - Transfer(to, value) - TransferFrom(from, to, value) - Allowance(owner, spender) - BalanceOf(owner) - Decimals() - Name() - Symbol() - TotalSupply() +### Functions -``` +The VFT service includes the following functions: -## Events +- `Approve(spender, value)` +- `Transfer(to, value)` +- `TransferFrom(from, to, value)` +- `Allowance(owner, spender)` +- `BalanceOf(owner)` +- `Decimals()` +- `Name()` +- `Symbol()` +- `TotalSupply()` -``` - Approval(owner, spender, value); - Transfer(from, to, value); -``` +### Events -## Key methods +The core service also defines the following events: -### `Approve` +- `Approval(owner, spender, value)` +- `Transfer(from, to, value)` -```rust -pub fn approve(&mut self, spender: ActorId, value: U256) -> bool -``` - -This function allows a designated spender (`spender`) to withdraw up to an `value` of tokens from your account, multiple times up to the amount limit. Resets allowance to `value` with a subsequent call. Returns a boolean value indicating whether the operation succeeded. +### Key Methods -Upon successful execution, triggers the event: +#### `Approve` ```rust -Approval { - owner: ActorId, - spender: ActorId, - value: U256, -} +pub fn approve(&mut self, spender: ActorId, value: U256) -> bool ``` -### `Transfer` +This function allows a designated spender to withdraw up to a specified value of tokens from the caller's account, multiple times up to the specified amount. A subsequent call resets the allowance to the new value. A boolean value indicates the success of the operation, and the function triggers an `Approval` event upon successful execution. + +#### `Transfer` ```rust pub fn transfer(&mut self, to: ActorId, value: U256) -> bool ``` +This function transfers a specified value of tokens to a designated account. It returns a boolean value indicating the success of the operation and triggers a `Transfer` event upon successful execution. -Transfers the specified `value` of tokens to the account `to`. Returns a boolean value indicating whether the operation - -Upon successful execution generates the event: - -```rust -Transfer { - from: ActorId, - to: ActorId, - value: U256, -} -``` - -### `TransferFrom` +#### `TransferFrom` ```rust pub fn transfer_from(&mut self, from: ActorId, to: ActorId, value: U256) -> bool ``` -Transfers a specified `value` of tokens `from` one account `to` another, using the allowance mechanism. Value is then deducted from the caller’s allowance. Returns a boolean value indicating whether the operation succeeded. -Upon successful execution generates the event: +This function transfers a specified value of tokens from one account to another, using the allowance mechanism. The transferred value is deducted from the caller’s allowance. A boolean value indicates the success of the operation, and a `Transfer` event is generated upon successful execution. -```rust -Transfer { - from: ActorId, - to: ActorId, - value: U256, -} -``` -## Query methods +### Query methods -### `name` +#### `name` Returns the name of the token. @@ -101,7 +73,7 @@ Returns the name of the token. pub fn name(&self) -> String ``` -### `symbol` +#### `symbol` Returns the symbol of the token. @@ -109,7 +81,7 @@ Returns the symbol of the token. pub fn symbol(&self) -> String ``` -### `decimals` +#### `decimals` Returns the decimals of the token. @@ -117,7 +89,7 @@ Returns the decimals of the token. pub fn decimals(&self) -> u8 ``` -### `total_supply` +#### `total_supply` Returns the total supply of the token. @@ -125,7 +97,7 @@ Returns the total supply of the token. pub fn total_supply(&self) -> U256 ``` -### `balance_of` +#### `balance_of` Returns the token balance of the `owner` address. @@ -133,16 +105,170 @@ Returns the token balance of the `owner` address. pub fn balance_of(&self, account: ActorId) -> U256 ``` -### `allowance` +#### `allowance` Returns the number of tokens the `spender` account is authorized to spend on behalf of the `owner`. ```rust pub fn allowance(&self, owner: ActorId, spender: ActorId) -> U256 +``` + + + +:::note + +The service provided here is not a complete application but serves as a foundational base or core for creating your own token. It can be extended and inherited to add additional functionality, allowing developers to build upon this framework. The code for this service is available on [GitHub](https://github.com/gear-foundation/standards/tree/master/vft-service). The extended version demonstrates how to utilize this base service to create a fully functional application, showcasing the process of expanding its capabilities into a finished program. + +::: + +## Extended VFT Implementation + +### Additional Features + +The extended implementation introduces new functions and events that enhance the basic VFT service. The additional features include: + +#### Functions + +- `Mint(to, value)` +- `Burn(from, value)` +- `GrantAdminRole(to)` +- `GrantBurnerRole(to)` +- `GrantMinterRole(to)` +- `RevokeAdminRole(from)` +- `RevokeBurnerRole(from)` +- `RevokeMinterRole(from)` +- `Admins()` +- `Burners()` +- `Minters()` + +#### Events + +- `Minted(to, value)` +- `Burned(from, value)` + +### Implementation Details + +To incorporate the extended functionality, the VFT service is first added as a dependency in the `Cargo.toml` file: + +```toml +vft-service = { git = "https://github.com/gear-foundation/standards" } +``` + +A new service is created that extends the existing VFT service: + +```rust +use vft_service::Service as VftService; + +pub struct ExtendedService { + vft: VftService, +} ``` -## Conclusion +The `#[service(extends = VftService, events = Event)]` attribute is used to ensure that the `ExtendedService` inherits methods and properties from `VftService`, making all core functionalities available within the extended service. + +### Key Methods + +#### `Mint` + +```rust +pub fn mint(&mut self, to: ActorId, value: U256) -> bool +``` + +This function mints new tokens and assigns them to a specified actor. The function checks if the caller has the minter role and triggers a `Minted` event if the minting is successful. + +#### `Burn` + +```rust +pub fn burn(&mut self, from: ActorId, value: U256) -> bool +``` + +This function burns tokens from a specified actor. It checks if the caller has the burner role and triggers a `Burned` event if the burning is successful. + +#### Role Management + +- `grant_admin_role(&mut self, to: ActorId)` +- `grant_minter_role(&mut self, to: ActorId)` +- `grant_burner_role(&mut self, to: ActorId)` +- `revoke_admin_role(&mut self, from: ActorId)` +- `revoke_minter_role(&mut self, from: ActorId)` +- `revoke_burner_role(&mut self, from: ActorId)` + +These methods manage the assignment and revocation of administrative, minting, and burning roles, ensuring that only authorized actors can perform sensitive operations. + +### Query methods + +#### `minters` + +Returns a list of all actors who have the minter role. + +```rust +pub fn minters(&self) -> Vec +``` + +#### `burners` + +Returns a list of all actors who have the burner role. + +```rust +pub fn burners(&self) -> Vec +``` + +#### `admins` + +Returns a list of all actors who have the admin role. + +```rust +pub fn admins(&self) -> Vec +``` + +### Contract Interface + +The extended service incorporates the following interface: + +```rust +constructor { + New : (name: str, symbol: str, decimals: u8); +}; + +service Vft { + Burn : (from: actor_id, value: u256) -> bool; + GrantAdminRole : (to: actor_id) -> null; + GrantBurnerRole : (to: actor_id) -> null; + GrantMinterRole : (to: actor_id) -> null; + Mint : (to: actor_id, value: u256) -> bool; + RevokeAdminRole : (from: actor_id) -> null; + RevokeBurnerRole : (from: actor_id) -> null; + RevokeMinterRole : (from: actor_id) -> null; + Approve : (spender: actor_id, value: u256) -> bool; + Transfer : (to: actor_id, value: u256) -> bool; + TransferFrom : (from: actor_id, to: actor_id, value: u256) -> bool; + query Admins : () -> vec actor_id; + query Burners : () -> vec actor_id; + query Minters : () -> vec actor_id; + query Allowance : (owner: actor_id, spender: actor_id) -> u256; + query BalanceOf : (account: actor_id) -> u256; + query Decimals : () -> u8; + query Name : () -> str; + query Symbol : () -> str; + query TotalSupply : () -> u256; + + events { + Minted: struct { to: actor_id, value: u256 }; + Burned: struct { from: actor_id, value: u256 }; + Approval: struct { owner: actor_id, spender: actor_id, value: u256 }; + Transfer: struct { from: actor_id, to: actor_id, value: u256 }; + } +}; +``` + +:::note + +The Extended VFT implementation illustrates how the core VFT service can be expanded to incorporate advanced features like minting, burning, and role management. This extension provides a versatile framework that developers can adapt to meet specific use cases, enabling more robust and feature-rich token systems. By leveraging these additional capabilities, the Extended VFT offers a comprehensive foundation for creating custom token solutions within the Vara ecosystem. + +For a more detailed implementation, the code for the Extended VFT can be found on [GitHub](https://github.com/gear-foundation/standards/tree/master/extended-vft). + +::: -By adhering to this standard, smart contracts can ensure interoperability and provide a consistent user experience across different platforms and applications within the blockchain ecosystem. +## Conclusion -Using this standard, dApp developers can ensure that their in-app tokens, built on the basis of this standard, will be natively displayed in user wallets without requiring additional integration efforts, assuming that wallet applications also support this standard. +The core VFT service establishes a robust foundation for implementing fungible tokens within the Vara ecosystem, encompassing essential functionalities that adhere to recognized token standards. This service functions as a fundamental core, with the Extended VFT illustrating how it can be expanded to incorporate advanced capabilities, including minting, burning, and role management. Together, these implementations provide a comprehensive framework for developers, facilitating the creation of tailored and sophisticated token systems. By utilizing both the core service and its extended functionalities, developers are well-positioned to design flexible and secure token solutions that address specific requirements and enhance overall system capabilities.