Struct Promise 

pub struct Promise { /* private fields */ }

A structure representing a result of the scheduled execution on another contract.

Smart contract developers will explicitly use Promise in two situations:

• When they need to return Promise.

  In the following code if someone calls method ContractA::a they will internally cause an execution of method ContractB::b of bob_near account, and the return value of ContractA::a will be what ContractB::b returned.

#[ext_contract]
pub trait ContractB {
    fn b(&mut self);
}

#[near(contract_state)]
#[derive(Default)]
struct ContractA {}

#[near]
impl ContractA {
    pub fn a(&self) -> Promise {
        contract_b::ext("bob_near".parse().unwrap()).b()
    }
}

• When they need to create a transaction with one or many actions, e.g. the following code schedules a transaction that creates an account, transfers tokens, and assigns a public key:

Promise::new("bob_near".parse().unwrap())
  .create_account()
  .transfer(NearToken::from_yoctonear(1000))
  .add_full_access_key(env::signer_account_pk());

More information about promises in NEAR documentation

Implementations

impl Promise

pub fn new(account_id: AccountId) -> Self

Create a promise that acts on the given account. Uses low-level crate::env::promise_batch_create

pub fn new_yield( function_name: &str, arguments: impl AsRef<[u8]>, gas: Gas, weight: GasWeight, ) -> (Self, YieldId)

Create a yielded promise that suspends execution until resumed.

Returns a tuple of (Promise, YieldId) where:

• The Promise represents the yielded execution that will call function_name when resumed
• The YieldId can be stored and used later to resume the promise with YieldId::resume

Arguments

• function_name - The callback function to invoke when the promise is resumed
• arguments - Arguments to pass to the callback function
• gas - Base gas to allocate for the callback
• weight - Gas weight for distributing remaining gas

Important

Yielded promises have a restriction:

• Cannot be used as continuations: Using a yielded promise in other.then(yielded) will panic. Yielded promises must be first in the chain: yielded.then(other) is valid.

Example

use near_sdk::{Promise, Gas, GasWeight};

// Create a yielded promise
let (promise, yield_id) = Promise::new_yield(
    "on_data_received",
    vec![],
    Gas::from_tgas(10),
    GasWeight(1),
);

// Chain another promise after the yielded one (valid)
promise.then(Promise::new("other.near".parse().unwrap()).create_account());

// Store yield_id to resume later from another transaction

Uses low-level crate::env::promise_yield_create

pub fn new_yield_with_id( function_name: &str, arguments: impl AsRef<[u8]>, deposit: NearToken, gas: Gas, weight: GasWeight, yield_id: UserYieldId, ) -> Option<Self>

Create a yielded promise with a caller-provided UserYieldId and an optional deposit.

Like Promise::new_yield, but the caller supplies the resumption identifier instead of the runtime generating one. The promise is later resumed with the same id via UserYieldId::resume, so the creator and the resumer can derive the id independently (e.g. from a request id) without round-tripping a runtime-generated data_id.

Returns None if a yield with the same yield_id is already pending for the current account, letting the caller detect and recover from duplicates instead of aborting.

Arguments

• function_name - The callback function to invoke when the promise is resumed
• arguments - Arguments to pass to the callback function
• deposit - Amount of NEAR to attach to the callback (use NearToken::from_yoctonear(0) for none)
• gas - Base gas to allocate for the callback
• weight - Gas weight for distributing remaining gas
• yield_id - The caller-provided 32-byte resumption identifier

Requirements

Requires the host to support the yield-with-id functions (nearcore protocol version 85+, shipped in nearcore 2.13).

Important

Like Promise::new_yield, the resulting promise cannot be used as a continuation (other.then(yielded) panics); it must come first in a chain.

Uses low-level crate::env::promise_yield_create_with_id

pub fn create_account(self) -> Self

Create account on which this promise acts. Uses low-level crate::env::promise_batch_action_create_account

pub fn deploy_contract(self, code: impl Into<Vec<u8>>) -> Self

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_global_contract(self, code: impl Into<Vec<u8>>) -> Self

Deploy a global smart contract using the provided contract code. Uses low-level crate::env::promise_batch_action_deploy_global_contract

Examples

use near_sdk::{Promise, NearToken};

let code = vec![0u8; 100]; // Contract bytecode
Promise::new("alice.near".parse().unwrap())
    .create_account()
    .transfer(NearToken::from_yoctonear(1000))
    .deploy_global_contract(code);

pub fn deploy_global_contract_by_account_id( self, code: impl Into<Vec<u8>>, ) -> Self

Deploy a global smart contract, identifiable by the predecessor’s account ID. Uses low-level crate::env::promise_batch_action_deploy_global_contract_by_account_id

Examples

use near_sdk::{Promise, NearToken};

let code = vec![0u8; 100]; // Contract bytecode
Promise::new("alice.near".parse().unwrap())
    .create_account()
    .transfer(NearToken::from_yoctonear(1000))
    .deploy_global_contract_by_account_id(code);

pub fn use_global_contract(self, code_hash: impl Into<CryptoHash>) -> Self

Use an existing global contract by code hash. Uses low-level crate::env::promise_batch_action_use_global_contract

Examples

use near_sdk::{Promise, NearToken};

let code_hash = [0u8; 32]; // 32-byte hash (CryptoHash)
Promise::new("alice.near".parse().unwrap())
    .create_account()
    .transfer(NearToken::from_yoctonear(1000))
    .use_global_contract(code_hash);

pub fn use_global_contract_by_account_id(self, account_id: AccountId) -> Self

Use an existing global contract by referencing the account that deployed it. Uses low-level crate::env::promise_batch_action_use_global_contract_by_account_id

Examples

use near_sdk::{Promise, NearToken};

Promise::new("alice.near".parse().unwrap())
    .create_account()
    .transfer(NearToken::from_yoctonear(1000))
    .use_global_contract_by_account_id("deployer.near".parse().unwrap());

pub fn function_call( self, function_name: impl Into<String>, arguments: impl Into<Vec<u8>>, amount: NearToken, gas: Gas, ) -> Self

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_weight( self, function_name: impl Into<String>, arguments: impl Into<Vec<u8>>, amount: NearToken, gas: Gas, weight: GasWeight, ) -> Self

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 transfer(self, amount: NearToken) -> Self

Transfer tokens to the account that this promise acts on. Uses low-level crate::env::promise_batch_action_transfer

pub fn stake(self, amount: NearToken, public_key: PublicKey) -> Self

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 add_full_access_key(self, public_key: PublicKey) -> Self

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_with_nonce( self, public_key: PublicKey, nonce: u64, ) -> Self

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_access_key_allowance( self, public_key: PublicKey, allowance: Allowance, receiver_id: AccountId, function_names: impl Into<String>, ) -> Self

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". Uses low-level crate::env::promise_batch_action_add_key_allowance_with_function_call

pub fn add_access_key( self, public_key: PublicKey, allowance: NearToken, receiver_id: AccountId, function_names: impl Into<String>, ) -> Self

👎Deprecated since 5.0.0:

Use add_access_key_allowance instead

pub fn add_access_key_allowance_with_nonce( self, public_key: PublicKey, allowance: Allowance, receiver_id: AccountId, function_names: impl Into<String>, nonce: u64, ) -> Self

Add an access key with a provided nonce. Uses low-level crate::env::promise_batch_action_add_key_allowance_with_function_call

pub fn add_access_key_with_nonce( self, public_key: PublicKey, allowance: NearToken, receiver_id: AccountId, function_names: impl Into<String>, nonce: u64, ) -> Self

👎Deprecated since 5.0.0:

Use add_access_key_allowance_with_nonce instead

pub fn delete_key(self, public_key: PublicKey) -> Self

Delete access key from the given account. Uses low-level crate::env::promise_batch_action_delete_key

pub fn delete_account(self, beneficiary_id: AccountId) -> Self

Delete the given account. Uses low-level crate::env::promise_batch_action_delete_account

pub fn transfer_to_gas_key( self, public_key: PublicKey, amount: NearToken, ) -> Self

Transfer tokens to a gas key on the account that this promise acts on. Uses low-level crate::env::promise_batch_action_transfer_to_gas_key

Requirements

Requires the host to support gas-key host functions (nearcore protocol version 85+, shipped in nearcore 2.13).

pub fn add_gas_key_full_access( self, public_key: PublicKey, num_nonces: u32, ) -> Self

Add a full access gas key to the given account, reserving num_nonces parallel nonces. Uses low-level crate::env::promise_batch_action_add_gas_key_with_full_access

Requirements

Requires the host to support gas-key host functions (nearcore protocol version 85+, shipped in nearcore 2.13).

pub fn add_gas_key_allowance_function_call( self, public_key: PublicKey, num_nonces: u32, allowance: Allowance, receiver_id: AccountId, function_names: String, ) -> Self

Add a gas key restricted to only calling a smart contract on some account using only a restricted set of methods, reserving num_nonces parallel nonces. Here function_names is a comma separated list of methods, e.g. "method_a,method_b". Uses low-level crate::env::promise_batch_action_add_gas_key_with_function_call

Requirements

Requires the host to support gas-key host functions (nearcore protocol version 85+, shipped in nearcore 2.13).

pub fn and(self, other: Promise) -> Promise

Merge this promise with another promise, so that we can schedule execution of another smart contract right after all merged promises finish.

Note, once the promises are merged it is not possible to add actions to them, e.g. the following code will panic during the execution of the smart contract:

let p1 = Promise::new("bob_near".parse().unwrap()).create_account();
let p2 = Promise::new("carol_near".parse().unwrap()).create_account();
let p3 = p1.and(p2);
// p3.create_account();

Uses low-level crate::env::promise_and

pub fn then(self, other: Promise) -> Promise

Schedules execution of another promise right after the current promise finish executing.

In the following code bob_near and dave_near will be created concurrently. carol_near creation will wait for bob_near to be created, and eva_near will wait for both carol_near and dave_near to be created first.

let p1 = Promise::new("bob_near".parse().unwrap()).create_account();
let p2 = Promise::new("carol_near".parse().unwrap()).create_account();
let p3 = Promise::new("dave_near".parse().unwrap()).create_account();
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_concurrent( self, promises: impl IntoIterator<Item = Promise>, ) -> ConcurrentPromises

Schedules execution of multiple concurrent promises right after the current promise finishes executing.

This method will send the same return value as a data receipt to all following receipts.

In the following code, bob_near is created first, carol_near second, and finally dave_near and eva_near are created concurrently.

let p1 = Promise::new("bob_near".parse().unwrap()).create_account();
let p2 = Promise::new("carol_near".parse().unwrap()).create_account();
let p3 = Promise::new("dave_near".parse().unwrap()).create_account();
let p4 = Promise::new("eva_near".parse().unwrap()).create_account();
p1.then(p2).then_concurrent([p3, p4]);

The returned ConcurrentPromises allows chaining more promises.

In the following code, bob_near is created first, next carol_near and dave_near are created concurrently, and finally eva_near is created after all others have been created.

let p1 = Promise::new("bob_near".parse().unwrap()).create_account();
let p2 = Promise::new("carol_near".parse().unwrap()).create_account();
let p3 = Promise::new("dave_near".parse().unwrap()).create_account();
let p4 = Promise::new("eva_near".parse().unwrap()).create_account();
p1.then_concurrent([p2, p3]).join().then(p4);

pub fn as_return(self) -> Self

A specialized, relatively low-level API method. Allows to mark the given promise as the one that should be considered as a return value.

In the below code a1 and a2 functions are equivalent.

#[ext_contract]
pub trait ContractB {
    fn b(&mut self);
}

#[near(contract_state)]
#[derive(Default)]
struct ContractA {}

#[near]
impl ContractA {
    pub fn a1(&self) {
       contract_b::ext("bob_near".parse().unwrap()).b().as_return();
    }

    pub fn a2(&self) -> Promise {
       contract_b::ext("bob_near".parse().unwrap()).b()
    }
}

Makes the promise to use low-level crate::env::promise_return.

pub fn detach(self)

Explicitly detach given promise

Trait Implementations

impl BorshSchema for Promise

Available on crate feature abi only.

Until we implement strongly typed promises we serialize them as unit struct.

fn add_definitions_recursively( definitions: &mut BTreeMap<Declaration, Definition>, )

Recursively, using DFS, add type definitions required for this type. Type definition partially explains how to serialize/deserialize a type.

fn declaration() -> Declaration

Get the name of the type without brackets.

impl BorshSerialize for Promise

fn serialize<W: Write>(&self, _writer: &mut W) -> Result<(), Error>

impl Drop for Promise

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T> From<Promise> for PromiseOrValue<T>

fn from(promise: Promise) -> Self

Converts to this type from the input type.

impl JsonSchema for Promise

Available on crate feature abi only.

fn schema_name() -> String

The name of the generated JSON Schema.

fn json_schema(_gen: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

impl Serialize for Promise

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.