Attribute Macro near

#[near]

This attribute macro is used on a struct and its implementations to generate the necessary code to expose pub methods from the contract as well as generating the glue code to be a valid NEAR contract.

Example

#[near(serializers=[borsh, json])]
struct MyStruct {
   pub name: String,
}

This macro will generate code to load and deserialize state if the self parameter is included as well as saving it back to state if &mut self is used.

Parameter and result serialization

If the macro is used with Impl section, for parameter serialization, this macro will generate a struct with all of the parameters as fields and derive deserialization for it. By default this will be JSON deserialized with serde but can be overwritten by using #[serializer(borsh)]:

#[near]
impl Adder {
   #[result_serializer(borsh)]
   pub fn borsh_parameters(&self, #[serializer(borsh)] a: Pair, #[serializer(borsh)] b: Pair) -> Pair {
       /// ...
   }
}

#[near] will also handle serializing and setting the return value of the function execution based on what type is returned by the function. By default, this will be done through serde serialized as JSON, but this can be overwritten using #[result_serializer(borsh)]:

#[near]
impl Adder {
   #[result_serializer(borsh)]
   pub fn borsh_parameters(&self) -> Pair {
       /// ...
   }
}

Usage for enum / struct

If the macro is used with struct or enum, it will make the struct or enum serializable with either Borsh or Json depending on serializers passed. Use #[near(serializers=[borsh])] to make it serializable with Borsh. Or use #[near(serializers=[json])] to make it serializable with Json. By default, borsh is used. You can also specify both and none. BorshSchema or JsonSchema are always generated.

If you want the struct to be a contract state, you can pass in the contract_state argument.

Example

use near_sdk::near;

#[near(contract_state)]
pub struct Contract {
   data: i8,
}

#[near]
impl Contract {
    pub fn some_function(&self) {}
}

As well, the macro supports arguments like event_json and contract_metadata.

Events Standard:

By passing event_json as an argument near_bindgen will generate the relevant code to format events according to NEP-297

For parameter serialization, this macro will generate a wrapper struct to include the NEP-297 standard fields standard and version as well as include serialization reformatting to include the eventanddatafields automatically. Thestandardandversionvalues must be included in the enum and variant declaration (see example below). By default this will be JSON deserialized withserde`

Examples

use near_sdk::near;

#[near(event_json(standard = "nepXXX"))]
pub enum MyEvents {
   #[event_version("1.0.0")]
   Swap { token_in: AccountId, token_out: AccountId, amount_in: u128, amount_out: u128 },

   #[event_version("2.0.0")]
   StringEvent(String),

   #[event_version("3.0.0")]
   EmptyEvent
}

#[near]
impl Contract {
    pub fn some_function(&self) {
        MyEvents::StringEvent(
            String::from("some_string")
        ).emit();
    }

}

Contract Source Metadata Standard:

By using contract_metadata as an argument near will populate the contract metadata according to NEP-330 standard. This still applies even when #[near] is used without any arguments.

All fields(version, link, standard) are optional and will be populated with defaults from the Cargo.toml file if not specified.

The contract_source_metadata() view function will be added and can be used to retrieve the source metadata. Also, the source metadata will be stored as a constant, CONTRACT_SOURCE_METADATA, in the contract code.

Examples

use near_sdk::borsh::{self, BorshDeserialize, BorshSerialize};
use near_sdk::near;

#[derive(Default, BorshSerialize, BorshDeserialize)]
#[near(contract_metadata(
    version = "39f2d2646f2f60e18ab53337501370dc02a5661c",
    link = "https://github.com/near-examples/nft-tutorial",
    standard(standard = "nep330", version = "1.1.0"),
    standard(standard = "nep171", version = "1.0.0"),
    standard(standard = "nep177", version = "2.0.0"),
))]
struct Contract {}