diff --git a/near-sdk/Cargo.toml b/near-sdk/Cargo.toml index 853cc17a0..05fe7b46d 100644 --- a/near-sdk/Cargo.toml +++ b/near-sdk/Cargo.toml @@ -98,4 +98,4 @@ __abi-generate = ["abi", "near-sdk-macros/__abi-generate"] __macro-docs = [] [package.metadata.docs.rs] -features = ["unstable", "legacy", "unit-testing", "__macro-docs"] +features = ["unstable", "legacy", "unit-testing", "__macro-docs", "near-primitives", "near-vm-runner"] diff --git a/near-sdk/src/environment/env.rs b/near-sdk/src/environment/env.rs index d7ee2abad..9d9c164da 100644 --- a/near-sdk/src/environment/env.rs +++ b/near-sdk/src/environment/env.rs @@ -225,6 +225,7 @@ fn assert_valid_account_id(bytes: Vec) -> AccountId { /// /// assert_eq!(input(), Some(Vec::new())); /// ``` +/// See an example here [here](https://github.com/near-examples/update-migrate-rust/blob/a1a326de73c152831f93fbf6d90932e13a08b89f/self-updates/update/src/update.rs#L19) pub fn input() -> Option> { try_method_into_register!(input) } @@ -753,6 +754,9 @@ pub fn alt_bn128_pairing_check(value: &[u8]) -> bool { /// ``` /// /// More info about promises in [NEAR documentation](https://docs.near.org/build/smart-contracts/anatomy/crosscontract#promises) +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_create`] +/// Example usages of this low-level api are and +/// pub fn promise_create( account_id: AccountId, function_name: &str, @@ -775,7 +779,7 @@ pub fn promise_create( } } -/// Attaches the callback that is executed after promise pointed by `promise_idx` is complete. +/// Attaches the callback (which is a [`near_primitives::action::FunctionCallAction`]) that is executed after promise pointed by `promise_idx` is complete. /// /// # Examples /// ``` @@ -805,6 +809,8 @@ pub fn promise_create( /// Gas::from_tgas(30) /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_then`] +/// Example usages of this low-level api are and pub fn promise_then( promise_idx: PromiseIndex, account_id: AccountId, @@ -860,6 +866,7 @@ pub fn promise_then( /// /// let chained_promise = promise_and(&[promise1, promise2]); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_and`] pub fn promise_and(promise_indices: &[PromiseIndex]) -> PromiseIndex { let mut data = vec![0u8; size_of_val(promise_indices)]; for i in 0..promise_indices.len() { @@ -899,6 +906,8 @@ pub fn promise_and(promise_indices: &[PromiseIndex]) -> PromiseIndex { /// All actions in a batch are executed in the order they were added. /// Batched actions act as a unit: they execute in the same receipt, and if any fails, then they all get reverted. /// More information about batching actions can be found in [NEAR documentation](https://docs.near.org/build/smart-contracts/anatomy/actions) +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_create`] +/// See example of usage [here](https://github.com/near/near-sdk-rs/blob/master/examples/factory-contract/low-level/src/lib.rs) pub fn promise_batch_create(account_id: &AccountId) -> PromiseIndex { let account_id: &str = account_id.as_ref(); unsafe { @@ -931,6 +940,7 @@ pub fn promise_batch_create(account_id: &AccountId) -> PromiseIndex { /// Attach a callback NEAR promise to a batch of NEAR promise actions. /// /// More info about batching [here](crate::env::promise_batch_create) +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_then`] pub fn promise_batch_then(promise_index: PromiseIndex, account_id: &AccountId) -> PromiseIndex { let account_id: &str = account_id.as_ref(); unsafe { @@ -957,6 +967,8 @@ pub fn promise_batch_then(promise_index: PromiseIndex, account_id: &AccountId) - /// /// promise_batch_action_create_account(promise); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_create_account`] +/// See example of usage [here](https://github.com/near/near-sdk-rs/blob/master/examples/factory-contract/low-level/src/lib.rs) pub fn promise_batch_action_create_account(promise_index: PromiseIndex) { unsafe { sys::promise_batch_action_create_account(promise_index.0) } } @@ -977,6 +989,8 @@ pub fn promise_batch_action_create_account(promise_index: PromiseIndex) { /// let code = [0; 1487]; /// promise_batch_action_deploy_contract(promise, &code); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_deploy_contract`] +/// See example of usage [here](https://github.com/near/near-sdk-rs/blob/master/examples/factory-contract/low-level/src/lib.rs) pub fn promise_batch_action_deploy_contract(promise_index: PromiseIndex, code: &[u8]) { unsafe { sys::promise_batch_action_deploy_contract( @@ -1009,6 +1023,7 @@ pub fn promise_batch_action_deploy_contract(promise_index: PromiseIndex, code: & /// Gas::from_tgas(30) /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_function_call`] pub fn promise_batch_action_function_call( promise_index: PromiseIndex, function_name: &str, @@ -1052,6 +1067,7 @@ pub fn promise_batch_action_function_call( /// GasWeight(1) /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_function_call_weight`] pub fn promise_batch_action_function_call_weight( promise_index: PromiseIndex, function_name: &str, @@ -1092,6 +1108,8 @@ pub fn promise_batch_action_function_call_weight( /// NearToken::from_near(1), /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_transfer`] +/// See example of usage [here](https://github.com/near/near-sdk-rs/blob/master/examples/factory-contract/low-level/src/lib.rs) pub fn promise_batch_action_transfer(promise_index: PromiseIndex, amount: NearToken) { unsafe { sys::promise_batch_action_transfer( @@ -1121,6 +1139,7 @@ pub fn promise_batch_action_transfer(promise_index: PromiseIndex, amount: NearTo /// &pk /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_stake`] pub fn promise_batch_action_stake( promise_index: PromiseIndex, amount: NearToken, @@ -1158,6 +1177,8 @@ pub fn promise_batch_action_stake( /// nonce /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_add_key_with_full_access`] +/// See example of usage [here](https://github.com/near/near-sdk-rs/blob/master/examples/factory-contract/low-level/src/lib.rs) pub fn promise_batch_action_add_key_with_full_access( promise_index: PromiseIndex, public_key: &PublicKey, @@ -1316,6 +1337,7 @@ pub fn promise_batch_action_add_key_allowance_with_function_call( /// &pk /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_delete_key`] pub fn promise_batch_action_delete_key(promise_index: PromiseIndex, public_key: &PublicKey) { unsafe { sys::promise_batch_action_delete_key( @@ -1344,6 +1366,7 @@ pub fn promise_batch_action_delete_key(promise_index: PromiseIndex, public_key: /// &AccountId::from_str("beneficiary.near").unwrap() /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_batch_action_delete_account`] pub fn promise_batch_action_delete_account( promise_index: PromiseIndex, beneficiary_id: &AccountId, @@ -1368,6 +1391,7 @@ pub fn promise_batch_action_delete_account( /// /// assert_eq!(promise_results_count(), 0); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_results_count`] pub fn promise_results_count() -> u64 { unsafe { sys::promise_results_count() } } @@ -1396,6 +1420,7 @@ pub fn promise_results_count() -> u64 { /// } /// }; /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_result`] pub fn promise_result(result_idx: u64) -> PromiseResult { match promise_result_internal(result_idx) { Ok(()) => { @@ -1436,6 +1461,7 @@ pub(crate) fn promise_result_internal(result_idx: u64) -> Result<(), PromiseErro /// /// promise_return(promise); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_return`] pub fn promise_return(promise_idx: PromiseIndex) { unsafe { sys::promise_return(promise_idx.0) } } @@ -1486,6 +1512,7 @@ pub fn promise_return(promise_idx: PromiseIndex) { /// }).to_string().into_bytes().as_slice() /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_yield_create`] pub fn promise_yield_create( function_name: &str, arguments: &[u8], @@ -1550,6 +1577,7 @@ pub fn promise_yield_create( /// }).to_string().into_bytes().as_slice() /// ); /// ``` +/// More low-level info here: [`near_vm_runner::logic::VMLogic::promise_yield_resume`] pub fn promise_yield_resume(data_id: &CryptoHash, data: &[u8]) -> bool { unsafe { sys::promise_yield_resume( diff --git a/near-sdk/src/promise.rs b/near-sdk/src/promise.rs index c99215f9c..5862c709f 100644 --- a/near-sdk/src/promise.rs +++ b/near-sdk/src/promise.rs @@ -251,6 +251,7 @@ enum PromiseSubtype { impl Promise { /// Create a promise that acts on the given account. + /// Uses low-level [`crate::env::promise_batch_create`] pub fn new(account_id: AccountId) -> Self { Self { subtype: PromiseSubtype::Single(Rc::new(PromiseSingle { @@ -274,16 +275,19 @@ impl Promise { } /// Create account on which this promise acts. + /// Uses low-level [`crate::env::promise_batch_action_create_account`] pub fn create_account(self) -> Self { self.add_action(PromiseAction::CreateAccount) } /// Deploy a smart contract to the account on which this promise acts. + /// Uses low-level [`crate::env::promise_batch_action_deploy_contract`] pub fn deploy_contract(self, code: Vec) -> Self { self.add_action(PromiseAction::DeployContract { code }) } /// A low-level interface for making a function call to the account that this promise acts on. + /// Uses low-level [`crate::env::promise_batch_action_function_call`] pub fn function_call( self, function_name: String, @@ -297,6 +301,7 @@ impl Promise { /// A low-level interface for making a function call to the account that this promise acts on. /// unlike [`Promise::function_call`], this function accepts a weight to use relative unused gas /// on this function call at the end of the scheduling method execution. + /// Uses low-level [`crate::env::promise_batch_action_function_call_weight`] pub fn function_call_weight( self, function_name: String, @@ -315,21 +320,25 @@ impl Promise { } /// Transfer tokens to the account that this promise acts on. + /// Uses low-level [`crate::env::promise_batch_action_transfer`] pub fn transfer(self, amount: NearToken) -> Self { self.add_action(PromiseAction::Transfer { amount }) } /// Stake the account for the given amount of tokens using the given public key. + /// Uses low-level [`crate::env::promise_batch_action_stake`] pub fn stake(self, amount: NearToken, public_key: PublicKey) -> Self { self.add_action(PromiseAction::Stake { amount, public_key }) } /// Add full access key to the given account. + /// Uses low-level [`crate::env::promise_batch_action_add_key_with_full_access`] pub fn add_full_access_key(self, public_key: PublicKey) -> Self { self.add_full_access_key_with_nonce(public_key, 0) } /// Add full access key to the given account with a provided nonce. + /// Uses low-level [`crate::env::promise_batch_action_add_key_with_full_access`] pub fn add_full_access_key_with_nonce(self, public_key: PublicKey, nonce: u64) -> Self { self.add_action(PromiseAction::AddFullAccessKey { public_key, nonce }) } @@ -337,6 +346,7 @@ impl Promise { /// Add an access key that is restricted to only calling a smart contract on some account using /// only a restricted set of methods. Here `function_names` is a comma separated list of methods, /// e.g. `"method_a,method_b".to_string()`. + /// Uses low-level [`crate::env::promise_batch_action_add_key_with_function_call`] pub fn add_access_key_allowance( self, public_key: PublicKey, @@ -366,6 +376,7 @@ impl Promise { } /// Add an access key with a provided nonce. + /// Uses low-level [`crate::env::promise_batch_action_add_key_with_function_call`] pub fn add_access_key_allowance_with_nonce( self, public_key: PublicKey, @@ -403,11 +414,13 @@ impl Promise { } /// Delete access key from the given account. + /// Uses low-level [`crate::env::promise_batch_action_delete_key`] pub fn delete_key(self, public_key: PublicKey) -> Self { self.add_action(PromiseAction::DeleteKey { public_key }) } /// Delete the given account. + /// Uses low-level [`crate::env::promise_batch_action_delete_account`] pub fn delete_account(self, beneficiary_id: AccountId) -> Self { self.add_action(PromiseAction::DeleteAccount { beneficiary_id }) } @@ -425,6 +438,7 @@ impl Promise { /// let p3 = p1.and(p2); /// // p3.create_account(); /// ``` + /// Uses low-level [`crate::env::promise_and`] pub fn and(self, other: Promise) -> Promise { Promise { subtype: PromiseSubtype::Joint(Rc::new(PromiseJoint { @@ -449,6 +463,7 @@ impl Promise { /// let p4 = Promise::new("eva_near".parse().unwrap()).create_account(); /// p1.then(p2).and(p3).then(p4); /// ``` + /// Uses low-level [`crate::env::promise_batch_then`] pub fn then(self, mut other: Promise) -> Promise { match &mut other.subtype { PromiseSubtype::Single(x) => { @@ -491,6 +506,7 @@ impl Promise { /// } /// } /// ``` + /// Makes the promise to use low-level [`crate::env::promise_return`]. #[allow(clippy::wrong_self_convention)] pub fn as_return(self) -> Self { *self.should_return.borrow_mut() = true; diff --git a/near-sdk/src/utils/mod.rs b/near-sdk/src/utils/mod.rs index 6ae2fbf1a..a1ced05cb 100644 --- a/near-sdk/src/utils/mod.rs +++ b/near-sdk/src/utils/mod.rs @@ -90,6 +90,7 @@ pub fn assert_one_yocto() { /// Returns true if promise was successful. /// Fails if called outside a callback that received 1 promise result. +/// Uses low-level [`crate::env::promise_results_count`]. pub fn is_promise_success() -> bool { require!(env::promise_results_count() == 1, "Contract expected a result on the callback"); env::promise_result_internal(0).is_ok() @@ -97,6 +98,7 @@ pub fn is_promise_success() -> bool { /// Returns the result of the promise if successful. Otherwise returns None. /// Fails if called outside a callback that received 1 promise result. +/// Uses low-level [`crate::env::promise_results_count`] and [`crate::env::promise_result`]. pub fn promise_result_as_success() -> Option> { require!(env::promise_results_count() == 1, "Contract expected a result on the callback"); match env::promise_result(0) {