DEV Community: Flow Blockchain

Build on Flow: JS Testing - 4. Storage Inspection

Max Daunarovich — Fri, 26 May 2023 06:21:53 +0000

Intro

In the previous episode of our epic journey, we've discovered how we can interact with Flow Emulator by sending transactions and executing scripts. Today we will continue exploring available functions that help us build quick and easy to read tests for our Cadence contracts.

Reading simple values from contracts and accounts is a pretty easy task, even if you write all the Cadence code manually. But ensuring that account has proper paths setup or specific item in its collection could be tedious.

The Framework provides several methods to inspect account storage fast and painlessly.

Let's start by creating another test suit:

npx @onflow/flow-js-testing make storage-inspection

Inspect Available Paths

To gather all available paths on accounts we will call getPaths function, which will return an object containing three Sets:

publicPaths
privatePaths
storagePaths

You can inspect them as you would do with any other Set.

Let's confirm that Alice has all the necessary bits to operate FLOW token (all new accounts do, but this will simplify the process).

test("get paths", async () => {
  const Alice = await getAccountAddress("Alice");
  const { publicPaths, privatePaths, storagePaths } = await getPaths(Alice);

  // Newly created account shall have 2 public and 1 storage slot occupied for FLOW Vault
  expect(publicPaths.size).toBe(2);
  expect(publicPaths.has("flowTokenBalance")).toBe(true);
  expect(publicPaths.has("flowTokenReceiver")).toBe(true);

  // Newly created account doesn't have any private paths
  expect(privatePaths.size).toBe(0);

  // And it should have single storage path for FLOW token vault
  expect(storagePaths.size).toBe(1);
  expect(storagePaths.has("flowTokenVault")).toBe(true);
});

Get Type Restrictions on Path

A common case is to ensure that account has specific capability in its account and ensure specific type restrictions on it to confirm that transactions would work correctly. We can get an extended version of paths with extra information about them via getPathsWithType:

test("read path types", async () => {
  const { publicPaths } = await getPathsWithType("Alice");
  const refTokenBalance = publicPaths.flowTokenBalance;

  expect(refTokenBalance).not.toBe(undefined);
  expect(refTokenBalance.restrictionsList.has("A.ee82856bf20e2aa6.FungibleToken.Balance")).toBe(
    true
  );
  expect(refTokenBalance.restrictionsList.size).toBe(1);
  expect(refTokenBalance.haveRestrictions("FungibleToken.Balance")).toBe(true);
});

You can comment out those expect statements and use console.log(refTokenBalance) to see all available options you can use to assert it's correctness.

Read Storage Values

Now let's store a value in Alice's storage and try to read it via getStorageValue. We need to pass account name (i.e. "Alice") or address we resolved with getAccountAddress and storage path

test("read storage", async () => {
  const Alice = await getAccountAddress("Alice");
  await shallPass(
    sendTransaction({
      code: `
          transaction{
            prepare(signer: AuthAccount){
              signer.save(42, to: /storage/answer)
            }
          }
        `,
      signers: [Alice],
    })
  );

  const { storagePaths } = await getPaths(Alice);
  const answer = await getStorageValue(Alice, "answer");
  expect(answer).toBe("42");
  expect(storagePaths.has("answer")).toBe(true);

  // We can also try to read non-existing value, which shall be resolved to null
  // Notice that we pass string here ;)
  const empty = await getStorageValue("Alice", "empty");
  expect(empty).toBe(null);
});

Storage Stats

Another useful method you can emply during account inspection is getStorageStats - you might need one if you think users might hold huge collections and check how much of the storage it will occupy:

test("Read storage stats", async () => {
  const { capacity, used } = await getStorageStats("Alice");

  expect(capacity).toBe(100000);
  expect(used > 0).toBe(true);
});

Jest Helpers

Last, but not the least, there are a couple Jest helpers to simplify the inspection process and shorten your tests.

`shallHavePath(account, pathName)`

This function will allow to quickly confirm that path exists on account. Note, that second argument contains a full path, including domain

test("get paths", async () => {
  const Alice = await getAccountAddress("Alice");

  await shallHavePath(Alice, "/public/flowTokenBalance");
  await shallHavePath(Alice, "/public/flowTokenReceiver");
});

`shallHaveStorageValue(account, {props})`

Using this function, we can quickly check storage value—both complex and simple ones. Let's start with simple:

test("read storage", async () => {
  const Alice = await getAccountAddress("Alice");
  await shallPass(
    sendTransaction({
      code: `
          transaction{
            prepare(signer: AuthAccount){
              signer.save(42, to: /storage/answer)
            }
          }
        `,
      signers: [Alice],
    })
  );

  // This time we only need to path path in storage domain
  await shallHaveStorageValue(Alice, {
    pathName: "answer",
    expect: "42",
  });
});

Or if we know that value in storage is complex - let's say some NFT or Vault, then we can provide a key to how we can access it and check our expectations:

test("compare complex storage value", async () => {
  const Alice = await getAccountAddress("Alice");

  // We will read "balance" field of the value stored in "/storage/flowTokenVault" slot
  await shallHaveStorageValue(Alice, {
    pathName: "flowTokenVault",
    key: "balance",
    expect: "0.00100000",
  });
});

This is it for today! 😎
Let us know if you think we've missed some valuable examples 😉

Good luck and have fun! 👋

Build on Flow: JS Testing - 3. Execute Scripts and Send Transactions

Max Daunarovich — Fri, 26 May 2023 06:21:32 +0000

Intro

Now deploying contracts is all fun and games, but it becomes boring pretty fast, unless you can interact with them :)

There are two ways how you can interact with contracts and accounts on Flow - you can read data (via scripts) and you can write data (via transactions).

The biggest difference is — you can't mutate the state of the chain when executing scripts. Even if you called the contract's method, which implementation modifies the state, it won't be preserved when a script returns.

Let's start with non-intrusive interactions - scripts.

Prerequisites

Let's assume we are using the same setup from our last part, and we already have our cadence folder. Later we will plant some scripts into scripts folder.

Create a new test suit file

npx @onflow/flow-js-testing make interaction

Calculator

Since Cadence is able to do basic math operations, let's try to sum two numbers. Import executeScript and add new test inside describe block:

test("calculator", async () => {
  const [result] = await executeScript({
    code: `
        pub fun main(a: Int, b: Int): Int{
          return a + b
        }
      `,
    args: ["10", "32"],
  });
  expect(result).toBe("42");
});

Notice that we are passing numbers as strings here and the final result returned from the script will also be a string. You can add necessary conversions at your leisure, but this is how network and libraries process numbers on Flow

executeScript will return you a tuple (an array with 2 values) [result, error], which you can
use in your assertions.

Account Management

The Framework provides you a clean and easy way to operate accounts - getAccountAddress function.
This function will return an address, which you can pass into any kind of interaction and framework will do the rest for you. For example, you can use it as a transaction signer or one of the
arguments in a function:

const Alice = await getAccountAddress("Alice");

What is cool about this method is that this specific account is available anywhere inside your tests. So you can create a helper function, get Alice's account address one more time, and it will
be resolved to exactly the same value! ✨

Read Balance

Calculator is fun and games, but let's do something more practical. For example, we can read the FLOW balance of any account. It is pretty easy if you know you way around Cadence:

test("read balance", async () => {
  const Alice = await getAccountAddress("Alice");
  const [balance] = await executeScript({
    code: `
        pub fun main(address: Address): UFix64 {
          let account = getAccount(address)
          return account.balance
        }
      `,
    args: [Alice],
  });

  expect(balance).toBe("0.00100000");
});

All newly created accounts start with 0.001 amount of Flow, so we can assert this value and use it as baseline for future computations

Contract Access

How about reading something from imported contract? Easy enough! Let's redeploy our Message contract and try to read message field from it:

test("read message", async () => {
  const message = "noice";
  await shallResolve(deployContractByName({ name: "Message", args: [message] }));
  const [contractValue] = await executeScript({
    code: `
      import Message from 0x1

      pub fun main():String{
        return Message.message
      }
    `,
  });

  expect(contractValue).toBe(message);
});

We can import contracts from any address - framework will resolve them and assign proper ones, before sending the script to the emulator.

Short Notation

Let's shorten that script notation, by moving Cadence code into read-message.cdc file and place it into scripts folder. executeScript have a shorthand notion, where the first argument is a name of the file containing the script.

test("read message - short", async () => {
  const message = "noice";
  await shallResolve(deployContractByName({ name: "Message", args: [message] }));
  const [contractValue] = await executeScript("read-message");

  expect(contractValue).toBe(message);
});

Arguments can be passed as second argument. Let's add read-balance.cdc file with code from above and rewrite our balance reading script:

test("balance - short", async () => {
  const Alice = await getAccountAddress("Alice");
  const [balance] = await executeScript("read-balance", [Alice]);

  expect(balance).toBe("0.00100000");
});

Noice!

Cadence Ninja Mutants 🐢

Let's bring some mutations to the mix! We will make two accounts, mint some tokens for one of them and transfer them to another account. This should be fun!

In order to mint FLOW, we will utilize mintFlow function, which expects the address and amount as arguments. Import mintFlow and sendTransaction at the top of the file

test("FLOW transfer", async () => {
  const Alice = await getAccountAddress("Alice");
  const Bob = await getAccountAddress("Bob");

  await mintFlow(Alice, "42");

  const [aliceBalance] = await executeScript("read-balance", [Alice]);
  expect(aliceBalance).toBe("42.00100000");
});

Similar to how we've used shallPass to deploy contract, we can utilize it, when sending transactions.

test("FLOW transfer", async () => {
  const Alice = await getAccountAddress("Alice");
  const Bob = await getAccountAddress("Bob");

  await mintFlow(Alice, "42");

  const [aliceBalance] = await executeScript("read-balance", [Alice]);
  expect(aliceBalance).toBe("42.00100000");

  await shallPass(
    sendTransaction({
      code: `
        import FungibleToken from 0x1

        transaction(receiverAddress: Address, amount: UFix64){
          prepare(sender: AuthAccount){
            let receiver = getAccount(receiverAddress)

            // Withdraw necessary amount into separate vault
            let senderVault <- sender
                .borrow<&{FungibleToken.Provider}>(from: /storage/flowTokenVault)!
                .withdraw(amount: amount)

            // Send to receiver
            getAccount(receiverAddress)
                .getCapability(/public/flowTokenReceiver)!
                .borrow<&{FungibleToken.Receiver}>()!
                .deposit(from: <- senderVault)
          }
        }
      `,
      args: [Bob, "1"],
      signers: [Alice],
    })
  );

  // Let's read updated balances and compare to expected values
  const [newAliceBalance] = await executeScript("read-balance", [Alice]);
  const [bobBalance] = await executeScript("read-balance", [Bob]);

  expect(newAliceBalance).toBe("41.00100000");
  expect(bobBalance).toBe("1.00100000");
});

Send via Short Notation

Similar to how we've done it with scripts, sendTransaction function also supports short notation:

sendTransaction(
  fileName, // file name in "transactions folder"
  [signers], // {optional) list of signers, even if that's single one
  [arguments] // (optional) list of arguments
);

Let's move all the Cadence code from example above into send-flow.cdc file under cadence/transactions folder and rewrite our test:

test("FLOW transfer - short", async () => {
  const Alice = await getAccountAddress("Alice");
  const Bob = await getAccountAddress("Bob");

  await mintFlow(Alice, "42");

  const [aliceBalance] = await executeScript("read-balance", [Alice]);
  expect(aliceBalance).toBe("42.00100000");

  const signers = [Alice];

  const recipient = Bob;
  const amount = "1";
  const args = [recipient, amount];

  await shallPass(sendTransaction("send-flow", signers, args));

  // Let's read updated balances and compare to expected values
  const [newAliceBalance] = await executeScript("read-balance", [Alice]);
  const [bobBalance] = await executeScript("read-balance", [Bob]);

  expect(newAliceBalance).toBe("41.00100000");
  expect(bobBalance).toBe("1.00100000");
});

"Multisig" is supported out of the box, simply specify the expected number of signers in your transaction code and pass the corresponding number of addresses via signers parameter 😉

That's all, folks! Next time, we will take a look at how we can inspect account storage and ensure resources were correctly minted or transferred. Until next time! 👋

Build on Flow: JS Testing - 2. Setup Emulator and Deploy Contracts

Max Daunarovich — Fri, 26 May 2023 06:21:08 +0000

Intro

Last Time we've covered how you can get started with testing in your project. That article covers use of init and make commands in JS Testing Framework and how to use them to scaffold your testing enviroment.

We will assume you've gone through that process and have ready setup.

This time we will cover how you can deploy your newly developed contract to emulator to be able to run scripts and transactions against it.

Prerequisites

You will need to install Flow CLI in order to be able to spin up Flow Emulator. Follow instructions for your OS on Developer Portal.

If you haven't prepared your environment - follow instructions from previous article.

Setup Cadence Folder

Most of the methods will allow you to use Cadence code straight from the .cdc files. The only requirement is to use specific folder structure in designated folder.

Let's create cadence folder in the root of your project. Then create 3 new folders inside of it:

contracts - will hold all the contracts you would want to deploy
transactions - for any transactions code
scripts - same for scripts

Please note that folders should be called exactly in the same manner or they won't work. We have planned the task, which would allow you to use custom names, but it's not implemented yet

In order for framework to know what location you want to use you will need to call init method:

import path from "path";
import { emulator, init } from "@onflow/flow-js-testing";

describe("interactions - sendTransaction", () => {
  // Instantiate emulator and path to Cadence files
  beforeEach(async () => {
    const basePath = path.resolve(__dirname, "../cadence");
    await init(basePath);
    return emulator.start();
  });

  // Stop emulator, so it could be restarted
  afterEach(async () => {
    return emulator.stop();
  });
});

Setup Emulator

In order to test any network interactions, we need instance of emulator running. Frameworks handle the process with emulator instance, which exposes two methods - start and stop. Those will handle running flow emulator process with necessary flags and extra steps after emulator will be stopped.

You can reference code above to see how we use it in beforeEach/afterEach blocks.

How to Deploy a contract?

Framework have two handy functions, which will help you deploy contracts:

deployContract - allows you to pass contract code as a string (handy, when you are just playing around)
deployContractByName- will allow you to deploy contract defined via file in your cadence folder (which you pass, when calling

They are quite similar in function, but deployContractByName provides you an easy way of deploying contracts located in your cadence/contracts folder. Let's create a file HelloWorld.cdc inside ouf our contracts folder and paste the following in:

pub contract HelloWorld{
    pub let greetings: String

    init(){
        self.greetings = "Hello, from Cadence"
    }
}

Our little contract only have single field, which we can read in the future. Let me show you how we can test it.

Create new test suit with make command:

npx @onflow/flow-js-testing make first

This command will run make tool provided by testing framework and create a first.js file, which will have a basic setup for you. Since deploying contract on Flow is just sending specifically designed transaction, we will use shallPass method to ensure everything works:

import path from "path";
import { init, emulator, shallPass, deployContractByName } from "@onflow/flow-js-testing";

// Increase timeout if your tests failing due to timeout
jest.setTimeout(10000);

describe("deploy", () => {
  beforeEach(async () => {
    const basePath = path.resolve(__dirname, "../cadence");
    const logging = false;

    await init(basePath);
    return emulator.start({ logging });
  });

  // Stop emulator, so it could be restarted
  afterEach(async () => {
    return emulator.stop();
  });

  // We will put next block here
  // ========>
});

Our first test will be super simple. We will wrap deployContractByName with shallPass and await the result of that computation:

test("deploy Hello", async () => {
  await shallPass(deployContractByName({ name: "Hello" }));
});

Well done! 👍 But scenarios like that is never the case. Contracts are usually much more complicated and accept multiple arguments to init it's field. Let's create another contract Message.cdc in our contracts folder and populate it with following Cadence code:

pub contract Message{
    pub let message: String

    init(message: String){
        self.message = message
    }
}

Now we need to pass arguments, when we deploy contract. We can do this by specifying args field on the object we pass into deployContractByName. It should be an array of values in the same order we defined them on init method of our contract.

test("deploy Message", async () => {
  const message = "Cadence is great!";

  await shallPass(
    deployContractByName({
      name: "Message",
      args: [message],
    })
  );
});

Note that framework will handle all the type conversions for you! 😎

You can try to add another argument to ensure that test will fail, ensuring you are doing
everything correctly.

Another function we have at our disposal is deployContract. It has pretty much the same API, except it expects code value for your Cadence instead of a file name. Let's make a simple test to
illustrate how you can use it.

test("deploy Custom", async () => {
  await shallPass(
    deployContract({
      code: `
          pub contract Custom{
            pub let message: String

            init(){
              self.message = "This is custom contract! Neat, ha? :)"
            }
          }
        `,
    })
  );
});

You can pass arguments in the same fashion we did above for deployContractByName by specifying args field.

Originally the purpose of this function was to process and consume arguments from
deployContractByName and wasn't exported. After some consideration we've exported it to enable
people who just learning Cadence to experiment quikly

You can find detailed explanation of both functions on [Flow Developer Portal - Contract Management (https://developers.flow.com/tooling/flow-js-testing/contracts)

Too slow!

Sometimes scenario that you are trying to test takes more time than default Jest timeout - 5 seconds. You can control this by increasing the timeout to next reasonable value:

// Place this after import lines
import path from "path";
import { deployContractByName, emulator, executeScript, init } from "@onflow/flow-js-testing";

jest.setTimeout(20000);

// the rest of the test setup below 👇

Some CI environments might be slower than you local machine, so if you see randomly failing tests - try to increase this value.

That's all, folks! Next time we will take a look how we can execute scripts, sign and send
transactions.

Build on Flow: JS Testing - 1. Introduction

Max Daunarovich — Wed, 08 Mar 2023 19:12:16 +0000

Intro

One of the most important parts of software development is Testing. It helps ensure that the product meets the requirements and is fit for the purpose. Testing allows to detect bugs and errors in the software, which in turn makes it more reliable and efficient.

It's especially important for any blockchain project, considering the immutable nature of blockchains. Errors that could easily be fixed in Web2 application usually are irreversable, when changes are introducted to the ledger.

Flow Network is using Cadence - a new Domain Specific Language designed to make writing smart contracts easier and more accessible. Cadence is a statically typed, high-level smart contract language that simplifies development by allowing developers to write complex logic that can be deployed and executed on the the Flow Network.

Testing Options

There are several paths you can go to test your Cadence code:

Create testbed based on Flow Go SDK and inspired by TopShot
Use amazing Overflow by one of the most prolific community members Bjarte S. Karlsen
Use Cadence Testing Framework
Use Flow JS Testing Framework

In this series we will explore the last option.

What is Flow JS Testing?

Flow JS Testing is a library of utility methods, which in conjuction with Flow CLI provides developers the ability to write tests for Cadence using Javascript and testing solutions like Jest

It have all the necessary capabilities to get blockchain interaction out of the way and allow you to focus on writing "human-readable" tests. Here are some of them:

start/stop Flow Blockchain emulator
create and manage accounts
deploy contracts
execute scripts and send transactions signed by one or multiple parties
helpful Jest assertions for passing/failing interactions

🖐 Please note, framework is not restricting you to only use Jest, even though all examples and tutorials utilizing it.

Let's give it a try and create a simple test, which will execute the script on Emulator and return a value, which we can then compare to expected result.

Prerequisites

You will need to install Flow CLI in order to be able to spin up Flow Emulator. Follow instructions for your OS on Developer Portal.

Installation

Setting up all the necessary configs and environment is quite taxating 😩. That is exactly the reason, why we made handy init function for you! Open the terminal in the root of your project, copy/paste following block and press Enter:

mkdir test &&
cd test &&
npx @onflow/flow-js-testing init

This will run all the necessary steps, create babel and jest configration as well as install dependecies neededd to run the tests.

Now let's create our first test file! You can copy/paste on of the examples from links we've provided below or simply run:

npx @onflow/flow-js-testing make simple

Where simple is the name of the file and test suite - series of tests enclosed in describe block.

Open the file in your prefered editor.
Import executeScript from @onflow/flow-js-testing:

import { emulator, init } from "@onflow/flow-js-testing";
import { executeScript } from "@onflow/flow-js-testing"

Update the only test block defined there:

test("basic assertion", async () => {
  const [result] = await executeScript({
    code: `
      pub fun main():Int{
        return 42
      }
    `
  })
  expect(result).toBe("42")
})

executeScript method will return a tupple [result, error, logs]. This time we only care about result value so we can drop error and logs values - one of the following articles will cover those in details.

☝ Even though we are returning Int value it is still a string! You will need to handle conversions yourself. At least for now 😅

Now run your test with:

jest

Congratulations! You succesfully tested and confirmed your setup is working properly 🎉

Next time we will create basic smart-contract and interact with it. Stay tuned! 👋

Link and Sources

Flow Developer Portal - Detailed information about Flow blockchain, tutorials, tools and everything you need
Flow JS Testing - API Reference - JS Testing API Reference
Flow JS Testing - Examples - Multiple examples for common patterns and interactions
KittyItems Example - Real-life example of JS Testing Framework application for Cadence testing

Build on Flow | Learn FCL - 16. How to Send FLOW Tokens to Another Account

Max Daunarovich — Mon, 29 Aug 2022 09:20:00 +0000

Overview

Fungible tokens are often used as a means of payment - for products or services. In this article we will guide you how to:

get current balance of FLOW on a specific account
compose FLOW transfer transaction
sign and send it using Blocto or Lilico wallet

Theory

FLOW token is a contract, which implements Fungible Token Standard interface. If you take a look in the code, you will see that on the higher level totalSupply is defined on implementing contract, but it doesn’t know how much tokens holds each individual account. Each account that would want to own tokens would need to have an instance of the Vault resource stored in their account storage. The Vault resource has methods that the owner and other users can call. Those methods are limited byProvider, Receiver, and Balance resource interfaces. These interfaces declare pre-conditions and post-conditions that restrict the execution of the functions in the Vault.

They are separate because it gives the user the ability to share a reference to their Vault that only exposes the fields functions in one or more of the interfaces.

It also gives users the ability to make custom resources that implement these interfaces to do various things with the tokens. For example, a faucet can be implemented by conforming
to the Provider interface.

By using resources and interfaces, users of Fungible Token contracts can send and receive tokens peer-to-peer, without having to interact with a central ledger smart contract. To send tokens to another user, a user would simply withdraw the tokens from their Vault, then call the deposit function on another user's Vault to complete the transfer.

Step 1 - Installation

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

Step 2 - FCL Config

Let’s create testnet-config.js file, so we can reuse it in later projects. It will also make our index.js file cleaner and allow for an easy swap to mainnet version. The content of the file will be pretty much the same as we covered in previous article:

// Configure FCL
import { config } from "@onflow/fcl";

config({
  // Use Testnet Access Node
  "accessNode.api": "https://rest-testnet.onflow.org",
  // We will also specify the network as some of the FCL parts need it to properly do it's work
  "flow.network": "testnet",
  // This will be the title of our DApp
  "app.detail.title": "Meow DApp",
  // This is just a kitten photo, we will use for the icon
  "app.detail.icon": "https://placekitten.com/g/200/200",
  // Next two will define where Wallet Discovery is located
  "discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn",
  "discovery.authn.endpoint":
    "https://fcl-discovery.onflow.org/api/testnet/authn",

  // We will also set aliases for the contracts we will use in this example
  "0xFLOW": "0x7e60df042a9c0868",
  "0xFT": "0x9a0766d93b6608b7"
});

If you take a look at the end of the config you can see that we’ve defined two aliases for the contracts we will import in our Cadence code:

0xFLOW for FlowToken contract
0xFT for FungibleToken contract

Step 4 - Imports

Back to our index.js file, where we will add all the necessary imports:

import { query, mutate, tx, reauthenticate } from "@onflow/fcl";
import "./testnet-config";

Step 3 - Implement `getFlowBalance` function

Next, let’s create a function, which will check current balance of the account, defined by it’s address.

It will accept single argument address, which will be passed to Cadence script and return UFix64 value, represented as string.

💡If you just arrived here and don’t quite know what is happening - don’t be afraid! We’ve got you covered! You can check earlier articles in this series:

How to Execute Scripts

How to Send Transactions

const getFlowBalance = async (address) => {
  const cadence = `
    import FlowToken from 0xFLOW
    import FungibleToken from 0xFT

    pub fun main(address: Address): UFix64 {
      let account = getAccount(address)

      let vaultRef = account.getCapability(/public/flowTokenBalance)
        .borrow<&FlowToken.Vault{FungibleToken.Balance}>()
        ?? panic("Could not borrow Balance reference to the Vault")

      return vaultRef.balance
    }
  `;
  const args = (arg, t) => [arg(address, t.Address)];
  const balance = await query({ cadence, args });
  console.log({ balance });
};

🧑‍🏫 If you are wondering where we’ve got the code for this transaction - you can check Fungible Token Standart repository on Github:

Get Balance Cadence script

Transfer Tokens Cadence Transaction

The “problem” is - you won’t be able to find BalancePublicPath field set on FlowTokencontract deployed to 0x9a0766d93b6608b7. The contract was deployed before this useful partern of storing common path became widely used. That’s why we are hard-coding /public/flowTokenBalance value which we sourecd from init method of the contract. We will also use /public/flowTokenReceiver defined there to get capability of the Recepient’s Vault.

While Javacript code is self-explanatory, let’s cover whats is happening in Cadence script. It accepts single argument address of type Address and returns UFix64 value:

pub fun main(address: Address): UFix64 {

First we take account, we are trying to “investigate” by calling getAccount function, which will return us PublicAccount struct.

let account = getAccount(address)

This struct gives us the ability to call getCapability method to retrieve necessary capability to FLOW Vault. We know that capability should be exposes on /public/flowTokenBalance public path. And we also know that it’s a limited capability FungibleToken.Balance, which will only alow us to read the balance of the Vault.

We can check init method of FlowToken contract (line #187) to get the correct type we need to borrow:

<&FlowToken.Vault{FungibleToken.Balance}>

In order to operate said capability, we need to get a reference to it with .borrow method. We can set the type are are expecting to borrow using angular brackets - and paste the same type as it was defined in init method.

let vaultRef = account.getCapability(/public/flowTokenBalance)
        .borrow<&FlowToken.Vault{FungibleToken.Balance}>()
        ?? panic("Could not borrow Balance reference to the Vault")

If the reference can’t be created (for example stored Capability have different type or can’t be casted to this specific type) - transaction will stop the execution with panic message.

Step 4 - Implement `sendFlow` function

Next on the list is a function, which will accept Recepient’s address and amount of FLOW tokens we want to transfer.

const sendFlow = async (recepient, amount) => {
  const cadence = `
    import FungibleToken from 0xFT
    import FlowToken from 0xFLOW

    transaction(recepient: Address, amount: UFix64){
      prepare(signer: AuthAccount){
        let sender = signer.borrow<&FlowToken.Vault>(from: /storage/flowTokenVault)
          ?? panic("Could not borrow Provider reference to the Vault")

        let receiverAccount = getAccount(recepient)

        let receiver = receiverAccount.getCapability(/public/flowTokenReceiver)
          .borrow<&FlowToken.Vault{FungibleToken.Receiver}>()
          ?? panic("Could not borrow Receiver reference to the Vault")

                let tempVault <- sender.withdraw(amount: amount)
        receiver.deposit(from: <- tempVault)
      }
    }
  `;
  const args = (arg, t) => [arg(recepient, t.Address), arg(amount, t.UFix64)];
  const limit = 500;

  const txId = await mutate({ cadence, args, limit });

    console.log("Waiting for transaction to be sealed...");

    const txDetails = await tx(txId).onceSealed();
  console.log({ txDetails });
};

Cadence code is pretty similar to one we’ve used above to query FLOW balance.

we are getting full reference to a Sender’s Vault
we are geting limited Receiver reference to Recepient’s Vault
we are creating temporary Vault via withdraw method and passing amount as argument
we are depositing into Recepient’s Vault via deposit method and tempVault

Notice the syntax of full reference - we don’t specify limiting interface in curly braces and we also specify storage path /storage/flowTokenVault . Every account is initialized with FLOW Vault on that path, so it’s safe to assume it’s there for every signer:

let sender = signer.borrow<&FlowToken.Vault>(from: /storage/flowTokenVault)

Finally

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

(async () => {
  console.clear();
    // "reauthenticate" will ensure your session works properly
  // and present you a popup to sign in
  await reauthenticate();

  // This is an example account we've created to this exibition
  // You can replace it with one of your addresses
  const recepient = "0x3e68d80ca405bbac";

  // Check "initial" balance first
  await getFlowBalance(recepient);

  // Send some FLOW tokens to Recepient
  await sendFlow(recepient, "1.337");

  // Ensure that Recepient's balance has been changed
  await getFlowBalance(recepient);
})();

After a series of popups and confirmation your console should have the proof that balance of Recepient’s Vault have been changed:

{balance: "1002.67500000"}

Waiting for transaction to be sealed... 

txDetails: {
    blockId: "b555b7ca17fac5ad170e3bfc4a85afd3325eb5d4fb56e4be49550dce9413ffad"
    status: 4
    statusString: "SEALED"
    statusCode: 0
    errorMessage: ""
    events: Array(5)
}

{balance: "1004.01200000"}

You know what to do next 😉

Until next time! 👋

Resources

Full Source Code - https://codesandbox.io/s/dev-to-16-transfer-flow-tokens-pjq98u
Fungible Token Standard - https://github.com/onflow/flow-ft
FCL - mutate - https://docs.onflow.org/fcl/reference/api/#mutate
FCL - query - https://docs.onflow.org/fcl/reference/api/#query
Cadence - Capabilities - https://docs.onflow.org/cadence/language/capability-based-access-control
Cadence - References - https://docs.onflow.org/cadence/language/references

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

Build on Flow | Learn FCL - 15. How to Add and Revoke Public Keys

Max Daunarovich — Mon, 22 Aug 2022 18:40:00 +0000

Preface

One of the problems you might encounter, when you need to sign with a lot of transactions is inability to sign more than single transaction by account in single block. This happens because Proposer role is used to provide a nounce, which will be updated on account key only after transaction is sealed.

The solution - we need to add more keys 🔑✨!

Overview

After you go through the code in this article you will know:

how to discover public keys on account using Flow View Source
how to add new PublicKey with set weight

Wallet Limitations

While Blocto or Lilico will not allow you to use key with different index - other than 0 - in some cases it’s still valuable to add public key you can use programmatically to automate some tasks. The key with full weight will give you access to the account storage and ability to manipulate it.

Investigation

Before we continue, let’s check our current account on Flow View Source - 0x5593df7d286bcdb8

😅 Considering how many times Codesandbox has been run, you probably will see multiple keys here, when you read it.

You should see at least a single key with weight equal to 1000 (full weight).

Step 1 - Installation

💡You can go and fork your work from previous article as it will be mostly the same :)

Add "@onflow/fcl", elliptic and sha3 packages as your dependencies.

Step 2 - Create a signer

You can copy/paste the content of signer.js file from previous article or follow the instructions and make a new one.

Step 3 - Configure FCL

We are not gonna use wallets in this example - consider this as homework assignment 😉 - so our config only needs access node url:

config({ "accessNode.api": "https://rest-testnet.onflow.org" });

Step 4 - Implement `addPublicKey`

Let’s make a new function called addPublicKey, which will:

accept PublicKey as a string,
prepare transaction to pass public key and weight as arguments
sign and send aforementioned transaction to network

The process is similar to how we were cooking transactions in previous article:

const addPublicKey = async (publicKey) => {
  const cadence = `
  transaction(publicKey: String, weight: UFix64) {
    prepare(signer: AuthAccount) {
      let bytes = publicKey.decodeHex()

      let key = PublicKey(
        publicKey: bytes,
        signatureAlgorithm: SignatureAlgorithm.ECDSA_P256
      )

      var clampledWeight = weight
      // weight should be in range 0 to 1000
      if(clampledWeight > 1000.0){
        clampledWeight = 1000.0
      }

      signer.keys.add(
        publicKey: key,
        hashAlgorithm: HashAlgorithm.SHA3_256,
        weight: clampledWeight
      )
    }
  }
  `;

  // List of arguments
    const weight = (0).toFixed(1) // zero weight keys are perfectly fine for Proposer role
  const args = (arg, t) => [
    arg(publicKey, t.String),
    arg(weight, t.UFix64)
  ];

  // Roles
  const proposer = signer;
  const payer = signer;
  const authorizations = [signer];

    // Execution limit
    const limit = 1000

  // "mutate" method will return us transaction id
  const txId = await mutate({
    proposer, payer, authorizations,
    cadence, args, limit
  });

    // Then we subscribe to status updates and return, when it's sealed
  return tx(txId).onceSealed();
};

Step 5 - Implement `revokePublicKey`

Another function we would like to prepare is revokePublicKey. It will prepare and submit transaction, which will revoke the key on account:

const revokePublicKey = async (keyIndex) => {
  const cadence = `
    transaction(keyIndex: Int){
      prepare(signer: AuthAccount){
        signer.keys.revoke(keyIndex:keyIndex)
      }
    }
  `;
  const args = (arg, t) => [arg(keyIndex.toString(), t.Int)];

  const proposer = signer;
  const payer = signer;
  const authorizations = [signer];

    const limit = 1000;

  // "mutate" method will return us transaction id
  const txId = await mutate({
    cadence, args, limit,
    proposer, payer, authorizations
  });

    // Then we subscribe to status updates and return, when it's sealed
  return tx(txId).onceSealed();
};

Finally -

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

(async () => {
  console.clear();

  // PublicKey doesn't need to be unique, so we are gonna use exactly the same one
  // that already exist on account. This way we can control it with the same private key.
  const key =
    "790a6849decbc179e9904f7f601fbd629f1687f371484998ceb8c587303e05ae4f859c7aa91f8493642de1039039d2da9650b4b7d9d44d2486e7a2adabf602bc";

  // Uncomment this block to add public key
  /*
  const txDetails = await addPublicKey(key);
  console.log({ txDetails });
  */

  // Uncomment this block to revoke key
  /*
  const txDetails = await revokePublicKey(2);
  console.log({ txDetails });
  */
})();

When the dust settles, your console should have the output, showcasing that transaction succesfully updated your account:

txDetails: {
    blockId: "b9ddfac94c968864ca369ec890e8025c0144375f334bd0e2ddea1965b175fc82",
    status: 4,
    statusString: "SEALED",
    statusCode: 0,
    errorMessage: "",
    events: Array(4),
    0: Object {
        type: "flow.AccountKeyAdded"
        transactionId: "fa2640f428a3317b656196ef7f069a744b2455569e492f8112d37abca31e273d"
        transactionIndex: 0
        eventIndex: 0
        data: Object
    },
    1: Object,
    2: Object,
    3: Object,
}

Checking Flow View Source will show there are now multiple keys that can be used:

If you uncomment the revokePublicKey usage block and wait for execution, you will be able to see that key is marked as revoked.

💡 Please note, that keys are not removed, but revoked - you won’t be able to use this key index on this account anymore 🤷‍♂️

Hope you’ve found this article useful. And if you have gone through it with us - you’ve grown stronger! 💪

Until next time 👋

Resources

Full Source Code - https://codesandbox.io/s/dev-to-15-add-public-key-cvfho2
Cadence Docs - Add Key - https://docs.onflow.org/cadence/language/accounts/#add-account-keys
Cadence Docs - Revoke Key - https://docs.onflow.org/cadence/language/accounts/#revoke-account-keys

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

Build on Flow | Learn FCL - 14. How to Mutate Chain State by Signing Transactions with a Private Key

Max Daunarovich — Mon, 01 Aug 2022 13:21:35 +0000

Preface

Last time we covered how you can sign transactions with Lilico and Blocto wallets from the comfort of your browser. But it’s quite common that you might need to do the same task on a backend (i.e. server-side), where the browser is not available.

Fear not, my friend as this is exactly what we will teach you. After working through materials of this article you will know how to:

fill different roles for your transaction
get a basic understanding of the multisig process
sign a transaction with your private key

Step 1 - Installation

Add "@onflow/fcl", elliptic and sha3 packages as project dependencies.

Step 2 - Create a Signer

Let’s create a new file and call it signer.js. The file can have any name, we are just picking something with a semantic meaning here. Our signer will need to have 3 functions.

First one will be called hashMessageHex- it will be used to hash the transaction message using a SHA3 algorithm. The reason we are using SHA3 is because we’ve picked it as the Hash Algorithm during account creation on the Testnet Faucet outlined in one of the previous articles. The function itself is pretty straightforward. We will take the transaction message, specifically packed and represented as hex string and feed it into the update method exposed by SHA3 , then return the result from the digest method:

const hashMessageHex = (msgHex) => {
  const sha = new SHA3(256);
  sha.update(Buffer.from(msgHex, "hex"));
  return sha.digest();
};

The next function will call signWithKey - we will use it to sign our hashed transaction message with a private key. Now this IS a really complicated topic and let’s say you will cut a lot of corners if you simply copy-paste this one and do your crypto research later, mkey? 😅 tldr: we will use a Elliptic Curve Digital Signature Algorithm in order to produce our signature:

const signWithKey = (privateKey, msgHex) => {
  const key = curve.keyFromPrivate(Buffer.from(privateKey, "hex"));
  const sig = key.sign(hashMessageHex(msgHex));

  const n = 32;
  const r = sig.r.toArrayLike(Buffer, "be", n);
  const s = sig.s.toArrayLike(Buffer, "be", n);

return Buffer.concat([r, s]).toString("hex");
};

The last one will be a signer function, which will be used as Authorization Function - function which produce the information of the user that is going to sign and a signing function to use the information to produce a signature.

export const signer = async (account) => {
  // We are hard coding these values here, but you can pass those values from outside as well.
  // For example, you can create curried function: 
  // const signer = (keyId, accountAdddress, pkey) => (account) => {...}
  // and then create multiple signers for different key indices 

  const keyId = Number(0); // always ensure that your keyId is a number not a string
  const accountAddress = "0x5593df7d286bcdb8";
  const pkey =
    "248f1ea7b4a058c39dcc97d91e6a5d0aa7afbc931428561b6efbc7bd0f5e0875";

  // authorization function need to return an account
  return {
    ...account, // bunch of defaults in here, we want to overload some of them though
    tempId: `${accountAddress}-${keyId}`, // tempIds are more of an advanced topic, for 99% of the times where you know the address and keyId you will want it to be a unique string per that address and keyId
    addr: sansPrefix(accountAddress), // the address of the signatory, currently it needs to be without a prefix right now
    keyId // this is the keyId for the accounts registered key that will be used to sign, make extra sure this is a number and not a string

    // This is where magic happens! ✨
    signingFunction: async (signable) => {
      // Singing functions are passed a signable and need to return a composite signature
      // signable.message is a hex string of what needs to be signed.
      const signature = await signWithKey(pkey, signable.message);

      return {
        addr: withPrefix(accountAddress), // needs to be the same as the account.addr but this time with a prefix, eventually they will both be with a prefix
        keyId, // needs to be the same as account.keyId, once again make sure its a number and not a string
        signature // this needs to be a hex string of the signature, where signable.message is the hex value that needs to be signed
      };
    }
  };
};

✨Please, note, that signingFunction is asynchronous, meaning that it can use Promises inside of its body to get a signature out of extension or remote server. Which is super handy, when you want to handle gas fees for your users 😉

Step 3 - FCL Setup

import { config, query, mutate, tx } from "@onflow/fcl";
import { signer } from "./signer"

// Contrary to our wallet signing example, we don't need most of it in our config now
// so we'll get back to simple version
config({
  "accessNode.api": "https://rest-testnet.onflow.org",
  "0xBasic": "0xafabe20e55e9ceb6"
});

Step 4 - Implement `readCounter`

We will copy the same function from our previous article, because it will behave absolutely the same:

const readCounter = async () => {
  const cadence = `
    import Basic from 0xBasic

    pub fun main():UInt{
      return Basic.counter
    }
  `;
  const counter = await query({ cadence });
  console.log({ counter });
};

Step 5 - Implement `shiftCounter`

shiftCounter function will be almost identical as well. The only difference is that this time we will fill all the roles, using our signer function. On top of that we will log how much time it took to seal the transaction, using console.time and console.timeEnd methods:

const shiftCounter = async (value) => {
  console.log("%cSigning Transaction", `color: teal`);

  // Our Cadence code. Notice the use of alias here
  const cadence = `
    import Basic from 0xBasic

    transaction(shift: UInt8){
      prepare(signer: AuthAccount){
        Basic.incrementCounterBy(shift)
      }
    }
  `;

  // List of arguments
  const args = (arg, t) => [arg(value.toString(), t.UInt8)];
  const proposer = signer;
  const payer = signer;
  const authorizations = [signer];

  // "mutate" method will return us transaction id
  const txId = await mutate({
    cadence,
    args,
    proposer,
    payer,
    authorizations,
    limit: 999
  });

  console.log(`Submitted transaction ${txId} to the network`);
  console.log("%cWaiting for transaction to be sealed...", `color: teal`);

  const label = "Transaction Sealing Time";
  console.time(label);

    // We will use transaction id in order to "subscribe" to it's state change and get the details
  // of the transaction
  const txDetails = await tx(txId).onceSealed();

  console.timeEnd(label);
  return txDetails;
};

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 readCounter();

  const txDetails = await shiftCounter(12);
  console.log({ txDetails });

  // we will call "readCounter" function second time to ensure 
  // that value of counter has changed
  await readCounter();
})();

After the dust settles your console should have similar output:

{counter: "655"}
Signing Transaction
Submitted transaction d88e98687dd98f7597aca9afaf3daaba788f644f90003c9b144bfa13440fd9ab to the network 
Waiting for transaction to be sealed...
Transaction Sealing Time: 14749.60000000149ms 
{txDetails: Object}
{counter: "667"}

It wasn’t that hard in the end, right? 😉

Until next time! 👋

Resources

Full Source Code - https://codesandbox.io/s/dev-to-14-mutate-with-pkey-d0jsj0
Package - SHA3 - https://www.npmjs.com/package/sha3
Package - elliptic - https://www.npmjs.com/package/elliptic
FCL - Authorization Function - https://docs.onflow.org/fcl/reference/api/#authorization-function

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

Build on Flow | Learn FCL - 13. How to Modify the State of the Chain by Signing Transactions with Wallets

Max Daunarovich — Mon, 25 Jul 2022 16:49:00 +0000

Overview

In this post we will learn:

Signing roles - payer, proposer and authorizers
What is a signing function and how to create one
How to sign a transaction with one of your wallets
How to sign a transaction with your private key

Preface

Once we have our wallet or private keys, we can start signing transactions. Woohoo!

For better understanding of how this works, you will need some extra knowledge.

The signing process on Flow requires 3 different parties to sign the transaction:

Proposer - this is the account, which proposes to include changes done by transaction into the blockchain. Proposer role can be filled by any account on Flow blockchain.
Payer is the account, who will pay the gas fees for transaction execution. Similar to proposer , this can be any account, who have enough FLOW tokens to cover the fee and is eager to do it.
Authorizers - this is a list of accounts, who authorize any changes in their accounts, done by transaction they are signing. These should be accounts, that want to make said changes. If there is only a single account, it should still be a list of one.

💡All of those roles can be filled by the same account! You don’t need to have 3 “actors” to sign transaction 😅

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. This time, though, we will extend our configuration with some new values to enable Wallet Discovery.

FCL Wallet Discovery allows you to connect to all known and registered wallets at once! If you are coming from Ethereum, you can think about it as Flow variant of WalletConnect sans multichain support 😅

Note that we are using slightly different way to specify config by passing in object instead of calling multiple .put calls:

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

// Configure FCL
config({
    // Use Testnet Access Node
  "accessNode.api": "https://rest-testnet.onflow.org",
  // We will also specify the network as some of the FCL parts need it to properly do it's work
  "flow.network": "testnet",
    // This will be the title of our DApp
  "app.detail.title": "Meow DApp",
    // This is just a kitten photo, we will use for the icon
  "app.detail.icon": "https://placekitten.com/g/200/200",
    // Next two will define where Wallet Discovery is located
  "discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn",
  "discovery.authn.endpoint":
    "https://fcl-discovery.onflow.org/api/testnet/authn",

    // We will also set alias for the contract we will use in this example
    "0xBasic": "0xafabe20e55e9ceb6"
});

You can read more information about those and other configuration keys on FCL documentation page

Step 3 - Get Current Chain State

We’ve deployed a Basic contract at 0xafabe20e55e9ceb6. If you click on that link it will lead you to Flow View Source. You can see there is a single public variable counter, that we can read and a couple of methods to modify it. Let’s use the knowledge from previous articles and read it.

const readCounter = async () => {
  const cadence = `
    import Basic from 0xBasic

    pub fun main():UInt{
      return Basic.counter
    }
  `;
  const counter = await query({ cadence });
  console.log({ counter });
};

This simple query looks exactly like what we’ve built before, except this time we are using 0xBasic alias for the address. FCL will use the value we set in the config - 0xafabe20e55e9ceb6 - and replace it. We are doing it this way, cause we will make calls to the contract from our transaction as well. So we have this value nice and handy in one place and we don’t need to constantly reference it or memorize it 😉

You should see some output in your console, similar to this (number can be different, as there are multiple users, who would want to alter it):

{counter: "19"}

Step 4 - Modify Counter

We will use method mutate provided by FCL package to modify the state of the chain. In its most basic form mutate is very similar to query, but it’s using some hidden mechanisms in order to sign the transaction (we will demystify them in later article).

Let’s define another method shiftCounter, which we will be using to modify the value of the counter. If you go back to the Basic contract you will see that it defines two methods. We will use incrementCounterBy(_ step: UInt8)

We will need to pass UInt8 value as an argument to the transaction - we do it the same way we’ve done previously using the query method.

const shiftCounter = async (value) => {
    // Our Cadence code. Notice we are using alias here as well
  const cadence = `
    import Basic from 0xBasic

    transaction(shift: UInt8){
      prepare(signer: AuthAccount){
        Basic.incrementCounterBy(shift)
      }
    }
  `;

    // List of arguments
  const args = (arg, t) => [
        // We need to pass UInt8 value, but it should be a string, remember? :)
        arg(value.toString(), t.UInt8)
    ];

    // "mutate" method will return us transaction id
    const txId = await mutate({
    cadence,
    args,
    limit: 999
  });

  // We will use transaction id in order to "subscribe" to it's state change and get the details
  // of the transaction
  const txDetails = await tx(txId).onceSealed();
    return txDetails
};

Wait, but what about those roles we’ve mentioned above. You see, mutate will populate all of them with the current authenticated user…

That’s part of the FCL and Wallet Discovery magic 🎇. If you don’t specify any role in that mutate method it will ask you to connect to the wallet and then use selected account as current user. Then it will use all the necessary params to fill in the roles in that interaction. Pretty cool, ha? 😎

Finally

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

(async () => {
  console.clear();
  // You can [un]comment this line to toggle Wallet Discovery
  unauthenticate();

    // Let's read value, currently set on contract 
  await readCounter();

  // Let's modify the state now
  const txDetails = await shiftCounter(13);
  console.log({ txDetails });

    // Now we can check that value is actually changed
  await readCounter();
})();

When the code on the page will execute it will present you a popup, allowing to choose which wallet to use.

⚠️ You need to have Lilico installed in order for it to appear in the list. Consult one of our previous articles for details how to install and setup Lilico.

If you were to choose Lilico, you will be presented with following flow. First it will ask you to connect wallet to our dapp:

Then ask for confirmation. You can expand/collapse script pane to check the code of the transaction.

💡 Actually, you should ALWAYS check what you are signing. Even on Testnet. It’s a good habit, that will help you make your interaction with Flow more secure 😉

Blocto will guide your through a similar process:

And it also has a way to check the transaction code:

After all said and done you should see the following in your console (numbers might change):

{ counter: "234" }
{ txDetails: Object }
{ counter: "247" }

Expanding txDetails will give your more information about the transaction:

blockId: "ad7605f10f9846dd1c5603723b1d12995a3152b19a1ca24e47a3a2e28cee0641"
status: 4
statusString: "SEALED"
statusCode: 0
errorMessage: ""
events: Array(3)

Until next time! 👋

Resources

Full Source Code - https://codesandbox.io/s/dev-to-part-13-modify-chain-state-1oy1l7
FCL - mutate method - https://docs.onflow.org/fcl/reference/api/#mutate
Cadence - Transactions - https://docs.onflow.org/cadence/language/transactions/
Lilico Wallet - https://lilico.app/

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

Создаем на Flow | Изучаем FCL - 1. Введение

Max Daunarovich — Wed, 29 Jun 2022 12:48:46 +0000

Краткий обзор

После того, как вы закончите чтение этой статьи вы будете знать:

что такое FCL и зачем он вам нужен
как настроить FCL JS для взаимодействия с Тестовой сетью (Тестнет / Testnet) блокчейна Flow
как запустить исполнение простого скрипта написанного на языке Cadence

Что такое FCL?

Flow Client Library (FCL) - это стандартизированный набор коммуникационных шаблонов между "кошельками" (wallets), приложениями и пользователями, который используется для выполнения большого разнообразия действий в вашем децентрализованном приложении. Различные языки программирования имеют свои собственные имплементации концепции FCL и стандарта.

В среде Javascript, это NPM-пакет, который используется для взаимодействия между кошельками, пользователем и блокчейном Flow, как в браузере так и на серверной стороне.

Подожди, а что за блокчейн такой, Flow?

Я рад, что вы задали такой вопрос! Flow - это блокчейн, созданный специально для нового поколения приложений, игр и цифровых “предметов” используемых в них.

Есть много различных характеристик, которые делают Flow уникальной “цепью”. Вот некоторые из них:

Cadence - это новый легко-изучаемый ресурсо-ориентированный язык программирования, разработанный для децентрализованных приложений (dApps) и цифровых “предметов”
Обновляемые Смарт-Контракты - позволяет безопасно и “прозрачно” исправить ошибки и обновить предопределенные части смарт-контракта
Быстрая и Детерминированная Завершенность (Finality) - Flow разработан таким образом, чтобы быть быстрый и отзывчивым - позволяя достигнуть глобальной завершенности в течении нескольких секунд

Вы можете найти больше информации о блокчейне Flow на сайтах https://flow.com и https://docs.onflow.org/

К сожалению, в данный момент документация доступно только на английском языке 😢
Но мы работаем в этом направлении и обновим ссылки на русско-язычные ресурсы, как только они станут доступны

Простой Пример

В последующих статьях мы покажем более сложные и значительные пример, но пока давайте попросим тестовую сеть Flow вернуть нам определенное число (пожалуйста не убегайте, дальше будет гораздо интереснее 😅)

Воспользуемся платформой Codesandbox (https://codesandbox.io), чтобы было проще поделиться с вами готовым решением и позволяя вам “форкнуть” (создать свою копию, чтобы иметь возможность делать в ней изменения) “песочницу” и попробовать свои идеи.

Шаг 1 - Установка

Добавьте пакет "@onflow/fcl": "1.0.0" в качестве одной из ваших “зависимостей”:

Шаг 2 - Импорт

Программный пакет FCL JS предоставляет множество методов - для “постройки” взаимодействий, конфигурации FCL, взаимодействии с цепью и т.д. Мы импортируем два их них:

query (https://docs.onflow.org/fcl/reference/api/#query)
config (https://docs.onflow.org/fcl/reference/api/#common-configuration-keys)

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

Шаг 3 - Настройка FCL

FCL должен знать, куда ему отправлять скрипт для обработки. Нижеследующий код задаст адрес Узла Доступа (Access Node) используя метод config:

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

Шаг 4 - Исполните скрипт на Тестнете

Для того, чтобы исполнить скрипта на блокчейне Flow, мы можем отправить его при помощи метода query . Наш пример не использует аргументов (параметров), поэтому внутрь query мы передадим только код скрипта:

  const cadence = `
    pub fun main(): Int{
      return 42
    }
  `;
  const theAnswer = await query({ cadence });
  console.log({ theAnswer });

В итоге - Полный Код

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

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

// Мы воспользуемся конструкцией IIFE чтобы автоматически // запустить наш код 
(async () => {
  console.clear();

  const cadence = `
    pub fun main(): Int{
      return 42
    }
  `;

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

После выполнения данного блока кода вы должны увидеть ответ в консоли:

{result: "42"}

Поздравляем! Вы успешно справились с заданием 👍

В следующей статье мы покажем, как вы можете передавать параметры для ваших скриптов. Оставайтесь на связи! 👋

Материалы

(ENG) | Полный пример на Codesandbox - https://codesandbox.io/s/dev-to-fcl-01-introduction-zbhz0v

Ccылки и Исходный Код

(ENG) | Документация Flow - https://docs.onflow.org/ - более детальная информации о блокчейне Flow и как взаимодействовать с ним
(ENG) | Flow Portal - https://flow.com/ - your entry point to Flow
(ENG) | FCL JS - https://github.com/onflow/fcl-js - Исходный код и возможность поучаствовать в разработке библиотеки FCL JS library
(ENG) | Cadence - https://docs.onflow.org/cadence/ - Введение в язык программирования Cadence
Codesandbox - https://codesandbox.io - Замечательная среда разработки и прототипирования прямо в вашем браузере

Build on Flow | Learn FCL - 12. How to Create a New Account with Flow CLI and Testnet Faucet

Max Daunarovich — Tue, 28 Jun 2022 20:19:22 +0000

Overview

In previous posts we’ve covered how to setup your wallet with Blocto and Lilico. While it’s convenient to use those in the browser environment, you won’t be able to do it on server side. But it’s still possible to sign the transactions if you control the private key corresponding to a public key set on account.

So in this post will teach you how to:

install Flow CLI
generate private/public key pair using Flow CLI
create new account using Testnet Faucet

Step 1 - Installation

First we will need to install Flow CLI. The process is pretty straightforward and explained in details here → Flow Documentation - Install the Flow CLI.

After the installation is completed, you can check that it’s working properly by checking version of installed Flow CLI:

flow version

At the time of writing latest released version is v0.36.1 and that’s what you should see in the terminal window:

% flow version
Version: v0.36.1
Commit: 5a1d7bfa90fb95ac3335d9c5ea214a6ef445759b

Step 2 - Generate Key Pair

Next thing we need to generate key pair - private and public keys. We will use the former to sign transactions and the latter to attach to a newly created account, so we could control it.

The easiest way to generate fresh key pair is - drum rolls 🥁 - Flow CLI! Boi, what a handy tool it is 🤩. Run this in your terminal:

flow keys generate

The output will be similar to this:

🙏 If you want to create an account on testnet with the generated keys use this link:
https://testnet-faucet.onflow.org/?key=95b37b7d759c09532ffbda33bcd65bd6826366fe0d518e1bdbead62a9e51a2f19db0fb4e0bbf0b4a35048437423fc87dfc00349096723d75c2e3bfbf2246895e 

🔴️ Store private key safely and don't share with anyone! 
Private Key      feca763f32039483394bf0b416c55fea7c9e07f43bc48ccf02de66a774346b49 
Public Key   95b37b7d759c09532ffbda33bcd65bd6826366fe0d518e1bdbead62a9e51a2f19db0fb4e0bbf0b4a35048437423fc87dfc00349096723d75c2e3bfbf2246895e

⛔ Attention! Do not share your private key with anyone. I’m showing you mine here for editorial purposes. But you should keep your private key in some safe place.

🙈 Post-it note on your monitor is not safe place…

⚠️ Windows OS have some issues with splitting the lengthy keys, so when you copy/paste it from your terminal ensure there is no extra space characters in the middle 😤

You can copy that link Flow CLI created for you to pre-populate Paste Your Public Key or you can open Flow Testnet Faucet and do it manually. Either way is OK 🙂

Keep ECDSA_P256 for Signature Algorithm and SHA3_256 for Hash Algorithm as those are used by CLI to prepare your keys. Then mark checkbox and pass CAPTCH test, confirming you are human (🤖 got you, meat bags!). Press Create Account and you are done! 🙌

Write that address down - better alongside private key 😉 - cause we will need it for signing as well.

Congratulations! Now you are the owner of freshly baked Flow Testnet account! 💪

Until next time, my fluffy kittens! 👋 😸

Resources

Install Flow CLI - https://docs.onflow.org/flow-cli/install/
Generate Key Pair - https://docs.onflow.org/flow-cli/generate-keys/
Flow Testnet Faucet - https://testnet-faucet.onflow.org/

Build on Flow | Learn FCL - 11. How to Install and Create a New Testnet Account with Lillico

Max Daunarovich — Tue, 28 Jun 2022 20:04:28 +0000

Overview

Similar to Blocto Wallet we’ve covered last time, Lilico is another wallet, which lets you create account for Mainnet and Testnet. So this post will teach you how to:

install Lilico Chrome extension
setup your wallet
switch to “Developer Mode”

Let’s start! 💪

Step 1 - Installation

Go to the Chrome Web Store and install Lilico - https://chrome.google.com/webstore/detail/lilico/hpclkefagolihohboafpheddmmgdffjm

Step 2 - Setup

Click on extension icon in top right corner of the browser panel and go through a step-by-step process.

Pick your username

Copy and save your recovery phrase. This one is really-really important if you intend to use this wallet not only for development, but as your primary mean of signing transactions

Create password - it will be used to unlock your wallet before using it.

(Optional) Create Google Drive backup, so you can restore the wallet in the future if you forget your password

🎉 Congratulations! Now you have Lilico Wallet in your browser and ready to sign some transactions 😁

You can see your address in the top part of the window.

Before we continue, let’s click on that gear icon (bottom panel, the one on the right) and click Developer Mode

This will allow you to enable Developer Mode and switch network to Testnet (which we will use to mitigate the damages we can inflict😅)

Notice that your address on Testnet changed as well.

That’s it! Now your Lilico Wallet is properly set up and ready for action 🙂

Until next time! 👋

Resources

Install Lilico - https://lilico.app/
Lilico Twitter Account - https://twitter.com/lilico_app

Build on Flow | Learn FCL - 10. How to Create a New Testnet Account with Blocto Wallet

Max Daunarovich — Tue, 28 Jun 2022 19:57:06 +0000

Overview

Our previous exploration of Flow Network were pretty harmless - scripts can’t change the state of the chain, they can just read the data from it. It’s time to change this and make some “dents” here and there. But in order to do this, we will need Flow account. It’s possible to do this in 4 different ways:

Using Blocto Wallet (this is the topic of this post)
Using Lilico Wallet - we are covering this in Chapter 11
Via Flow Faucet and Flow CLI - check Chapter 12 of this series
by signing and submitting a transaction, which would create new account (you need to have one, though 😛)

Personally, I gravitate toward the opinion that easiest way to make new account is Blocto Wallet. This is what we gonna do today:

create new account with Blocto Wallet
authenticate into account via FCL and Blocto Wallet
get account balance, using wallet address

How?

There are 2 ways to create new wallet with Blocto:

using mobile app
using FCL pop-up

There are multiple articles outlining the process of wallet creation with mobile app. For example:

While mobile is great and all - we will reduce extra steps and create our wallet using FCL.

Blocto provides nice step-by-step instructions how to configure and then invoke login popup on their doc site. We will use those bits and pieces to make Blocto Wallet Creator 🧙‍♂️!

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 methods from FCL
import { unauthenticate, logIn, config } from "@onflow/fcl";

// Specify the API endpoint - this time we will use Testnet
const api = "https://rest-testnet.onflow.org";

// This is the endpoint, which will be responsible for wallet authorization
const handshake = "https://flow-wallet-testnet.blocto.app/authn";

// Configure FCL to use mainnet as the access node
config()
  // connect to Flow testnet
  .put("accessNode.api", api)
  .put("challenge.handshake", handshake);

Step 3 - Create Login Sequence

// We will use IIFE to execute our code right away
(async () => {
  console.clear();

  // just in case we have authenticated user, we will log him out first
    await unauthenticate();

    // calling "logIn" will invoke "Sign in with Blocto - Testnet" popup
    const wallet = await logIn();

  console.log({ wallet });})();
})();

Step 4 - Launch!

When the code will be executed, you should see popup with title “Sign in with Blocto Testnet"

Fill in your email address and press “Sign in / Register” button.

After that you should get a passcode in your inbox for the email you’ve provided on previous step.

If the passcode is correct, Blocto popup will show your wallet address:

After pressing “Confirm” button console log should be populated with account details (this is for my address, but yours should look similar):

{
    f_type: "USER",
    f_vsn: "1.0.0",
    addr: "0xe7dd0f2ee4e077e2",
    cid: "ca88f086a545ce3c552d80",
    loggedIn: true,
    expiresAt: 1656443452552
}

Congratulations, now you are the owner of freshly baked Flow account 🍰!

Step 5 - Get Account Balance

Let’s use our knowledge from previous post and fetch our current balance. In order to do this, let’s update our imports:

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

and update our IIEFE:

// We will use IIFE to execute our code right away
(async () => {
  console.clear();
  await unauthenticate();

  const wallet = await logIn();
  console.log({ wallet });

    // We will take only "balance" field from account details
  const { balance }= await account(wallet.addr);
  const flowBalance = result.balance / Math.pow(10, 8);
  console.log({ flowBalance });
})();

That’s 0.001 FLOW on your account. You are rich 🤑!

Until next time 👋

Resources

Codesandbox Wallet Creator - https://codesandbox.io/s/dev-to-fcl-create-account-q60f2b
Docs: Create Flow Wallet - https://docs.onflow.org/flow-token/available-wallets/
Blocto: Login / Register - https://docs.blocto.app/blocto-sdk/javascript-sdk/flow/login-register#step-1-configure-fcl

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

DEV Community: Flow Blockchain

Build on Flow: JS Testing - 4. Storage Inspection

Intro

Inspect Available Paths

Get Type Restrictions on Path

Read Storage Values

Storage Stats

Jest Helpers

shallHavePath(account, pathName)

shallHaveStorageValue(account, {props})

Build on Flow: JS Testing - 3. Execute Scripts and Send Transactions

Intro

Prerequisites

Calculator

Account Management

Read Balance

Contract Access

Short Notation

Cadence Ninja Mutants 🐢

Send via Short Notation

Build on Flow: JS Testing - 2. Setup Emulator and Deploy Contracts

Intro

Prerequisites

Setup Cadence Folder

Setup Emulator

How to Deploy a contract?

Too slow!

Build on Flow: JS Testing - 1. Introduction

Intro

Testing Options

What is Flow JS Testing?

Prerequisites

Installation

Link and Sources

Build on Flow | Learn FCL - 16. How to Send FLOW Tokens to Another Account

Overview

Theory

Step 1 - Installation

Step 2 - FCL Config

Step 4 - Imports

Step 3 - Implement getFlowBalance function

Step 4 - Implement sendFlow function

Finally

Resources

Build on Flow | Learn FCL - 15. How to Add and Revoke Public Keys

Preface

Overview

Wallet Limitations

Investigation

Step 1 - Installation

Step 2 - Create a signer

Step 3 - Configure FCL

Step 4 - Implement addPublicKey

Step 5 - Implement revokePublicKey

Finally -

Resources

Build on Flow | Learn FCL - 14. How to Mutate Chain State by Signing Transactions with a Private Key

Preface

Step 1 - Installation

Step 2 - Create a Signer

Step 3 - FCL Setup

Step 4 - Implement readCounter

Step 5 - Implement shiftCounter

Finally

Resources

Build on Flow | Learn FCL - 13. How to Modify the State of the Chain by Signing Transactions with Wallets

Overview

Preface

Step 1 - Installation

Step 2 - Setup

Step 3 - Get Current Chain State

Step 4 - Modify Counter

Finally

Resources

Создаем на Flow | Изучаем FCL - 1. Введение

Краткий обзор

Что такое FCL?

Подожди, а что за блокчейн такой, Flow?

Простой Пример

Шаг 1 - Установка

`shallHavePath(account, pathName)`

`shallHaveStorageValue(account, {props})`

Step 3 - Implement `getFlowBalance` function

Step 4 - Implement `sendFlow` function

Step 4 - Implement `addPublicKey`

Step 5 - Implement `revokePublicKey`

Step 4 - Implement `readCounter`

Step 5 - Implement `shiftCounter`