waves_logo Docs
  • Ride Programming Language
    Ride Programming Language
  • Getting Started
    Getting Started
  • Syntax Basics
    • Directives
      Directives
    • Definition
      Definition
    • Expression
      Expression
    • Constant
      Constant
    • Variable
      Variable
    • Function
      Function
    • Exception
      Exception
    • Comment
      Comment
    Syntax Basics
  • Script Types
    • dApp Script
      • Annotations
        Annotations
      • Callable Function
        Callable Function
      • Verifier Function
        Verifier Function
      dApp Script
    • Account Script
      Account Script
    • Asset Script
      Asset Script
    Script Types
  • Standard Library
    Standard Library
  • Data types
    • Boolean
      Boolean
    • ByteVector
      ByteVector
    • Int
      Int
    • String
      String
    • Unit
      Unit
    • List
      List
    • Tuple
      Tuple
    • Union
      Union
    Data types
  • Structures
    • Script Actions
      • BinaryEntry (v4)
        BinaryEntry (v4)
      • BooleanEntry (v4)
        BooleanEntry (v4)
      • Burn (v4)
        Burn (v4)
      • DataEntry (v3)
        DataEntry (v3)
      • DeleteEntry (v4)
        DeleteEntry (v4)
      • IntegerEntry (v4)
        IntegerEntry (v4)
      • Issue (v4)
        Issue (v4)
      • Reissue (v4)
        Reissue (v4)
      • ScriptTransfer (v3 and v4)
        ScriptTransfer (v3 and v4)
      • SponsorFee (v4)
        SponsorFee (v4)
      • StringEntry (v4)
        StringEntry (v4)
      Script Actions
    • Script Results (v3)
      • ScriptResult
        ScriptResult
      • TransferSet
        TransferSet
      • WriteSet
        WriteSet
      Script Results (v3)
    • Common Structures
      • Address
        Address
      • Alias
        Alias
      • Asset
        Asset
      • AssetPair
        AssetPair
      • AttachedPayment
        AttachedPayment
      • BalanceDetails
        BalanceDetails
      • BlockInfo
        BlockInfo
      • Invocation
        Invocation
      • Order
        Order
      • Transfer
        Transfer
      Common Structures
    • Transaction Structures
      • BurnTransaction
        BurnTransaction
      • CreateAliasTransaction
        CreateAliasTransaction
      • DataTransaction
        DataTransaction
      • ExchangeTransaction
        ExchangeTransaction
      • GenesisTransaction
        GenesisTransaction
      • InvokeScriptTransaction
        InvokeScriptTransaction
      • IssueTransaction
        IssueTransaction
      • LeaseCancelTransaction
        LeaseCancelTransaction
      • LeaseTransaction
        LeaseTransaction
      • MassTransferTransaction
        MassTransferTransaction
      • ReissueTransaction
        ReissueTransaction
      • SetAssetScriptTransaction
        SetAssetScriptTransaction
      • SetScriptTransaction
        SetScriptTransaction
      • SponsorFeeTransaction
        SponsorFeeTransaction
      • TransferTransaction
        TransferTransaction
      • UpdateAssetInfoTransaction
        UpdateAssetInfoTransaction
      Transaction Structures
    Structures
  • Built-in Variables
    Built-in Variables
  • Built-in Functions
    • Account Data Storage Functions
      Account Data Storage Functions
    • Blockchain Functions
      Blockchain Functions
    • Byte Array Functions
      Byte Array Functions
    • Converting Functions
      Converting Functions
    • Data Transaction Functions
      Data Transaction Functions
    • Decoding Functions
      Decoding Functions
    • Encoding Functions
      Encoding Functions
    • Exception Functions
      Exception Functions
    • Hashing Functions
      Hashing Functions
    • List Functions
      List Functions
    • Math Functions
      Math Functions
    • String Functions
      String Functions
    • Union Functions
      Union Functions
    • Verification Functions
      Verification Functions
    Built-in Functions
  • Operators
    Operators
  • Pattern Matching: match-case
    Pattern Matching: match-case
  • Interations with FOLD<N>
    Interations with FOLD<N>
  • Limitations
    • Complexity
      Complexity
    • Data Weight
      Data Weight
    Limitations
  • Version 5 (Stagenet)
    • dApp-to-dApp Invocation
      dApp-to-dApp Invocation
    • Continued Computations
      Continued Computations
    • Strict Variable
      Strict Variable
    • Callable Function
      Callable Function
    • Data types
      • Any
        Any
      • Boolean
        Boolean
      • ByteVector
        ByteVector
      • Int
        Int
      • String
        String
      • Unit
        Unit
      • List
        List
      • Tuple
        Tuple
      • Union
        Union
      Data types
    • Structures
      • Script Actions
        • BinaryEntry
          BinaryEntry
        • BooleanEntry
          BooleanEntry
        • Burn
          Burn
        • DeleteEntry
          DeleteEntry
        • IntegerEntry
          IntegerEntry
        • Issue
          Issue
        • Lease
          Lease
        • LeaseCancel
          LeaseCancel
        • Reissue
          Reissue
        • ScriptTransfer
          ScriptTransfer
        • SponsorFee
          SponsorFee
        • StringEntry
          StringEntry
        Script Actions
      • Common Structures
        • Address
          Address
        • Alias
          Alias
        • Asset
          Asset
        • AssetPair
          AssetPair
        • AttachedPayment
          AttachedPayment
        • BalanceDetails
          BalanceDetails
        • BlockInfo
          BlockInfo
        • Invocation
          Invocation
        • Order
          Order
        • Transfer
          Transfer
        Common Structures
      • Transaction Structures
        • BurnTransaction
          BurnTransaction
        • CreateAliasTransaction
          CreateAliasTransaction
        • DataTransaction
          DataTransaction
        • ExchangeTransaction
          ExchangeTransaction
        • GenesisTransaction
          GenesisTransaction
        • InvokeScriptTransaction
          InvokeScriptTransaction
        • IssueTransaction
          IssueTransaction
        • LeaseCancelTransaction
          LeaseCancelTransaction
        • LeaseTransaction
          LeaseTransaction
        • MassTransferTransaction
          MassTransferTransaction
        • ReissueTransaction
          ReissueTransaction
        • SetAssetScriptTransaction
          SetAssetScriptTransaction
        • SetScriptTransaction
          SetScriptTransaction
        • SponsorFeeTransaction
          SponsorFeeTransaction
        • TransferTransaction
          TransferTransaction
        • UpdateAssetInfoTransaction
          UpdateAssetInfoTransaction
        Transaction Structures
      Structures
    • Built-in Variables
      Built-in Variables
    • Built-in Functions
      • Account Data Storage Functions
        Account Data Storage Functions
      • Blockchain Functions
        Blockchain Functions
      • Byte Array Functions
        Byte Array Functions
      • Converting Functions
        Converting Functions
      • Data Transaction Functions
        Data Transaction Functions
      • Decoding Functions
        Decoding Functions
      • Encoding Functions
        Encoding Functions
      • Exception Functions
        Exception Functions
      • Hashing Functions
        Hashing Functions
      • dApp-to-dApp Invocation Function
        dApp-to-dApp Invocation Function
      • List Functions
        List Functions
      • Math Functions
        Math Functions
      • String Functions
        String Functions
      • Union Functions
        Union Functions
      • Verification Functions
        Verification Functions
      Built-in Functions
    • Operators
      Operators
    • Limitations
      Limitations
    Version 5 (Stagenet)
  • Ride Components
    Ride Components
  • Script performance tests
    Script performance tests
      • English
      • Русский
      On this page
        • Annotation
        • Version 4
        • Version 3
        • Threshold for Saving Failed Transactions
      waves_logo Docs

          # Callable function

          Callable function is a dApp script function which can be invoked externally by invoke script transaction.

          dApp script can contain multiple callable functions.

          Callable functions features rely on standard library version:

          Standard library v3 Standard library v4
          Adding and modifying of account data storage entries Adding, modifying, deleting of account data storage entries
          Token transfers Token transfers
          Issue, reissue, burning tokens
          Sponsorship setup

          The invoke script transaction can have payments in favor of dApp applied. Funds obtained in this payments can be included in token transfers.

          Standard library v4 is available starting from node version 1.2.0 after activation of feature #15 “Ride V4, VRF, Protobuf, Failed transactions”.

          ⚠️ After activation of the feature #15, the fee for the invoke script transaction cannot be funded by transfer from the dApp to the transaction sender. If sender's balance is insufficient to pay the fee, dApp script is not executed.

          # Annotation

          The callable function should be marked with the @Callable(i) annotation, where i is an Invocation structure that contains invoke script transaction fields that are available to the callable function. The variable name in the annotation is required even if the called function does not use it.

          # Version 4

          # Arguments

          Callable function can have arguments of the following types:

          • Boolean,
          • ByteVector,
          • Int,
          • String,
          • Union with elements having types listed above.
          • List having elements of the following types:
            • Boolean,
            • ByteVector,
            • Int,
            • String,
            • List.

          # Invocation result

          Callable function invocation result in Standard library version 4 is a list of script actions. Actions are executed in the same order as the elements in the list.

          Example:

          [
             BooleanEntry("key1", true),
             IntegerEntry("key2", 42),
             StringEntry("key3", "some string"),
             BinaryEntry("key4", base58'encoded'),
             DeleteEntry("key4"),
             ScriptTransfer(Address(base58'3Ms8fSfAxBLDjKvNVgACRzQoBLCtCWxtawu'), 100, base58'someAssetid'),
             Issue("RegularToken", "This is an ordinary token", 10000, 2, true),
             Reissue("4ZzED8WJXsvuo2MEm2BmZ87Azw8Sx7TVC6ufSUA5LyTV", 1000, true),
             Burn("4ZzED8WJXsvuo2MEm2BmZ87Azw8Sx7TVC6ufSUA5LyTV", 1000)]
             SponsorFee("4ZzED8WJXsvuo2MEm2BmZ87Azw8Sx7TVC6ufSUA5LyTV", 300)
          ]
          

          # Script actions

          Script actions executed by the callable function are set by Ride structures.

          Ride structure that sets action Description
          - BinaryEntry
          - BooleanEntry
          - IntegerEntry
          - StringEntry
          Adding/modifying of the entry. The type of structure must match the type of entry to be added/changed.
          - If there is no entry in the account data storage with the key specified in the structure, the entry will be added.
          - If the entry is present in the account data storage, it will be modified
          DeleteEntry Entry deletion
          Issue Token issue
          Reissue Token reissue
          Burn Token burn
          SponsorFee Sponsorship setup
          ScriptTransfer Token transfer

          # Limitations

          • The maximum number of BinaryEntry, BooleanEntry, IntegerEntry, StringEntry, DeleteEntry that are executed by callable function is 100.
          • The maximum number of Issue, Reissue, Burn, SponsorFee, ScriptTransfer that are executed by callable function is 10.
          • The maximum number of the payments in favor of dApp which are attached to the invoke script transaction is 2.

          # Example

          The example listed below is a wallet application which allows to send WAVES to certain address and withdraw them (withdrawing others' WAVES is prevented). There are two callable functions in the example:

          • deposit — provides desposit of the tokens.
          • withdraw — provides withdraw of the tokens.
          {-# STDLIB_VERSION 4 #-}
          {-# CONTENT_TYPE DAPP #-}
          {-# SCRIPT_TYPE ACCOUNT #-}
          
          @Callable(i)
          func deposit() = {
            let pmt =
              if i.payments.size() == 1 then
                i.payments[0]
              else throw("Attached payment is required")
            if (isDefined(pmt.assetId))
              then throw("works with waves only")
              else {
               let currentKey = toBase58String(i.caller.bytes)
               let currentAmount = match getInteger(this, currentKey) {
                 case a:Int => a
                 case _ => 0
               }
               let newAmount = currentAmount + pmt.amount;
               [IntegerEntry(currentKey, newAmount)]
             }
          }
          
          @Callable(i)
          func withdraw(amount: Int) = {
           let currentKey = toBase58String(i.caller.bytes)
           let currentAmount = match getInteger(this, currentKey) {
             case a:Int => a
             case _ => 0
           }
           let newAmount = currentAmount - amount
           if (amount < 0)
             then throw("Can't withdraw negative amount")
             else if (newAmount < 0)
               then throw("Not enough balance")
               else [
                 IntegerEntry(currentKey, newAmount),
                 ScriptTransfer(i.caller, amount, unit)
                ]
          }
          
          @Verifier(tx)
          func verify() = false
          

          # Version 3

          # Arguments

          Callable function can have arguments of the following types:

          • Boolean,
          • ByteVector,
          • Int,
          • String,
          • Union with elements whose types are listed above.

          # Invocation result

          Callable function invocation result in Standard library version 3 is one of the following structures:

          • WriteSet — contains a list of actions for account data storage entries.

            Example:

            WriteSet([
                  DataEntry("key", true),
                  DataEntry("another_key", base58'someBase58VaLue'),
                  DataEntry("yet_another_key", 42),
                  DataEntry("one_more_key", "value")
               ])
            
          • TransferSet — contains a list of transfers.

            Example:

            TransferSet([ScriptTransfer(Address(base58'3Ms8fSfAxBLDjKvNVgACRzQoBLCtCWxtawu'), 100, base58'someAssetid')])
            
          • ScriptResult — contains WriteSet and TransferSet structures.

            Example:

            ScriptResult(
                 WriteSet([
                   DataEntry("key", true),
                   DataEntry("other_key", base58'someBase58VaLue'),
                   DataEntry("yet_another_key", 42), DataEntry("one_more_key", "value")
                 ]),
                 TransferSet([ScriptTransfer(Address(base58'3Ms8fSfAxBLDjKvNVgACRzQoBLCtCWxtawu'), 100, base58'someAssetid')])
               )
            

          # Script actions

          Script actions executed by the callable function are set by Ride structures.

          Ride structure that sets action Description
          DataEntry - If in the account data storage there is no entry with the key similar to the DataEntry key, then the entry will be added.
          - If in the account data storage there is an entry with the key similar to the DataEntry key, then the entry will be modified
          ScriptTransfer Token transfer

          # Limitations

          • Amount of dApp account data storage entries which can be added/modified within the single invoke script transaction - up to 100.
          • Amount of token transfers which can be performed by the dApp within single invoke script transaction — up to 10.
          • Amount of the payments in favor of dApp which are attached to the invoke script transaction — 1.

          # Example

          The example listed below is a wallet application which allows to send WAVES to certain address and withdraw them (withdrawing others' WAVES is prevented). There are two callable functions in the example:

          • deposit — provides desposit of the tokens.
          • withdraw — provides withdraw of the tokens.
          {-# STDLIB_VERSION 3 #-}
          {-# CONTENT_TYPE DAPP #-}
          {-# SCRIPT_TYPE ACCOUNT #-}
          @Callable(i)
          func deposit() = {
           let pmt = extract(i.payment)
           if (isDefined(pmt.assetId))
              then throw("works with waves only")
              else {
               let currentKey = toBase58String(i.caller.bytes)
               let currentAmount = match getInteger(this, currentKey) {
                 case a:Int => a
                 case _ => 0
               }
               let newAmount = currentAmount + pmt.amount
               WriteSet([DataEntry(currentKey, newAmount)])
             }
           }
          @Callable(i)
          func withdraw(amount: Int) = {
           let currentKey = toBase58String(i.caller.bytes)
           let currentAmount = match getInteger(this, currentKey) {
             case a:Int => a
             case _ => 0
           }
           let newAmount = currentAmount - amount
           if (amount < 0)
             then throw("Can't withdraw negative amount")
             else if (newAmount < 0)
               then throw("Not enough balance")
               else ScriptResult(
                 WriteSet([DataEntry(currentKey, newAmount)]),
                 TransferSet([ScriptTransfer(i.caller, amount, unit)])
                )
           }
          @Verifier(tx)
          func verify() = false
          

          # Threshold for Saving Failed Transactions

          After activation of feature # 15 “Ride V4, VRF, Protobuf, Failed transactions” the invoke script transaction is saved on the blockchain and a fee is charged for it even if the dApp script or the asset script failed, provided that the sender's signature or account script verification passed.

          However if the callable function failed with an error or throwing an exception before the complexity of performed computations exceeded the threshold for saving failed transactions, the transaction is rejected and the fee is not charged.

          This rule doesn't depend on the Standard library version used. Keep it in mind when developing a dApp script. For more information, see the Transaction Validation article.

          Annotations
          Verifier Function
          Annotations
          Verifier Function