From 76a9f29189475b42defff3780ae9aa17143ee0f2 Mon Sep 17 00:00:00 2001 From: garikbesson Date: Fri, 31 Oct 2025 12:36:18 +0000 Subject: [PATCH 1/5] Init tutorial how to use contract tools package to create FT --- docs/tutorials/examples/ft-contract-tools.md | 104 +++++++++++++++++++ website/sidebars.js | 1 + 2 files changed, 105 insertions(+) create mode 100644 docs/tutorials/examples/ft-contract-tools.md diff --git a/docs/tutorials/examples/ft-contract-tools.md b/docs/tutorials/examples/ft-contract-tools.md new file mode 100644 index 00000000000..0aed59dc13b --- /dev/null +++ b/docs/tutorials/examples/ft-contract-tools.md @@ -0,0 +1,104 @@ +--- +id: ft-contract-tools +title: Create FT using Contract Tools +sidebar_label: Create FT using Contract Tools +description: "Learn how to create a fungible token (FT) using Contract Tools package" +--- + +import {Github} from "@site/src/components/UI/Codetabs"; +import MovingForwardSupportSection from '@site/src/components/MovingForwardSupportSection'; + +In this tutorial, we will create a fungible token (FT) using [Contract Tools](https://github.com/near/near-sdk-contract-tools) package. This package is a collection of common tools and patterns in NEAR smart contract development: + +- Storage fee management. +- Escrow pattern and derive macro. +- Owner pattern and derive macro. +- Pause pattern and derive macro. +- Role-based access control. +- Derive macros for NEP standards: + - NEP-141 (fungible token), extension NEP-148. + - NEP-145 (storage management), and integrations for the fungible token and non-fungible token standards. + - NEP-171 (non-fungible token), extensions NEP-177, NEP-178, NEP-181. + - NEP-297 (events). + +--- + +## Introduction + +The difference of this example from the [FT contract](https://github.com/near-examples/FT) based on `near_contract_standards` package is the approach of using deriving macros to implement NEP standards and common patterns. + +When we use deriving macros, we can bring `near_contract_standards` implementations into our contract without writing boilerplate code for the each method. That allows us to focus on the unique logic of our contract like minting/burning logic, access control, other custom features. So, this collection of common tools and patterns (mostly in the form of derive macros) is as a sort of OpenZeppelin for NEAR. + +--- + +## Basic FT Methods + +To derive basic FT methods to our contract, we need to derive `FungibleToken` macro to our contract struct: + + + +This will bring all the basic FT methods defined in NEP-141 standard to our contract: +- `new` +- `contract_source_metadata` +- `ft_balance_of` +- `ft_metadata` +- `ft_total_supply` +- `storage_balance_bounds` +- `storage_balance_of` +- `ft_resolve_transfer` +- `ft_transfer` +- `ft_transfer_call` +- `storage_deposit` +- `storage_unregister` +- `storage_withdraw` + +To bring basic owner methods to our contract, we derived also `Owner` macro which adds the following methods: +- `own_get_owner` +- `own_get_proposed_owner` +- `own_accept_owner` +- `own_propose_owner` +- `own_renounce_owner` + +--- + +## Initialization + +To initialize the basic FT contract with custom owner, metadata and storage bounds implement `new` method: + + + +--- + +## Minting + +To mint initial supply of tokens to the owner implement `mint` method and restrict access only to the owner of the contract: + + + +:::tip +You can modify this method as you need, for example, to allow minting only when the contract is not paused (requires deriving [`Pausable`](https://github.com/near/near-sdk-contract-tools/tree/develop?tab=readme-ov-file#macro-combinations) hook), or to allow minting only to specific accounts with a certain role or from whitelist with custom limitations. +::: + +--- + +## Burning + +To burn tokens from the owner's account, we implement `burn` method and also restrict access: + + + +--- + +## Conclusion + +Using `near-sdk-contract-tools` is very simple and flexible way to create FT contract with minimal boilerplate code and focusing on business logic. You can further extend this contract with more features like pausing, role-based access control, escrow pattern, and more by deriving corresponding macros from the package. + + \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index 29e6f58744e..a261cd9da84 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -300,6 +300,7 @@ const sidebar = { 'tutorials/examples/advanced-xcc', 'tutorials/examples/global-contracts', 'tutorials/examples/update-contract-migrate-state', + 'tutorials/examples/ft-contract-tools', { "Build a FT Contract from Scratch": [ 'tutorials/fts/introduction', From 6f35fb51c6dda7ba06972ba6b50f6b6031083b73 Mon Sep 17 00:00:00 2001 From: garikbesson Date: Tue, 4 Nov 2025 13:07:39 +0000 Subject: [PATCH 2/5] update tutorial --- docs/tutorials/examples/ft-contract-tools.md | 38 ++++++++++++++------ 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/examples/ft-contract-tools.md b/docs/tutorials/examples/ft-contract-tools.md index 0aed59dc13b..b1deaccc1e6 100644 --- a/docs/tutorials/examples/ft-contract-tools.md +++ b/docs/tutorials/examples/ft-contract-tools.md @@ -35,9 +35,9 @@ When we use deriving macros, we can bring `near_contract_standards` implementati To derive basic FT methods to our contract, we need to derive `FungibleToken` macro to our contract struct: - + start="9" end="12" /> This will bring all the basic FT methods defined in NEP-141 standard to our contract: - `new` @@ -67,19 +67,35 @@ To bring basic owner methods to our contract, we derived also `Owner` macro whic To initialize the basic FT contract with custom owner, metadata and storage bounds implement `new` method: - + start="14" end="35" /> --- -## Minting +## Transfer Hook + +To add custom logic on transfer method, we need to implement a hook. Hooks are a way to wrap (inject code before and after) component functions: + + -To mint initial supply of tokens to the owner implement `mint` method and restrict access only to the owner of the contract: +Then derive it to our contract struct: - + start="9" end="12" /> + +--- + +## Minting + +To mint additional supply of tokens to the owner implement `mint` method and restrict access only to the owner of the contract: + + :::tip You can modify this method as you need, for example, to allow minting only when the contract is not paused (requires deriving [`Pausable`](https://github.com/near/near-sdk-contract-tools/tree/develop?tab=readme-ov-file#macro-combinations) hook), or to allow minting only to specific accounts with a certain role or from whitelist with custom limitations. @@ -91,9 +107,9 @@ You can modify this method as you need, for example, to allow minting only when To burn tokens from the owner's account, we implement `burn` method and also restrict access: - + --- From 0de2caaf6b23107fecbc6d44414dc0406a962d12 Mon Sep 17 00:00:00 2001 From: garikbesson Date: Fri, 7 Nov 2025 12:08:00 +0000 Subject: [PATCH 3/5] fix code snippets lines --- docs/tutorials/examples/ft-contract-tools.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/examples/ft-contract-tools.md b/docs/tutorials/examples/ft-contract-tools.md index b1deaccc1e6..42d5d65e48d 100644 --- a/docs/tutorials/examples/ft-contract-tools.md +++ b/docs/tutorials/examples/ft-contract-tools.md @@ -69,7 +69,7 @@ To initialize the basic FT contract with custom owner, metadata and storage boun + start="14" end="45" /> --- @@ -109,7 +109,7 @@ To burn tokens from the owner's account, we implement `burn` method and also res + start="5" end="25" /> --- From f45e3bda234e049ed93ab1572dfd38b1ce6091ab Mon Sep 17 00:00:00 2001 From: Guillermo Alejandro Gallardo Diez Date: Tue, 11 Nov 2025 15:00:31 +0100 Subject: [PATCH 4/5] fix: small text corrections --- docs/tutorials/examples/ft-contract-tools.md | 48 +++++++++++--------- 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/tutorials/examples/ft-contract-tools.md b/docs/tutorials/examples/ft-contract-tools.md index 42d5d65e48d..4c05a226bb6 100644 --- a/docs/tutorials/examples/ft-contract-tools.md +++ b/docs/tutorials/examples/ft-contract-tools.md @@ -8,26 +8,26 @@ description: "Learn how to create a fungible token (FT) using Contract Tools pac import {Github} from "@site/src/components/UI/Codetabs"; import MovingForwardSupportSection from '@site/src/components/MovingForwardSupportSection'; -In this tutorial, we will create a fungible token (FT) using [Contract Tools](https://github.com/near/near-sdk-contract-tools) package. This package is a collection of common tools and patterns in NEAR smart contract development: - -- Storage fee management. -- Escrow pattern and derive macro. -- Owner pattern and derive macro. -- Pause pattern and derive macro. -- Role-based access control. -- Derive macros for NEP standards: - - NEP-141 (fungible token), extension NEP-148. - - NEP-145 (storage management), and integrations for the fungible token and non-fungible token standards. - - NEP-171 (non-fungible token), extensions NEP-177, NEP-178, NEP-181. - - NEP-297 (events). +In this tutorial, we will create a fungible token (FT) using the [NEAR SDK Contract Tools](https://github.com/near/near-sdk-contract-tools) package. This package is a collection of common tools and patterns to simplify smart contract development, including: + +- Storage fee management +- Escrow pattern and derive macro +- Owner pattern and derive macro +- Pause pattern and derive macro +- Role-based access control +- Derive macros for NEP standards + - NEP-141 (fungible token), extension NEP-148 + - NEP-145 (storage management), and integrations for the fungible token and non-fungible token standards + - NEP-171 (non-fungible token), extensions NEP-177, NEP-178, NEP-181 + - NEP-297 (events) --- ## Introduction -The difference of this example from the [FT contract](https://github.com/near-examples/FT) based on `near_contract_standards` package is the approach of using deriving macros to implement NEP standards and common patterns. +While one can create a fungible token (FT) contract from scratch using only the `near-sdk` and `near_contract_standards` (e.g. [FT contract](https://github.com/near-examples/FT)), a simpler approach is to use `near-sdk-contract-tools`. -When we use deriving macros, we can bring `near_contract_standards` implementations into our contract without writing boilerplate code for the each method. That allows us to focus on the unique logic of our contract like minting/burning logic, access control, other custom features. So, this collection of common tools and patterns (mostly in the form of derive macros) is as a sort of OpenZeppelin for NEAR. +`near-sdk-contract-tools` allows us implement the logic for minting/burning logic, access control, and other FT standards by simply deriving macros on our contract struct, as `OpenZeppelin` does for Ethereum contracts. --- @@ -54,7 +54,7 @@ This will bring all the basic FT methods defined in NEP-141 standard to our cont - `storage_unregister` - `storage_withdraw` -To bring basic owner methods to our contract, we derived also `Owner` macro which adds the following methods: +To bring basic owner methods to our contract, we can also derive the `Owner` macro which adds the following methods: - `own_get_owner` - `own_get_proposed_owner` - `own_accept_owner` @@ -75,7 +75,7 @@ To initialize the basic FT contract with custom owner, metadata and storage boun ## Transfer Hook -To add custom logic on transfer method, we need to implement a hook. Hooks are a way to wrap (inject code before and after) component functions: +If we want to customize how the transfer of tokens work (i.e. modify the `ft_transfer` method), we need to implement a hook. Hooks are a way to **wrap (inject code before and after)** component functions: :::tip -You can modify this method as you need, for example, to allow minting only when the contract is not paused (requires deriving [`Pausable`](https://github.com/near/near-sdk-contract-tools/tree/develop?tab=readme-ov-file#macro-combinations) hook), or to allow minting only to specific accounts with a certain role or from whitelist with custom limitations. + +You can modify this method as you need, for example, to allow minting only when the contract is not paused (requires deriving [`Pausable`](https://github.com/near/near-sdk-contract-tools/tree/develop?tab=readme-ov-file#macro-combinations) hook), or to allow minting only to specific accounts with a certain role or from whitelist with custom limitations + ::: --- ## Burning -To burn tokens from the owner's account, we implement `burn` method and also restrict access: +In the same way that minting is not included in the FT standards, burning is also not included. However, we can also easily implement it. + +To burn tokens from the owner's account, we can add a `burn` method which is also only callable by the owner: \ No newline at end of file + From bc6c02118565679c4edf9328308d1aae6030f92b Mon Sep 17 00:00:00 2001 From: Guillermo Alejandro Gallardo Diez Date: Tue, 11 Nov 2025 15:03:16 +0100 Subject: [PATCH 5/5] fix: moved contract-tools to the right folder --- .../ft/sdk-contract-tools.md} | 4 ++-- website/sidebars.js | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/{tutorials/examples/ft-contract-tools.md => primitives/ft/sdk-contract-tools.md} (98%) diff --git a/docs/tutorials/examples/ft-contract-tools.md b/docs/primitives/ft/sdk-contract-tools.md similarity index 98% rename from docs/tutorials/examples/ft-contract-tools.md rename to docs/primitives/ft/sdk-contract-tools.md index 4c05a226bb6..b0c011bf086 100644 --- a/docs/tutorials/examples/ft-contract-tools.md +++ b/docs/primitives/ft/sdk-contract-tools.md @@ -1,5 +1,5 @@ --- -id: ft-contract-tools +id: sdk-contract-tools title: Create FT using Contract Tools sidebar_label: Create FT using Contract Tools description: "Learn how to create a fungible token (FT) using Contract Tools package" @@ -15,7 +15,7 @@ In this tutorial, we will create a fungible token (FT) using the [NEAR SDK Contr - Owner pattern and derive macro - Pause pattern and derive macro - Role-based access control -- Derive macros for NEP standards +- Derive macros for [NEP standards](./standard.md) - NEP-141 (fungible token), extension NEP-148 - NEP-145 (storage management), and integrations for the fungible token and non-fungible token standards - NEP-171 (non-fungible token), extensions NEP-177, NEP-178, NEP-181 diff --git a/website/sidebars.js b/website/sidebars.js index 1aba99e8983..078728cb4cc 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -467,7 +467,7 @@ const sidebar = { 'Fungible Tokens (FT)': [ 'primitives/ft/standard', 'primitives/ft/ft', - 'tutorials/examples/ft-contract-tools' + 'primitives/ft/sdk-contract-tools' ] }, {