feat: be explicit about detached Promises

[mitinarseny]

This PR annotates Promise, ConcurrentPromises and PromiseOrValue with #[must_use], so that contract devs should be explicit about detaching them.

Promise::new(account_id)
    .transfer(amount)
     // add other actions ...
    .detach(); // <- be explicit about being detached

In general, detached Promises should be discouraged from use, as it ruins composability between different smart-contracts. There still are cases where it's ok to detach, but for the majority of them is a bad design choice. For example, it's currently impossible for a contract to safely refund storage_deposit on some token to the owner of this contract without relying on some trusted party or oracle:

#[derive(near_plugins::Ownable)]
#[near(contract_state)]
pub struct Contract;

#[near]
impl Contract {
    #[only(owner)]
    pub fn storage_withdraw(&self, amount: NearToken) -> Promise {
    ext_storage_management::ext(contract_id)
        .storage_withdraw(amount) // detaches refund Promise internally
        .then(
            Self::ext(env::current_account_id())
                // there is no way to ensure it will be called AFTER refund arrived
                .refund_storage_deposit(amount, env::predecessor_id())
        )
    }

    #[private]
    pub fn refund_storage_deposit(&self, amount: NearToken, refund_to: AccountId) -> Promise {
        require!(matches!(env::promise_result(0), PromiseResult::Success(_)), "storage_withdraw() failed");
        Promise::new(refund_to).transfer(amount)
    }
}

So, it makes sense to add this hint for contract developers to prevent them from misusing this detached functionality.

Of course, another huge blocker for handling such refunds is the absence of functionality to check for attached_amount for one of data receipts accessible via env::promise_result(), but that's a problem of Near Protocol, not near-sdk directly.

[codecov]

Codecov Report

❌ Patch coverage is 76.47059% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.68%. Comparing base (69b695b) to head (5bda0fa).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
...tract-standards/src/fungible_token/storage_impl.rs	0.00%	9 Missing ⚠️
...s/src/non_fungible_token/approval/approval_impl.rs	0.00%	3 Missing ⚠️
...standards/src/non_fungible_token/core/core_impl.rs	0.00%	2 Missing ⚠️
...contract-standards/src/non_fungible_token/utils.rs	0.00%	1 Missing ⚠️
near-sdk/src/promise.rs	98.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1400      +/-   ##
==========================================
- Coverage   80.68%   80.68%   -0.01%     
==========================================
  Files         106      106              
  Lines       15514    15539      +25     
==========================================
+ Hits        12518    12537      +19     
- Misses       2996     3002       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[frol]

This is a nice and elegant solution. Thank you for contributing it!

@race-of-sloths score 5

[race-of-sloths]

@mitinarseny Thank you for your contribution! Your pull request is now a part of the Race of Sloths!
Are you going to win race-of-sloths this month? If so, you should speed up! Run, Sloth, run!

Current status: executed

Reviewer	Score
@frol	5

Your contribution is much appreciated with a final score of 5!
You have received 50 Sloth points for this contribution

@frol received 25 Sloth Points for reviewing and scoring this pull request.

We would appreciate your feedback or contribution idea that you can submit here

What is the Race of Sloths

Race of Sloths is a friendly competition where you can participate in challenges and compete with other open-source contributors within your normal workflow

For contributors:

• Tag @race-of-sloths inside your pull requests
• Wait for the maintainer to review and score your pull request
• Check out your position in the Leaderboard
• Keep weekly and monthly streaks to reach higher positions
• Boast your contributions with a dynamic picture of your Profile

For maintainers:

• Score pull requests that participate in the Race of Sloths and receive a reward
• Engage contributors with fair scoring and fast responses so they keep their streaks
• Promote the Race to the point where the Race starts promoting you
• Grow the community of your contributors

Feel free to check our website for additional details!

Bot commands

• For contributors
  • Include a PR: @race-of-sloths include to enter the Race with your PR
• For maintainers:
  • Invite contributor @race-of-sloths invite to invite the contributor to participate in a race or include it, if it's already a runner.
  • Assign points: @race-of-sloths score [1/2/3/5/8/13] to award points based on your assessment.
  • Reject this PR: @race-of-sloths exclude to send this PR back to the drawing board.
  • Exclude repo: @race-of-sloths pause to stop bot activity in this repo until @race-of-sloths unpause command is called