Build on Flow | Learn FCL - 2. Pass Arguments to Scripts

Overview

After working through code in this post you should know how to:

pass simple arguments - Int, String, etc.
pass complex arguments - Arrays and Dictionaries
pass complex structures - Arrays of Dictionaries, etc.

💡 Learn better with video? Lucky for you there is a video you can follow along w/ this guide. Narrated by one and only Flow Developer Advocate Kimcodeashian!

Kimazing Content

Previously on "Learn FCL"

In previous post we've learned how to send basic Cadence script to execution. In this one I will show you how to pass different type of arguments.

For this and all the following examples we will use Codesandbox to simplify the process 🙂

Step 1 - Installation

Add "@onflow/fcl": "1.0.0" as your dependency

Step 2 - Setup

Just like the last time we will import necessary methods and setup FCL:

import { query, config } from "@onflow/fcl";

const api = "https://rest-testnet.onflow.org";
config().put("accessNode.api", api);

Step 3 - Pass Integers

passIntegers will pass two integer arguments to a simple Cadence script, which shall return us their sum.

const passIntegers = async () => {
  // Here we will store the code we want to execute.
  // We can inline it into the object we pass to "query" method,
  // but it feels cleaner this way
  const cadence = `
    pub fun main(a: Int, b: Int): Int{
      return a + b
    }
  `;

  // Even though both of the arguments are numbers, we need to pass them as strings representation
  const a = (5).toString();
  const b = (12).toString();
  const args = (arg, t) => [arg(a, t.Int), arg(b, t.Int)];

  // "query" will pass Cadence code and arguments to access node for execution and return us a result:
  // read more about "query" method on Flow Docs Site:
  // https://docs.onflow.org/fcl/reference/api/#query
  const result = await query({ cadence, args });
  console.log({ result }); //
};

Step 4 - Pass Multiple Different Types

passMultipleDifferentTypes will pass a String, Bool, UFix64 and an Address arguments.

const passMultipleDifferentTypes = async () => {
  const cadence = `
    pub fun main(a: String, b: Bool, c: UFix64, d: Address): Address{
      return d
    }
  `;

  const a = "Hello";
  const b = true;
  // All  numeric values should be passed as strings, remember? :)
  const c = "42.0";
  // Address should be passed as string value as well
  const d = "0x01";

  // Types should always mirror argument types defined in script
  const args = (arg, t) => [arg(a, t.String), arg(b, t.Bool), arg(c, t.UFix64), arg(d, t.Address)];

  const result = await query({ cadence, args });
  console.log({ result }); //
};

Step 5 - Pass an Array

passArray method will pass an array of Strings and return one of them back.

const passArray = async () => {
  const cadence = `
    pub fun main(a: [String]): String{
      return a[1]
    }
  `;

  const a = ["Hello", "Cadence"];
  // Type of the argument is composed of t.Array and t.String
  const args = (arg, t) => [arg(a, t.Array(t.String))];

  const result = await query({ cadence, args });
  console.log({ result }); //
};

Step 6 - Pass a Dictionary

passDictionary method will pass a Dictionary as argument and then return value of one of the fields. Keys of said Dictionary will be of type String and values of type Int.

const passDictionary = async () => {
  // In this example we will pass to Cadence Dictionary as argument
  // keys will be of type "String" and values of type "Int"
  const cadence = `
    pub fun main(a: {String: Int}): Int?{
      return a["amount"]
    }
  `;

  // Dictionaries should be represented as array of key/value pairs of respective types
  // Note that we shall pass numeric value as string here
  const a = [{ key: "amount", value: "42" }];
  // Dictionary type is composed out of t.Dictionary, t.String and t.Int for our case
  const args = (arg, t) => [
    arg(a, t.Dictionary({ key: t.String, value: t.Int }))
  ];

  const result = await query({ cadence, args });
  console.log({ result }); //
};

Step 7 - Pass Complex Argument

passComplex will showcase how to pass an array of Dictionaries as argument. Conceptually it’s a mix of array and dictionary types.

const passComplex = async () => {
  // In this example we will pass an Array of Dictionaries as argument
  // Keys will be of type "String" and values of type "Int"
  const cadence = `
    pub fun main(a: [{String: Int}]): Int?{
      return a[0]["amount"]
    }
  `;

  // Array of Dictionaries should be represented as array of arrays of key/value pairs of respective types
  // Note that we shall pass numeric value as string here
  const a = [[{ key: "amount", value: "1337" }]];
  // Dictionary type is composed out of t.Dictionary, t.String and t.Int for our case
  const args = (arg, t) => [
    arg(a, t.Array(t.Dictionary({ key: t.String, value: t.Int })))
  ];

  const result = await query({ cadence, args });
  console.log({ result });
};

Finally

Let's add an IIFE at the end of the file and populate it with methods we have just defined:

(async () => {
  console.clear();
  await passIntegers();
  await passMultipleDifferentTypes();
  await passArray();
  await passDictionary();
  await passComplex();
})();

When the dust settles you should see the following in the console log:

{result: "17"}
{result: "0x0000000000000001"}
{result: "Cadence"}
{result: "42"}
{result: "1337"}

Practice passing different types of arguments, as it should be a common task for you in the future.

Full code could be found on Codesandbox here:
https://codesandbox.io/s/dev-to-fcl-script-arguments-knpuel

Until next time! 👋

Resources

Other resources you might find useful:

Flow Docs Site - https://docs.onflow.org/ - More detailed information about Flow blockchain and how to interact with it
Flow Portal - https://flow.com/ - your entry point to Flow
FCL JS - https://github.com/onflow/fcl-js - Source code and ability to contribute to the FCL JS library
Cadence - https://docs.onflow.org/cadence/ - Introduction to Cadence
Codesandbox - https://codesandbox.io - An amazing in-browser IDE enabling quick prototyping

Blog