-
Notifications
You must be signed in to change notification settings - Fork 366
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Blogpost on SDK consolidation + Announcement Bar (+ small fix) (#2090)
* added blogpost + small fixes * Apply suggestions from code review Co-authored-by: Damián Parrino <[email protected]> --------- Co-authored-by: Damián Parrino <[email protected]>
- Loading branch information
Showing
7 changed files
with
223 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| --- | ||
| title: One place for all Smart Contracts Docs | ||
| authors: [gagdiez] | ||
| slug: sdks-unified | ||
| tags: [updates] | ||
| --- | ||
|
|
||
| *We have consolidated all our documentation in a single section, so you don't need to go searching around for it* | ||
|
|
||
| <p><img src="/assets/images/contracts-landing-5a9c76a78e71b0e5f9a96033f1f23d23.png" /></p> | ||
|
|
||
| <!-- truncate --> | ||
|
|
||
| Smart contracts are small pieces of logic that can live on every NEAR account. To build a contract you use the NEAR SDKs, which comes in two flavours: Rust and JavaScript. | ||
|
|
||
| Until today, we had multiple docs explaining how to build smart contracts: | ||
| - `/sdk/rust` dedicated to explain how to use the Rust SDK | ||
| - `/sdk/js` dedicated to explain how to use the JS SDK | ||
| - [`/build/smart-contracts/what-is`](/build/smart-contracts/what-is) - that explains general concepts, and how to implement them using both SDKs | ||
|
|
||
| Today, this is over, as all the information on how to build smart contracts is located in a single area: [`/build/smart-contracts/what-is`](/build/smart-contracts/what-is). | ||
|
|
||
| Meanwhile, we have transformed the [SDK page](/tools/sdk) to be a simple landing page with links to: | ||
| - The [Rust SDK reference docs](https://docs.rs/near-sdk/latest/near_sdk/) | ||
| - The [JS SDK reference docs](https://near.github.io/near-api-js/) | ||
| - The [Smart Contract Section](/build/smart-contracts/what-is) | ||
|
|
||
| ## Why did we have 3 sections explaining the same topic? | ||
|
|
||
| The reason we had 3 different sections was that, historically, the engineers of each SDK were working on their own docs in isolation. To help mitigate this, we created a section on NEAR docs, meant to consolidate all the external documentation. | ||
|
|
||
| One day, the individual SDK pages were deleted - if I remember correctly, it was because we wanted to have fewer domains - and we had to migrate everything in a rush. | ||
|
|
||
| This left us in a very weird situation: we already had a section explaining how to build a smart contract... and now we had 3. | ||
|
|
||
| ## A single source of truth | ||
|
|
||
| Luckily, this is now fixed! We have finally conquered the original dream of having a single section for [Smart Contracts](/build/smart-contracts/what-is), with all the information consolidated in there. | ||
|
|
||
| Now, we can focus on maintaining a single section, thus making it easier to keep it updated and relevant. | ||
|
|
||
| ## What's next? | ||
|
|
||
| We are currently undergoing a process of **consolidating** all the documentation. This means that we are looking at all the sections that have overlapping information, and trying to merge them into a single place. | ||
|
|
||
| This will not only improve the quality of our docs, but also make it easier for you to find the information you need. In fact, improving search is one of the main motors of this change, since we noticed that our search tool ([Algolia](https://www.algolia.com/)) gets confused when the same concept is spread all over the place. | ||
|
|
||
| Moreover, having consistent and coherent documentation will allow us to further expand our search capabilities using AI! This is something we are very excited about, as it will allow us to provide you with even more relevant information. | ||
|
|
||
| ## If you don't like this change, please let us know! | ||
|
|
||
| As always, we are more than open to feedback. If you think that this change is not good, or that we are missing something, please let us know! You can reach out to us through the blue feedback button you see at the side of the screen. | ||
|
|
||
| We are looking forward to hearing your thoughts and feedback, and hope you enjoy the content we'll be sharing. | ||
|
|
||
| Happy coding, and see you in the next post! 🚀 |
139 changes: 139 additions & 0 deletions
139
docs/2.build/2.smart-contracts/anatomy/best-practices.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| --- | ||
| id: best-practices | ||
| title: "Best Practices" | ||
| --- | ||
|
|
||
| # Best practices | ||
|
|
||
| ## Enable overflow checks | ||
|
|
||
| It's usually helpful to panic on integer overflow. To enable it, add the following into your `Cargo.toml` file: | ||
|
|
||
| ```toml | ||
| [profile.release] | ||
| overflow-checks = true | ||
| ``` | ||
|
|
||
| ## Use `require!` early | ||
|
|
||
| Try to validate the input, context, state and access using `require!` before taking any actions. The earlier you panic, the more [gas](https://docs.near.org/concepts/protocol/gas) you will save for the caller. | ||
|
|
||
| ```rust | ||
| #[nearn] | ||
| impl Contract { | ||
| pub fn set_fee(&mut self, new_fee: Fee) { | ||
| require!(env::predecessor_account_id() == self.owner_id, "Owner's method"); | ||
| new_fee.assert_valid(); | ||
| self.internal_set_fee(new_fee); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **Note**: If you want debug information in the panic message or if you are using an SDK version before `4.0.0-pre.2`, | ||
| the Rust `assert!` macro can be used instead of `require!`. | ||
|
|
||
| ```rust | ||
| #[near] | ||
| impl Contract { | ||
| pub fn set_fee(&mut self, new_fee: Fee) { | ||
| assert_eq!(env::predecessor_account_id(), self.owner_id, "Owner's method"); | ||
| new_fee.assert_valid(); | ||
| self.internal_set_fee(new_fee); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Use `log!` | ||
|
|
||
| Use logging for debugging and notifying user. | ||
|
|
||
| When you need a formatted message, you can use the following macro: | ||
|
|
||
| ```rust | ||
| log!("Transferred {} tokens from {} to {}", amount, sender_id, receiver_id); | ||
| ``` | ||
|
|
||
| It's equivalent to the following message: | ||
|
|
||
| ```rust | ||
| env::log_str(format!("Transferred {} tokens from {} to {}", amount, sender_id, receiver_id).as_ref()); | ||
| ``` | ||
|
|
||
| ## Return `Promise` | ||
|
|
||
| If your method makes a cross-contract call, you probably want to return the newly created `Promise`. | ||
| This allows the caller (such as a near-cli or near-api-js call) to wait for the result of the promise instead of returning immediately. | ||
| Additionally, if the promise fails for some reason, returning it will let the caller know about the failure, as well as enabling NEAR Explorer and other tools to mark the whole transaction chain as failing. | ||
| This can prevent false-positives when the first or first few transactions in a chain succeed but a subsequent transaction fails. | ||
|
|
||
| E.g. | ||
|
|
||
| ```rust | ||
| #[near] | ||
| impl Contract { | ||
| pub fn withdraw_100(&mut self, receiver_id: AccountId) -> Promise { | ||
| Promise::new(receiver_id).transfer(100) | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Reuse crates from `near-sdk` | ||
|
|
||
| `near-sdk` re-exports the following crates: | ||
|
|
||
| - `borsh` | ||
| - `base64` | ||
| - `bs58` | ||
| - `serde` | ||
| - `serde_json` | ||
|
|
||
| Most common crates include `borsh` which is needed for internal STATE serialization and | ||
| `serde` for external JSON serialization. | ||
|
|
||
| When marking structs with `serde::Serialize` you need to use `#[serde(crate = "near_sdk::serde")]` | ||
| to point serde to the correct base crate. | ||
|
|
||
| ```rust | ||
| /// Main contract structure serialized with Borsh | ||
| #[near(contract_state)] | ||
| #[derive(PanicOnDefault)] | ||
| pub struct Contract { | ||
| pub pair: Pair, | ||
| } | ||
|
|
||
| /// Implements both `serde` and `borsh` serialization. | ||
| /// `serde` is typically useful when returning a struct in JSON format for a frontend. | ||
| #[near(serializers = [json, borsh])] | ||
| pub struct Pair { | ||
| pub a: u32, | ||
| pub b: u32, | ||
| } | ||
|
|
||
| #[near] | ||
| impl Contract { | ||
| #[init] | ||
| pub fn new(pair: Pair) -> Self { | ||
| Self { | ||
| pair, | ||
| } | ||
| } | ||
|
|
||
| pub fn get_pair(self) -> Pair { | ||
| self.pair | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## `std::panic!` vs `env::panic` | ||
|
|
||
| - `std::panic!` panics the current thread. It uses `format!` internally, so it can take arguments. | ||
| SDK sets up a panic hook, which converts the generated `PanicInfo` from `panic!` into a string and uses `env::panic` internally to report it to Runtime. | ||
| This may provide extra debugging information such as the line number of the source code where the panic happened. | ||
|
|
||
| - `env::panic` directly calls the host method to panic the contract. | ||
| It doesn't provide any other extra debugging information except for the passed message. | ||
|
|
||
| ## Use workspaces | ||
|
|
||
| Workspaces allow you to automate workflows and run tests for multiple contracts and cross-contract calls in a sandbox or testnet environment. | ||
| Read more, [workspaces-rs](https://github.com/near/workspaces-rs) or [workspaces-js](https://github.com/near/workspaces-js). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters