dApp-to-App Invocation#
A dApp callable function can invoke a callable function of another dApp, or another callable function of the same dApp, or even itself. The invocation is synchronous. The invoked function returns a value that the invoking function can use.
dApp-to-dApp invocation is processed as follows:
A user sends an Invoke Script transaction that invokes the callable function \(1\).
The callable function \(1\) invokes the callable function \(2\) via a strict variable initialized by the invoke or reentrantInvoke function.
The callable function \(2\) is executed; the script actions and return value are calculated.
The return value is assigned to the strict variable. The subsequent operations of callable function 1 are executed, taking into account script actions of callable function \(2\) (as if the actions were applied to the blockchain state).
Finally, the script actions of callable functions \(2\) and \(1\) are applied to the blockchain state.
Features#
dApp-to-dApp invocations can be nested.
All invoked callable functions are executed within a single Invoke Script transaction.
A dApp-to-dApp invocation can contain payments that are transferred from the balance of the parent dApp to the balance of the invoked dApp.
Payments attached to a callable function invocation can be used in script actions and in payments attached to nested invocations.
Conditions#
Both the parent and invoked dApp scripts use standard library version 5.
If the dApp invokes itself, the invocation must not contain payments.
The number of the invoke or reentrantInvoke function calls is up to 100 within a single Invoke Script transaction.
The maximum total number of Issue, Reissue, Burn, SponsorFee, ScriptTransfer, Lease, LeaseCancel script actions executed by all callable functions in a single transaction is \(30\).
The maximum total number of BinaryEntry, BooleanEntry, IntegerEntry, StringEntry, DeleteEntry script actions executed by all callable functions in a single transaction is \(100\).
The total complexity is limited by \(26,000\) for all callable functions and asset scripts of involved smart assets. The sender’s account script complexity is not included in that limit.
Strict Variable#
strict keyword defines a variable with eager evaluation. Unlike lazy variables defined with let, a strict variable is evaluated immediately when script execution reaches it, that is, before the next expression.
Invoke and reentrantInvoke Functions#
invoke(dApp: Address|Alias, function: String, arguments: List[Any], payments: List[AttachedPayments]): Any
reentrantInvoke(dApp: Address|Alias, function: String, arguments: List[Any], payments: List[AttachedPayments]): Any
Parameters:
Parameter |
Description |
|---|---|
dApp: Address|Alias |
Address or alias of a dApp to invoke. |
function: String|Unit |
Name of a callable function. unit for a default function invocation. |
arguments: List[Any] |
Parameters of a callable function. |
payments: List[AttachedPayment] |
Payments to transfer from the parent dApp to the invoked dApp, up to \(10\). |
strict z = invoke(dapp,foo,args,[AttachedPayment(unit,100000000)])
The return value is of type Any, which means any valid type. You can extract a particular type from it using as[T] and exactAs[T] macros or the match … case operator, see the any article.
The invoke and reentrantInvoke functions differ only in the reentrancy restriction. For details, see the dApp-to-dApp invocation function article.
Invocation Fields#
For dApp-to-dApp invocation, the fields of Invocation structure used by the invoked function are filled with the following values:
# |
Name |
Data type |
Description |
|---|---|---|---|
\(1\) |
caller |
address of the dApp that invokes the callable function. |
|
\(2\) |
callerPublicKey |
Public key of the dApp that invokes the callable function. |
|
\(3\) |
originCaller |
Address |
Address of the account that sent the invoke script transaction. |
\(4\) |
originCallerPublicKey |
Public key of the account that sent the invoke script transaction. |
|
\(5\) |
payments |
Payments indicated in the invoke or reentrantInvoke function. |
|
\(6\) |
transactionId |
ID of the invoke script transaction. |
|
\(7\) |
fee |
||
\(8\) |
feeAssetId |
ID of the fee token. |
Callable Function Result#
In standard library version 5, a callable function result is a tuple of two elements:
List of script actions.
Return value that is passed to the invoking function.
Let’s see an example:
(
[
ScriptTransfer(i.caller,100,unit)
],
42
)
In standard library version 4 or 3, there is no return value, so unit is implied.
For details, see the callable function article.
Updating Balance and Account Data Storage Entries#
If the callable function invoked by the invoke or reentrantInvoke function performs script actions, the results of those actions are available to the invoking function:
If the invoked function adds an entry to the account’s data storage, the invoking function can obtain the entry after the invocation.
If the invoked function deletes an entry from the account’s data storage, the invoking function cannot obtain the entry after the invocation.
If the invoked function performs actions with tokens (transfer, issue/reissue/burn, and others) and the invoking function obtains balances after the invocation, it receives the updated balances.
Transaction Fail#
If the callable function’s execution fails or throws an exception, the Invoke Script transaction could be rejected or saved on the blockchain as failed. This depends on whether the complexity of performed computations has exceeded the threshold for saving a failed transaction (currently \(1000\)). The complexity is summed up for all invocations.
Consider the example: callable function \(1\) performs computations of 800 complexity, then invokes callable function \(2\) which performs computations of 300 complexity and then fails. The complexity \(800 + 300\) has exceeded the threshold, so the transaction is saved as failed, and the sender is charged a fee.
If the total complexity of executed callable functions and asset scripts exceeds the limit of \(26,000\), the transaction is saved as failed as well. For example, if the complexity of executed callable functions is \(25,000\) in total, and there is a smart asset in script action whose script’s complexity is \(1500\).
In case of failure, no payments and script actions are applied to the blockchain state, even if some of the invoked functions are executed completely. The only state change the failed transaction entails is charging the fee.
Limitations#
Limitation |
Maximum value |
|---|---|
dApp script size |
\(32\) Kbytes. |
Account script or asset script size |
\(8\) Kbytes. |
Complexity of account script |
\(2000\) |
Complexity of asset script |
\(4000\) |
Complexity of each callable function of dApp script |
\(10,000\) |
Total number of dApp-to-dApp invocations within a single Invoke Script transaction |
\(100\) |
Total complexity for all callable functions and asset scripts involved in an Invoke Script transaction. The sender’s account script complexity is not included in this limit |
\(26,000\) |
Complexity threshold for saving failed transactions: if the callable function failed with an error or throwing an exception before the threshold exceeded, the invoke script transaction is rejected and the fee is not charged |
\(1000\) |
Complexity of verifier function of dApp script |
\(2000\) |
Sender complexity threshold: if the complexity of an account script or the verifier function of a dApp script exceeds this limit, the minimum fee for a transaction sent from the account is increased by 0.004 DecentralCoins |
\(200\) |
Function name or variable name |
\(255\) bytes |
Size of String variable |
\(32,767\) bytes |
Size of ByteVector variable |
\(32,767\) bytes (except bodyBytes field of transaction structure). |
Data weight |
See data weight. |
Number of callable function arguments |
\(22\) |
Number of payments attached to an invocation |
\(10\) |
Total number of Issue, Reissue, Burn, SponsorFee, ScriptTransfer, Lease, and LeaseCancel script actions executed by all callable functions in a single transaction |
\(30\) |
Total number of BinaryEntry, BooleanEntry, DeleteEntry, IntegerEntry, StringEntry script actions executed by all callable functions in a single transaction |
\(100\) |
Total size of data written to the account data storage by all BinaryEntry, BooleanEntry, IntegerEntry, StringEntry script actions executed by a callable function |
\(5\) Kbytes. |
Total size of data written to the account data storage by all BinaryEntry, BooleanEntry, IntegerEntry, StringEntry script actions executed by all callable functions in a single transaction |
\(15\) Kbytes. |
Script Complexity#
Script complexity is a dimensionless quantity that estimates computational resources needed to execute a script. The complexity of a script is estimated based on complexities of all the operators and functions it consists of. The complexity of the built-in functions is listed in the built-in functions article.
Limitations on script complexity are given in the limitations article.
Data Weight#
The weight of each value approximately corresponds to its size in bytes. Weight is used in limitations on creating and comparing values.
Weight Calculation#
Data type |
Weight of value |
|---|---|
\(64\) |
|
\(1\) |
|
Size in bytes. |
|
\(8\) |
|
See weight of list below. |
|
Size in bytes. |
|
See weight of tuple or structure. |
|
See weight of tuple or structure. |
|
\(40\) |
Weight of List#
The weight of the list is calculated as follows:
\(W_{list} = 20 + 20 × Q + W_{elems}\)
where:
\(Q\) is a number of elements.
\(W_{elems}\) is a total weight of elements.
Weight of Tuple or Structure#
The weight of the tuple or structure is calculated as follows:
\(W_{struct} = 40 + 30 × Q + W_{fields}\)
where:
\(Q\) is a number of fields.
\(W_{fields}\) is a total weight of fields.
Weight Limitations#
The maximum weight of the value is \(307200\).
A comparison of values is not allowed if the weight of each value exceeds \(13000\).
If the limitations are exceeded, the script fails.
Let’s consider an example, using the AssetPair structure:
AssetPair(amountAsset: ByteVector|Unit, priceAsset: ByteVector|Unit)
An asset ID is a ByteVector of \(32\) bytes, its weight is \(32\). If both assets in the pair are not DecentralCoins, then the weight of the AssetPair structure is:
\(W_{AssetPair} = 40 + 30 × 2 + (32 + 32) = 164\)
If one of the assets is DecentralCoin, then the corresponding field is of type Unit and its weight is \(40\). Then the weight of the AssetPair structure is:
\(W_{AssetPair} = 40 + 30 × 2 + (32 + 40) = 172\)