This kind of implements the state-machine version of multisig, but the Approval construct is generic such that I think it could conceivably be used for any type of "multisig-like" process.

A few ways to implement multisig:

1. Follow a preexisting pattern (e.g. copy/translate from core-contracts/multisig2).
   • Pros: Logic & structures predefined, pattern is somewhat well-known (at least, not new)
   • Cons: Code is not very well-maintained, large, complex (complexity = opportunity for error), not NEP-standardized, and such a standard would likely take a long time due to the complexity
2. Implement our own: state machine (similar logic to core-contracts version)
   • Pros: We can clean up the logic from core-contracts a lot and simplify as necessary
   • Cons: Still relatively complex, and that comes with the same NEP approval difficulties.
3. Implement our own: tx queue/approval. The idea is to accept an arbitrary transaction-like blob and simply sign&send when quorum is reached.
   • Pros: Simpler than state machine model, since we don't have to re-implement every possible action in our own custom data structures. Management actions (e.g. add member) could be implemented as normal #[private] functions which are called via normal, reflexive FUNCTION_CALL proposal blobs. Possibly easier to standardize as NEP since the logic is simpler.
   • Cons: Contract will have to do a little extra legwork (tx blob parsing) if it wants to implement any sort of limits on what sort of actions can be proposed, since this implementation would be written for generically signing opaque transaction blobs. I'm not aware if this pattern has been implemented before (on NEAR), so this would be new technology. Requires more testing, and I'm not even absolutely sure it's possible since I've not written a PoC.
4. Implement our own: transaction signing protocol. Accept a transaction blob and an array of signatures (generated off-chain).
   • Pros: Probably the most straightforward implementation of multisig.
   • Cons: Suffers from the same lack of control as option 3 since it accepts an opaque blob. Requires some sort of off-chain mechanism for generating signatures.

@encody For https://near-foundation.atlassian.net/browse/ENG-149 , what do you think about this?

Adding a server-side CI tool looked more complicated than it's worth (for our small team at this point, I think).

The top level doc page for the package shows the modules but not the traits it offers.

Since the primary aim of this repo is to capture common patterns as traits. They can be exposed at the top level. This is will also expose those traits in the top level documentation. This can be done by re-exporting them from lib.rs.

Again we can take a cue from serde docs and lib.rs

~For example, ownership::Ownership::propose_owner_internal would not call require_owner or emit an OwnershipEvent::Propose event.~

For Owner, it might make more sense to just have a non-event-emitting version of update_owner and update_proposed. For Pause, set_is_paused already doesn’t emit events or have any require! calls, so it wouldn’t require updating for this issue. I think the method names could use some work though, i.e. just by looking at the name of the method I should be able to tell whether it emits events & performs, for example, predecessor checks, and also the method that does perform those things should appear to the untrained eye as the “natural” choice. Hence, I had initially thought using names like update_owner_internal would be a good idea, but maybe update_owner_unchecked would be a better choice.

It would be very neat to have a standardized way of upgrading a smart contract and migrating its state to mitigate common security vulnerabilities.

• Should provide a callback for calling a migration state
• Can only be executed with a full access key or by the contract owner.
• Possibly support storing the previous state of the contract in case of an immediate rollback

serde uses this nifty field on their macros to allow you to specify the actual crate it should be using as the "serde" crate:

#[serde(crate = "path::to::serde")]

Emulating this pattern is useful:

• Currently there is an inconsistent use of leading colons :: in the macros
• It's weird to try to use the near_contract_tools_macros in near_contract_tools for this reason
• Some macros make use of other crates' types (near_sdk and serde, particularly). near_sdk reexports its own version of serde, so some users may wish to use that version (also we should discuss what the default serde crate should be @ryancwalsh @nearken).

Writes a decent amount of the boilerplate per discussion with @nearken . Does not expose a public interface (difficult with generics + NEP requirement). Usage: see updated workspaces test.

Let's add (in a separate repo if necessary... and this one can link to it) complete examples of projects taking advantage of near-contract-tools.

E.g. https://github.com/NEARFoundation/near-contract-tools/blob/01a64242717af71a27fa49197a96912d1c5aeedb/README.md#fungible-token isn't enough to get me started. Part (most?) of it is that I'm new to Rust, but I'm having trouble knowing where to put these lines, what Cargo.toml needs to contain, how to build the project, etc. So a full working example would be helpful.

I looked at https://github.com/NEAR-Edu/near-certification-tools/blob/938255e1adbecbe0605c2749f9a7ebd9a9df317a/data-contract/src/contract.rs#L5 but couldn't figure it out. (Maybe certain types of macros are different from "derive" macros?

This issue is resolved when all of the below point are resolved or moot:

• Should the name of the package be changed?
• To what should the name of the package be changed?
• All internal references/mentions have been updated, the repository has been moved, the old package has been deprecated on crates.io, and the renamed package has been published to crates.io.

For assistance on the audit, every component should have a list of invariants / assumptions for use and for every function. For example, the Owner component's list would include:

• The root storage key is not used for any other data.
• Only the owner will ever be able to call own_renounce_owner, own_propose_owner.
• Only the account most recently proposed (by the current owner, via own_propose_owner) will be able to call own_accept_owner.
• After own_accept_owner has been called, the formerly "proposed owner" will become the owner, and the former owner will be removed. There will not be a "proposed owner".
• Et cetera.

This list should appear in the module level documentation comments for each component.

Currently, many of the components are composed of traits that contain methods that are primarily (nigh exclusively) for internal use (e.g. many of them have a root() function that returns a Slot). For someone who isn't super familiar with how this library works, these methods may appear to be freely usable, and may unintentionally cause the component to malfunction by their misuse.

There are a few ways we could think about fixing this problem:

1. Just be really clear in the documentation which functions are for general use and which ones are internal.
2. Rename the functions… a. …by prefixing with an underscore (e.g. root -> _root). b. …by prefixing with a word (e.g. root -> internal_root).
3. We could consider using #[doc(hidden)], but I don't think that's really what that attribute is for.
4. Split the internal functions off into a separate trait.
5. Restructure the entire library such that hidden/private functions are actually hidden/private. Probably quite difficult to do at this point in the library's development, plus it would almost definitely make the derive macros more complicated to correctly implement.

The contract demonstrates a simplified but relatable real world scenario where a payroll management contract can add and pay employees.

Among other things it demonstrates how and where to use macros for Rbac and patterns around collections, storage keys and Promises and handling errors in a non-trivial example.

Next step is to handle more error cases, include a multi-sig approval in this and create test cases to show how it works.

For smart contracts that manage multiple NEP-141 tokens in a treasury and issue a backed token. Inspired by the Skyward Finance hack. Should work well in conjunction with the existing NEP-141 infrastructure in this package (optional).

• Provides mint and redeem actions. Each action could be exposed / limited / permissioned by the contract author as desired.
• Mint action is backed by something (token, NEAR native, etc.). This would be specified by the contract author, probably via some sort of hook.
• Redeem action would return the backing asset(s) to the redeemer.
• Mechanism for controlled / limited release (e.g. time release, cliff / vest schedule, etc.)

Request for comments

• Design suggestions
• Should the component that would solve the Skyward issue be a "backed token" (i.e. NEP-141 extension of sorts) or a "treasury manager" (contract-agnostic multi-token (NEP-141 only?) manager)
• Is this component in-scope for this project? It is definitely a little bit more "niche" in use-case, but I think if the component is sufficiently generalized, it could be useful for implementing:
  • Arbitrary token lockups (cliff/vest schedule)
  • Backed tokens (single- and multi-asset)
  • DAO treasuries

Like a generic version of Owner. Like Rbac, but there is a 1:0..1 relationship between an identity and an account ID. It will also be possible to retrieve the holder of an identity (enumeration is not possible in the current version of Rbac). Identity transfer (via propose/accept) and renunciation are optionally allowed.

Possible Example

enum Identity {
    Owner,
    Administrator,
    Manager,
}

#[derive(Identities)]
#[identities(identities = "Identity")]
#[near_bindgen]
struct MyContract {}

#[near_bindgen]
impl MyContract {
    #[init]
    fn init() -> Self {
        let mut contract = Self {};

        contract.initialize_identity(&Identity::Owner, env::predecessor_account_id());
        contract.initialize_identity(&Identity::Administrator, env::predecessor_account_id());
        contract.initialize_identity(&Identity::Manager, env::predecessor_account_id());
    }

    fn only_owner(&self, account: AccountId) {
        self.require_identity(&Identity::Owner);
    }

    fn only_administrator(&self, account: AccountId) {
        self.require_identity(&Identity::Administrator);
    }
}

impl IdentityHook<Identity> for MyContract {
    fn on_transfer(identity: &Identity, from: AccountId, to: AccountId) -> Result<(), ?> { }

    fn on_propose(identity: &Identity, account: AccountId) -> Result<(), ?> { }

    fn on_accept(identity: &Identity, account: AccountId) -> Result<(), ?> { }
}

Would expose the following interface to the blockchain:

(Caveat: Identities need a to/from string serialization)

trait IdentityExternal<Identity> {
    fn id_is(&self, account: AccountId, identity: Identity) -> bool;
    fn id_get(&self, identity: Identity) -> Option<AccountId>;
    fn id_renounce(&mut self, identity: Identity);
    fn id_propose(&mut self, identity: Identity, to: AccountId);
    fn id_accept(&mut self, identity: Identity, from: AccountId);
}

Macro that adds an external method that returns the commit hash of the build.

This should be possible because macros run at compile time.

Existing similar NEP: https://github.com/near/NEPs/blob/master/neps/nep-0330.md

Possible Example Usage

trait BuildId {
    fn build_id(&self) -> String;
}

#[derive(BuildId)]
#[derive(BorshSerialize, BorshDeserialize, PanicOnDefault)]
#[near_bindgen]
pub struct MyContract {
    // ...
}

let contract = MyContract::new();
println!("{}", contract.build_id()); // 6a5992033dc4a092a5d45d64b4f205ce9aeb2939