v1.0.1

.github/workflows/rust.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: 1.65
+          toolchain: 1.66
           components: rustfmt
       - name: Check formatting
         run: >
@@ -30,7 +30,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: 1.65
+          toolchain: 1.66
           components: clippy
       - name: Run linter
         run: cargo clippy -- -D warnings
@@ -41,7 +41,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: 1.65
+          toolchain: 1.66
       - name: Run unit and integration tests
         run: cargo test --workspace --exclude workspaces-tests
   workspaces-test:
@@ -51,7 +51,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: 1.65
+          toolchain: 1.66
           targets: wasm32-unknown-unknown
       - name: Run workspaces tests
         run: >

Cargo.toml

@@ -4,16 +4,17 @@ categories = ["wasm", "cryptography::cryptocurrencies"]
 description = """
 Helpful functions and macros for developing smart contracts on NEAR Protocol.
 """
-documentation = "https://docs.rs/near-contract-tools"
+documentation = "https://docs.rs/near-sdk-contract-tools"
 edition = "2021"
+exclude = ["documents/"]
 license = "GPL-3.0"
-name = "near-contract-tools"
-repository = "https://github.com/NEARFoundation/near-contract-tools"
-version = "0.7.2"
+name = "near-sdk-contract-tools"
+repository = "https://github.com/NEARFoundation/near-sdk-contract-tools"
+version = "1.0.0"
 
 [dependencies]
-near-contract-tools-macros = {version = "=0.7.2", path = "./macros"}
 near-sdk = {version = "4.1.0", default-features = false}
+near-sdk-contract-tools-macros = {version = "=1.0.0", path = "./macros"}
 serde = "1.0.144"
 serde_json = "1.0.85"
 thiserror = "1.0.35"

README.md

@@ -1,6 +1,4 @@
-# This package will be renamed to [`near-sdk-contract-tools`](https://crates.io/crates/near-sdk-contract-tools)
-
-# near-contract-tools
+# near-sdk-contract-tools
 
 > Helpful functions and macros for developing smart contracts on NEAR Protocol.
 
@@ -17,15 +15,17 @@ Not to be confused with [`near-contract-standards`](https://crates.io/crates/nea
 
 **WARNING:** This is still early software, and there may be breaking changes between versions. I'll try my best to keep the docs & changelogs up-to-date. Don't hesitate to create an issue if find anything wrong.
 
+(Formerly known as [`near-contract-tools`](https://crates.io/crates/near-contract-tools).)
+
 ## Benefits
 
 - requires fewer lines of code
-  - Without near-contract-tools, implementing fungible token events (mint, transfer, and burn) takes ~100 lines of code. Using near-contract-tools, you can [implement them in ~40 lines](https://youtu.be/kJzes_UP5j0?t=1058).
+  - Without near-sdk-contract-tools, implementing fungible token events (mint, transfer, and burn) takes ~100 lines of code. Using near-sdk-contract-tools, you can [implement them in ~40 lines](https://youtu.be/kJzes_UP5j0?t=1058).
 - is more readable
 - follows a consistent pattern
   - Every time you use the events macro, it will [implement events in the same way](https://youtu.be/kJzes_UP5j0?t=1150). Without it, you’d need to ensure that `emit`, `emit_many`, etc all work (and work the same).
 - is more thorough
-  - near-contract-standards is also not implementing traits, so that’s another improvement that near-contract-tools offers.
+  - near-contract-standards is also not implementing traits, so that’s another improvement that near-sdk-contract-tools offers.
 
 You can think of this collection of common tools and patterns (mostly in the form of [derive macros](https://doc.rust-lang.org/reference/procedural-macros.html#derive-macros)) as sort of an OpenZeppelin for NEAR.
 
@@ -34,7 +34,7 @@ You can think of this collection of common tools and patterns (mostly in the for
 ```text
 rustup target add wasm32-unknown-unknown
 cargo init
-cargo add near-contract-tools
+cargo add near-sdk-contract-tools
 cargo add near-sdk
 # https://raen.dev/guide/intro/getting-set-up.html
 cargo install raen
@@ -80,7 +80,7 @@ See also: [the full integration tests](tests/macros/mod.rs).
 
 ```rust
 use near_sdk::{near_bindgen, AccountId};
-use near_contract_tools::{owner::Owner, Owner};
+use near_sdk_contract_tools::{owner::Owner, Owner};
 
 #[derive(Owner)]
 #[near_bindgen]
@@ -124,7 +124,7 @@ fn own_accept_owner(&mut self);
 The `#[event]` macro can be applied to structs or enums.
 
 ```rust
-use near_contract_tools::{event, standard::nep297::Event};
+use near_sdk_contract_tools::{event, standard::nep297::Event};
 
 #[event(standard = "nft", version = "1.0.0")]
 pub struct MintEvent {
@@ -146,7 +146,7 @@ e.emit();
 To create a contract that is compatible with the NEP-141 and NEP-148 standards, that emits standard-compliant (NEP-141, NEP-297) events.
 
 ```rust
-use near_contract_tools::FungibleToken;
+use near_sdk_contract_tools::FungibleToken;
 use near_sdk::near_bindgen;
 
 #[derive(FungibleToken)]
@@ -169,7 +169,7 @@ Standalone macros for each individual standard also exist.
 One may wish to combine the features of multiple macros in one contract. All of the macros are written such that they will work in a standalone manner, so this should largely work without issue. However, sometimes it may be desirable for the macros to work in _combination_ with each other. For example, to make a fungible token pausable, use the fungible token hooks to require that a contract be unpaused before making a token transfer:
 
 ```rust
-use near_contract_tools::{
+use near_sdk_contract_tools::{
     pause::Pause,
     standard::nep141::{Nep141Hook, Nep141Transfer},
     FungibleToken, Pause,
@@ -192,13 +192,13 @@ Note: Hooks can be disabled using `#[nep141(no_hooks)]` or `#[fungible_token(no_
 
 ### Custom Crates
 
-If you are a library developer, have modified a crate that one of the `near-contract-tools` macros uses (like `serde` or `near-sdk`), or are otherwise using a crate under a different name, you can specify crate names in macros like so:
+If you are a library developer, have modified a crate that one of the `near-sdk-contract-tools` macros uses (like `serde` or `near-sdk`), or are otherwise using a crate under a different name, you can specify crate names in macros like so:
 
 ```rust, ignore
 #[event(
     // ...
-    crate = "near_contract_tools",
-    macros = "near_contract_tools_macros",
+    crate = "near_sdk_contract_tools",
+    macros = "near_sdk_contract_tools_macros",
     serde = "serde",
 )]
 // ...
@@ -255,6 +255,10 @@ See [src/slot.rs](src/slot.rs) They are very thin wrappers over a storage key. I
 
 First, run `git config core.hooksPath hooks/` to install the hooks of this directory (without affecting how git hooks work for other projects).
 
+## Audit
+
+This library has been [audited](./documents/NEAR%20Contract%20Tools%20-%20Final%20-%2005.05.2023.pdf) by [Kudelski Security](https://www.kudelskisecurity.com/).
+
 ## Authors
 
 - Jacob Lindahl [@sudo_build](https://twitter.com/sudo_build)

macros/Cargo.toml

@@ -2,12 +2,12 @@
 authors = ["Jacob Lindahl <jacob@near.foundation>"]
 categories = ["wasm"]
 description = """
-Macros for `near-contract-tools`
+Macros for `near-sdk-contract-tools`
 """
 edition = "2021"
 license = "GPL-3.0"
-name = "near-contract-tools-macros"
-version = "0.7.2"
+name = "near-sdk-contract-tools-macros"
+version = "1.0.0"
 
 [dependencies]
 base64 = "0.13.0"

macros/src/approval/simple_multisig.rs

@@ -42,7 +42,7 @@ pub fn expand(meta: SimpleMultisigMeta) -> Result<TokenStream, darling::Error> {
     });
 
     Ok(quote! {
-        impl #imp #me::approval::ApprovalManager<
+        impl #imp #me::approval::ApprovalManagerInternal<
                 #action,
                 #me::approval::simple_multisig::ApprovalState,
                 #me::approval::simple_multisig::Configuration<Self>,

macros/src/lib.rs

@@ -1,4 +1,4 @@
-//! Macros for near-contract-tools
+//! Macros for near-sdk-contract-tools.
 
 use darling::{FromDeriveInput, FromMeta};
 use proc_macro::TokenStream;
@@ -14,11 +14,11 @@ mod standard;
 mod upgrade;
 
 fn default_crate_name() -> syn::Path {
-    syn::parse_str("::near_contract_tools").unwrap()
+    syn::parse_str("::near_sdk_contract_tools").unwrap()
 }
 
 fn default_macros() -> syn::Path {
-    syn::parse_str("::near_contract_tools").unwrap()
+    syn::parse_str("::near_sdk_contract_tools").unwrap()
 }
 
 fn default_near_sdk() -> syn::Path {
@@ -59,6 +59,18 @@ where
 /// - `SHOUTY_SNAKE_CASE`
 /// - `SHOUTY-KEBAB-CASE`
 /// - `Title Case`
+///
+/// # Warning
+///
+/// Rename strategies are provided for convenience, and the actual string
+/// transformation is delegated to the [`heck`](https://crates.io/crates/heck)
+/// crate. It _is_ possible that unexpected name transformations or collisions
+/// may occur, but it is _extremely unlikely_ if reasonable Rust naming
+/// conventions are followed.
+///
+/// For example, `"HelloWorld"`, `"hello_world"`, and `"hello__world"`, when
+/// snake-case-ified, are `"hello_world"`, so if you happened to name distinct
+/// events thusly, the transformed names would collide.
 #[proc_macro_derive(Nep297, attributes(nep297))]
 pub fn derive_nep297(input: TokenStream) -> TokenStream {
     make_derive(input, standard::nep297::expand)
@@ -85,8 +97,8 @@ pub fn derive_pause(input: TokenStream) -> TokenStream {
 
 /// Adds role-based access control. No external methods are exposed.
 ///
-/// The roles prefix must be specify a type using #[rbac(roles = "MyRoles")].
-/// Typically "MyRoles" is an enum and it's variants are the different role
+/// The roles prefix can be specified using `#[rbac(roles = "MyRoles")]`.
+/// Typically `"MyRoles"` is an enum and its variants are the different role
 /// names.
 ///
 /// The storage key prefix for the fields can be optionally specified (default:
@@ -98,7 +110,7 @@ pub fn derive_rbac(input: TokenStream) -> TokenStream {
 
 /// Adds NEP-141 fungible token core functionality to a contract. Exposes
 /// `ft_*` functions to the public blockchain, implements internal controller
-/// and receiver functionality (see: `near_contract_tools::standard::nep141`).
+/// and receiver functionality (see: [`near_sdk_contract_tools::standard::nep141`]).
 ///
 /// The storage key prefix for the fields can be optionally specified (default:
 /// `"~$141"`) using `#[nep141(storage_key = "<expression>")]`.
@@ -170,7 +182,9 @@ pub fn derive_simple_multisig(input: TokenStream) -> TokenStream {
     make_derive(input, approval::simple_multisig::expand)
 }
 
-/// Smart `#[event]` macro
+/// Smart `#[event]` macro.
+///
+/// See documentation on the [`derive@Nep297`] derive macro for more details.
 #[proc_macro_attribute]
 pub fn event(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr = parse_macro_input!(attr as AttributeArgs);

macros/src/owner.rs

@@ -39,36 +39,36 @@ pub fn expand(meta: OwnerMeta) -> Result<TokenStream, darling::Error> {
     });
 
     Ok(quote! {
-        impl #imp #me::owner::Owner for #ident #ty #wher {
+        impl #imp #me::owner::OwnerInternal for #ident #ty #wher {
             #root
         }
 
         #[#near_sdk::near_bindgen]
         impl #imp #me::owner::OwnerExternal for #ident #ty #wher {
             fn own_get_owner(&self) -> Option<#near_sdk::AccountId> {
-                <Self as #me::owner::Owner>::slot_owner().read()
+                <Self as #me::owner::OwnerInternal>::slot_owner().read()
             }
 
             fn own_get_proposed_owner(&self) -> Option<#near_sdk::AccountId> {
-                <Self as #me::owner::Owner>::slot_proposed_owner().read()
+                <Self as #me::owner::OwnerInternal>::slot_proposed_owner().read()
             }
 
             #[payable]
             fn own_renounce_owner(&mut self) {
                 #near_sdk::assert_one_yocto();
-                self.renounce_owner()
+                #me::owner::Owner::renounce_owner(self);
             }
 
             #[payable]
             fn own_propose_owner(&mut self, account_id: Option<#near_sdk::AccountId>) {
                 #near_sdk::assert_one_yocto();
-                self.propose_owner(account_id);
+                #me::owner::Owner::propose_owner(self, account_id);
             }
 
             #[payable]
             fn own_accept_owner(&mut self) {
                 #near_sdk::assert_one_yocto();
-                self.accept_owner();
+                #me::owner::Owner::accept_owner(self);
             }
         }
     })

macros/src/pause.rs

@@ -39,7 +39,7 @@ pub fn expand(meta: PauseMeta) -> Result<TokenStream, darling::Error> {
     });
 
     Ok(quote! {
-        impl #imp #me::pause::Pause for #ident #ty #wher {
+        impl #imp #me::pause::PauseInternal for #ident #ty #wher {
             #root
         }
 

macros/src/rbac.rs

@@ -40,7 +40,7 @@ pub fn expand(meta: RbacMeta) -> Result<TokenStream, darling::Error> {
     });
 
     Ok(quote! {
-        impl #imp #me::rbac::Rbac for #ident #ty #wher {
+        impl #imp #me::rbac::RbacInternal for #ident #ty #wher {
             type Role = #roles;
 
             #root

macros/src/standard/nep141.rs

@@ -54,7 +54,7 @@ pub fn expand(meta: Nep141Meta) -> Result<TokenStream, darling::Error> {
     });
 
     Ok(quote! {
-        impl #imp #me::standard::nep141::Nep141Controller for #ident #ty #wher {
+        impl #imp #me::standard::nep141::Nep141ControllerInternal for #ident #ty #wher {
             #root
         }
 

macros/src/upgrade.rs

@@ -32,7 +32,7 @@ impl FromMeta for HookBody {
                 .and_then(|s| syn::parse_str::<Expr>(s.as_str()).ok())
                 .map(|e| HookBody::Role(Box::new(e)))
                 .ok_or_else(|| {
-                    darling::Error::custom(&format!(
+                    darling::Error::custom(format!(
                         r#"Invalid value "{value}", expected "empty", "owner", or "role(...)""#,
                     ))
                 })
@@ -51,7 +51,7 @@ impl FromMeta for Serializer {
         match value {
             "borsh" => Ok(Self::Borsh),
             "jsonbase64" => Ok(Self::JsonBase64),
-            _ => Err(darling::Error::custom(&format!(
+            _ => Err(darling::Error::custom(format!(
                 r#"Invalid value "{value}", expected "borsh" or "jsonbase64""#
             ))),
         }

rust-toolchain.toml

@@ -1,2 +1,2 @@
 [toolchain]
-channel = "1.65"
+channel = "1.66"