comments from PR 1259

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"]

near-sdk/src/environment/env.rs

@@ -225,6 +225,7 @@ fn assert_valid_account_id(bytes: Vec<u8>) -> 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<Vec<u8>> {
     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 <https://github.com/near/near-sdk-rs/tree/master/examples/factory-contract/low-level/src/lib.rs> and <https://github.com/near/near-sdk-rs/blob/master/examples/cross-contract-calls/low-level/src/lib.rs> 
+///
 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 <https://github.com/near/near-sdk-rs/tree/master/examples/factory-contract/low-level/src/lib.rs> and <https://github.com/near/near-sdk-rs/blob/master/examples/cross-contract-calls/low-level/src/lib.rs>
 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(

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<u8>) -> 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,28 +320,33 @@ 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 })
     }
 
     /// 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;

near-sdk/src/utils/mod.rs

@@ -90,13 +90,15 @@ 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()
 }
 
 /// 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<Vec<u8>> {
     require!(env::promise_results_count() == 1, "Contract expected a result on the callback");
     match env::promise_result(0) {