pub struct Promise { /* private fields */ }
Expand description
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 methodContractB::b
ofbob_near
account, and the return value ofContractA::a
will be whatContractB::b
returned.
#[ext_contract]
pub trait ContractB {
fn b(&mut self);
}
#[near_bindgen]
#[derive(Default, BorshDeserialize, BorshSerialize)]
struct ContractA {}
#[near_bindgen]
impl ContractA {
pub fn a(&self) -> Promise {
contract_b::b("bob_near".parse().unwrap(), 0, Gas(1_000))
}
}
- 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(1000)
.add_full_access_key(env::signer_account_pk());
Implementations
sourceimpl Promise
impl Promise
sourcepub fn create_account(self) -> Self
pub fn create_account(self) -> Self
Create account on which this promise acts.
sourcepub fn deploy_contract(self, code: Vec<u8>) -> Self
pub fn deploy_contract(self, code: Vec<u8>) -> Self
Deploy a smart contract to the account on which this promise acts.
sourcepub fn function_call(
self,
function_name: String,
arguments: Vec<u8>,
amount: Balance,
gas: Gas
) -> Self
pub fn function_call(
self,
function_name: String,
arguments: Vec<u8>,
amount: Balance,
gas: Gas
) -> Self
A low-level interface for making a function call to the account that this promise acts on.
sourcepub fn transfer(self, amount: Balance) -> Self
pub fn transfer(self, amount: Balance) -> Self
Transfer tokens to the account that this promise acts on.
sourcepub fn stake(self, amount: Balance, public_key: PublicKey) -> Self
pub fn stake(self, amount: Balance, public_key: PublicKey) -> Self
Stake the account for the given amount of tokens using the given public key.
sourcepub fn add_full_access_key(self, public_key: PublicKey) -> Self
pub fn add_full_access_key(self, public_key: PublicKey) -> Self
Add full access key to the given account.
sourcepub fn add_full_access_key_with_nonce(
self,
public_key: PublicKey,
nonce: u64
) -> Self
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.
sourcepub fn add_access_key(
self,
public_key: PublicKey,
allowance: Balance,
receiver_id: AccountId,
function_names: String
) -> Self
pub fn add_access_key(
self,
public_key: PublicKey,
allowance: Balance,
receiver_id: AccountId,
function_names: 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".to_string()
.
sourcepub fn add_access_key_with_nonce(
self,
public_key: PublicKey,
allowance: Balance,
receiver_id: AccountId,
function_names: String,
nonce: u64
) -> Self
pub fn add_access_key_with_nonce(
self,
public_key: PublicKey,
allowance: Balance,
receiver_id: AccountId,
function_names: String,
nonce: u64
) -> Self
Add an access key with a provided nonce.
sourcepub fn delete_key(self, public_key: PublicKey) -> Self
pub fn delete_key(self, public_key: PublicKey) -> Self
Delete access key from the given account.
sourcepub fn delete_account(self, beneficiary_id: AccountId) -> Self
pub fn delete_account(self, beneficiary_id: AccountId) -> Self
Delete the given account.
sourcepub fn and(self, other: Promise) -> Promise
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();
sourcepub fn then(self, other: Promise) -> Promise
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);
sourcepub fn as_return(self) -> Self
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_bindgen]
#[derive(Default, BorshDeserialize, BorshSerialize)]
struct ContractA {}
#[near_bindgen]
impl ContractA {
pub fn a1(&self) {
contract_b::b("bob_near".parse().unwrap(), 0, Gas(1_000)).as_return();
}
pub fn a2(&self) -> Promise {
contract_b::b("bob_near".parse().unwrap(), 0, Gas(1_000))
}
}
Trait Implementations
sourceimpl BorshSchema for Promise
impl BorshSchema for Promise
Until we implement strongly typed promises we serialize them as unit struct.
sourcefn add_definitions_recursively(
definitions: &mut HashMap<Declaration, Definition>
)
fn add_definitions_recursively(
definitions: &mut HashMap<Declaration, Definition>
)
Recursively, using DFS, add type definitions required for this type. For primitive types this is an empty map. Type definition explains how to serialize/deserialize a type. Read more
sourcefn declaration() -> Declaration
fn declaration() -> Declaration
Get the name of the type without brackets.
sourcefn add_definition(
declaration: String,
definition: Definition,
definitions: &mut HashMap<String, Definition, RandomState>
)
fn add_definition(
declaration: String,
definition: Definition,
definitions: &mut HashMap<String, Definition, RandomState>
)
Helper method to add a single type definition to the map.
fn schema_container() -> BorshSchemaContainer
sourceimpl BorshSerialize for Promise
impl BorshSerialize for Promise
sourceimpl<T> From<Promise> for PromiseOrValue<T>
impl<T> From<Promise> for PromiseOrValue<T>
Auto Trait Implementations
impl !RefUnwindSafe for Promise
impl !Send for Promise
impl !Sync for Promise
impl Unpin for Promise
impl !UnwindSafe for Promise
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more