DEV Community: Max Daunarovich

Chapter 1: Boring SVG Manipulation

Max Daunarovich — Thu, 16 May 2024 23:58:51 +0000

Exposition

The exposition is a set of scenes in a story that are meant to introduce the audience to the characters, world, and tone of the story. It is relatively short, and no major changes occur during these opening scenes.

It was a nice calm evening, right after successfully lunched project. The feeling of accomplishment started to wither away and my mind started to wonder how to occupy itself. I heard a bip and new email messages popped up in my inbox, notifying me that I just won 3rd place in Apparel Challenge on www.kittl.com. I jumped to check the result, then some of applicants who was close or got exact number of votes, then to the Pinterest and then back to Kittl.

I played around with leftover ideas for the past challenge, but haven’t posted anything. Then I got curios how Kittl is making money, so I looked around what is their business proposition, how they build a community, checked multiple videos they posted on Youtube (lots of quality content there, highly recommend to check it out if you are interested), then researched what’s happening in POD (print on demand) domain, watched a bunch more videos from influencers, creators and debunkers to broaden the understanding of supply and demand…

At some point I got back to Kittle and stumbled into Careers page. There was an open position for Senior Frontend Engineer (Rendering) role with some more useful information about the team and their business. But on top of that there was this requirement that got most of my attention:

Domain Knowledge: Vector graphics and SVG manipulation, with experience in rendering and displaying SVGs. Proficiency in Canvas 2D is a plus.

I skimmed the rest of the description, putting mental checkmarks against skills I had under my belt and got back to Domain Knowledge.

What would be the perfect demo to leave positive impression during interview if I would wanted to get this role? Now, this sound like something than can feed my curiosity and exploration itch for quite a while!

TL;DR

If you wonder what this is all about and whether you should continue reading this, I’ll tell you.

This is an article about how you can compose expertise in different vaguely related fields into something new. It’s about self-doubt and perseverance. How one should start small, make even smallest steps, but still walking forward. How complex tasks can be chunked into smaller, more digestible pieces and then reassembled back. How everything is achievable if you put your fear and doubt on hold and carry on till the goal you set is reached.

Still with me? Good! Let’s go!

The Stars Align

Nowadays I am a Lead Frontend Developer at FindLabs, but I was trading my time for about 10 years as UI/UX designer designing interfaces for a wide range of different applications and domains. I had plenty hands on experience using vector based tools - CorelDraw, Illustrator, Photoshop (still my favorite one) and Figma - to design and prepare graphics for production (both print and on-screen).

As a matter of fact, I also explored SVG internals, capabilities and limitations and had bunch of experiments with SVG manipulation, when I was trying to switch my career from design into development field. My Dribbble profile still have some of them, alongside Canvas and CSS sandboxes.

I was in awe that SVG have native support for filters (blurs, shadows, complex color compositions, etc.), animation and even interactivity (albeit limited)!

And canvas felt almost natural and invoked heavy nostalgia from the first time I touched keyboard and wrote primitive program to draw a house out of lines utilizing Basic. Later on I had a chance to broaden my expertise, when I was doing my hobby game project with Pixi and small bits and pieces on FindLabs pages.

So, yeah. I wasn’t going blindly into the battlefield 😅

What to build?

Kittle provides you with a set of tools to create impressive vector and bitmap based designs using only browser. Which makes it readily available and accessible for everyone with a computer and a mouse. No need to install “heavy” and expensive software. You can start creating right after you register!

One of the coolest features I’ve seen in Kittl - which is missing in, for example, Figma - is text styles and warping based on a curve. Like this:

This is powerful and common effect, which allows you to create dynamic designs. I’d say it’s a “staple” one.

In order to implement something similar you will need to know:

how SVG constructs vector image
how coordinate system works in SVG
how text can be represented in SVG format
what are Bezier curves and how they are defined in SVG format
how we can control individual points

How WE gonna do it?

Kittl feature is quite complex, but we will start small. Let’s try to modify the corners of the rectangular shape based on the slope of the straight line. We will assume that leftmost point of rectangle perfectly aligns with left side of rectangle and the same is true for the right side.

For any point on the edge of rectangle, we will take x coordinate of the point, project it on the guide line to calculate the y difference of that point, relative to it’s edge. This will give us the difference we need to apply to original point.

Let's start

Instead of going “whole mile” with using something like React template, we will create a blank HTML file and populate it with minimum content:

<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>SVG Alteration Study</title>
</head>
<body></body>
</html>

Next we will open Figma, create rectangle, convert it to outlines (this is important, since we want to adjust position of individual points), slightly offset the points up and to the side (I will explain why in a bit), add another line below it (we will use it as guide) and export it. Then open file with your text editor (I have Notepad here, it’s more than enough). This is what I got here:

<svg width="640" height="480" viewBox="0 0 640 480" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M146.034 288.994L150.967 140.994L498.945 139.006L491.052 287.005L146.034 288.994Z" stroke="#0F66EA" stroke-width="2"/>
    <path d="M145 366L499 326" stroke="#00B347"/>
</svg>

Plug that into the body tag and open the page in browser. Plain boring pair of rectangle and a line should appear:

But boring is good! It will allow us to manually adjust the values and see how it affects the output.

Let’s examine our SVG in detail. We can see that viewbox of our canvas is 640px wide and 480px. That will be our working area. Anything that would go outside of bounds would be cropped. You can think about it as a camera. Also notice, even though we have width and height properties on <svg> tag - those represent browser dimensions of SVG container, not the working area size. We can make it smaller or bigger if needed, while keeping the same logic and inner elements.

Then we have two paths. First one is most likely define our “rectangular”, since it’s d value (which is responsible for path definition) have more data in it. Second one is our guide line. Let’s add id property to both of them, so we could reference them later:

<svg width="640" height="480" viewBox="0 0 640 480" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="target" d="M146.034 288.994L150.967 140.994L498.945 139.006L491.052 287.005L146.034 288.994Z" stroke="#0F66EA" stroke-width="2"/>
    <path id="guide" d="M145 366L499 326" stroke="#00B347"/>
</svg>

Back to the d property. Take a look at guide’s path - M145 366L499 326 . That’s a bit cryptic isn’t it? But inside of it there is a set of instructions how to plot this line. Let’s modify it to look like a tabular data, using characters like M and L as a marker to start a new line:

M 145 366
L 499 326

Ha, now this is a bit easier:

capital M instruction will move the “tip” of your pen to a specific location (X, Y) relative to (0, 0) point and will wait for next instruction.
capital L will draw a line from current “tip” position to (X, Y) coordinate (relative to zero point)

Meaning those two lines of instructions will move the pen to (145, 366) and then draw a line to (499, 326).

Note that L instruction will keep the tip at (499, 326). If we would write another L instruction, for example, L 520, 350 it will connect points at (499, 326) and (520, 350).
Even though it doesn’t affect how we approach the solution, it’s important to understand the process in details.

Now to our target path. We will do the same - split instructions on individual lines:

M 146.034 288.994
L 150.967 140.994
L 498.945 139.006
L 491.052 287.005
L 146.034 288.994
Z

Let’s round decimal parts on points to closest integer:

Capital Z instructions signifies that shape is closed and can be filled with color.

You can also define multiple overlapping paths, dividing the definition with Z instructions. We will see the example later on, when we would try to warp the text.

Let’s translate it:

Move cursor to (146, 289)
Draw a Line (146, 289) → (150, 140)
Draw a Line (150, 140) → (498, 139)
Draw a Line (489, 139) → (491, 287)
Draw a Line (491, 287) → (146, 289)
Ze end

Now we understand how shapes and paths are created, so we can edit them! We can try to create our own parser (which I did 🙈) , but let’s use some existing solution instead. I’ve found parse-svg-path library, which will do the job.

Add complexity

Let’s initialize our project with pnpm and Vite, so we can utilize 3rd party libraries in the project.

pnpm init
pnpm add vite

Then install prettier (to keep the code nice and tidy) and parse-svg-path:

pnpm add prettier parse-svg-path

Add dev command to scripts in package.json

  "scripts": {
    "dev": "vite"
  }

Make index.html and plug the code from above:

<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>SVG Alteration Study</title>
</head>
<body>

<svg width="640" height="480" viewBox="0 0 640 480" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="target" d="M146.034 288.994L150.967 140.994L498.945 139.006L491.052 287.005L146.034 288.994Z" stroke="#0F66EA" stroke-width="2"/>
    <path id="guide" d="M145 366L499 326" stroke="#00B347"/>
</svg>

<script type="module" src="main.js"></script>
</body>
</html>

Create main.js and utils files and put some simple code to make sure our Vite setup is working properly:

// this goes into utils.js
export function hello(){ console.log("Hello, world!") }

// ------------------------------------------------------
// and this is our main.js
import { hello } from "./utils";

hello()

Now run pnpm run dev and you should see the page with our rectangle and hello world in the console. Well done! 👍

Geometry Time ⌚

In order to calculate the offset we need to apply to the point, we can use basic geometry a devise a ratio using points coordinates:

On the left hand side we have our Y offset and on the right we have ratio in the range from 0 to 1 multiplied by maximum offset. Let’s capture this in form of utility function we can use later.

First let’s check what parse-svg-path library will provide us. This way we won’t need to make extra conversions later on and make our utility work with formatted data right away:

parse('m1 2 3 4') // => [['m',1,2],['l',3,4]]

Right, so it will be array of arrays. Got it!

Our utility function will accept a tuple of tuples for guide points as first param and another tuple for point we want to offset.

export function getOffset(guidePoints, offsetPoint) {
    const [[x0, y0], [x1, y1]] = guidePoints;
    const [x, y] = point;

    const ratio = (x - x0) / (x1 - x0);
    const maxOffset = y1 - y0

    return ratio * maxOffset
}

Back to our main.js:

import parse from "parse-svg-path";

function run() {
  // Grab nodes
  const guide = document.getElementById("guide");
  const target = document.getElementById("target");

  // Extract path definitions
  const guidePath = guide.getAttribute("d");
  const targetPath = target.getAttribute("d");

  // Parse points
  const guidePoints = parse(guidePath);
  const targetPoints = parse(targetPath);

  console.log(guidePoints);
}

// Run, Forest, run!
run();

This will grab the DOM nodes, extract paths from them and try to parse guide points:

[
    ["M",145,366],
    ["L",499,326]
]

That’s good! Now, since we know that this path will always have only two points (since we control how it is created) and parsing it will produce known result we can convert it to desired shape - something that getOffset can consume. We will use .map method on array and simply slice first value:

const guidePoints = parse(guidePath).map(point => point.slice(1))

This will give us clean pair of tuples to use as guide points.

[ [145,366], [499,326] ]

Next we will create a mapper for targetPath. We will use currying to create a function, which will return us another function, which then be applied to every point in our parsed instruction set via .map method:

export function offset(guidePoints) {
  return function (point) {
    const [instruction, x, y] = point;
    if (instruction === "Z") {
      return point;
    }

    // calculate offset
    const offset = getOffset(guidePoints, [x, y]);
    // apply it to Y coordinate
    const newY = y + offset;

    // plug it back into instruction set
    return [instruction, x, newY];
  };
}

And apply it:

  const targetPoints = parse(targetPath)
  const offsetPoints = targetPoints.map(offset(guidePoints));

If we will output the result into console we will see that Y coordinate of the point actually changed, compared to reference (targetPoints). Though right now it’s in array form and to display it we need to convert it back to path definition. Let’s implement zip function that will do just that:

export function zip(instructionSet) {
  return instructionSet.reduce((path, instruction) => {
    return path + instruction.join(" ") + "\n";
  }, "");
}

Import it in main.js and apply to offsetPoints:

import parse from "parse-svg-path";
import { offset, zip } from "./utils";

// ...

const offsetPath = zip(offsetPoints);
console.log( offsetPath );

This will produce nice and clean output:

M 146.034 288.87716384180794
L 150.967 140.3197627118644
L 498.945 99.01221468926553
L 491.052 247.9030790960452
L 146.034 288.87716384180794
Z

Now let’s plug it back into our SVG canvas.

Create another path on the canvas, add offsetShape id so it can be referenced and adjust the style of target path to be displayed with dashed stroke line:

<svg width="640" height="480" viewBox="0 0 640 480" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="target" d="M146.034 288.994L150.967 140.994L498.945 139.006L491.052 287.005L146.034 288.994Z" stroke="#CCC" stroke-width="1" stroke-dasharray="4 6"/>
    <path id="guide" d="M145 366L499 326" stroke="orange"/>

    <path id="offsetShape" d="" stroke="green" stroke-width="2"/>
</svg>

Update the code in main.js :

  // Apply offset
  const offsetPath = zip(offsetPoints);
  const offsetShape = document.getElementById("offsetShape");
  offsetShape.setAttribute("d", offsetPath);

..and voilà 👇

You can play around with second coordinate of the guide path to check how it affects the target shape. For example, let’s slope it down instead of up. The beauty of our setup is that we only need to change the d parameter of the guide path and refresh the page (actually Vite will do refreshing part, if you still have dev server running):

<path id="guide" d="M145 366L499 420" stroke="orange"/>

That’s a win! We can apply this to any shape now, right?

P.S.

Second chapter will be more fun, I promise. Stay tuned! 😁
In the mean time, I’ve compiled the code from above into sandbox, so you can fork it here 👈

Darling, I converted our perfectly fine SPA application into SSR: Part 2

Max Daunarovich — Tue, 14 May 2024 09:59:54 +0000

Introduction

If you're just tuning in, the first chapter detailed our approach to creating the SPA (Single Page Application) version of Flowdiver. We explained the reasoning behind our decisions and the challenges we encountered.👍

In this chapter, we'll discuss our experiences in migrating the SPA to a Next.js framework, employing an SSR (Server-Side Rendering) strategy to tackle some of the ongoing "problems."

The Lab

Preparation

To ensure that our decision was the right one, we took some time to evaluate other existing solutions on the market.

Next.js stood out due to its large community, the abundance of examples, and the availability of templates. However, the "recent" shift from a pages router to an app router, along with the introduction of client and server components, and the overall feeling that Next.js might be too cumbersome for our needs, sent us on a quest for new horizons.

Qwik

We just wrapped up our FindLabs corporate website using Qwik and thought we could utilize our newly acquired experience.

Pros

Qwik was incredibly fast and straightforward to set up for SEO and achieving good web metrics. The clear separation between client and server-side code, utilizing useVisibleTask$() was a breeze to manage and didn't require complex mental gymnastics to understand the migration process.

Cons

The SPA version heavily utilizes Styled Components, and although it's feasible to use the styled-vanilla-extract library and migrate the code with minimal changes, some parts would still need refactoring since CSS is pre-built during compilation. We've previously used the useStylesScoped$ function while building a corporate website, but it often felt more like a hack than a solid solution.

Another significant challenge was the render props pattern. We heavily rely on this for our table component to ensure a high level of customization and abstraction. However, Qwik's architecture is fundamentally different—the framework aims to fragment the code into the smallest possible chunks and load them in parallel. This means it attempts to serialize your render functions, which becomes a mess real fast.

Additionally, the contexts that Flowdiver heavily depends on would be unworkable and would require a complete redesign into a new composition. While these changes are manageable, we wanted to minimize disruption as much as possible.

Considering all these pros and cons, we decided to put this on the bench for a better use case 🙏.

Waku

While researching server-side components, we discovered Waku—a minimal React framework that facilitates the use of SSR (Server-Side Rendering) and SSG (Static Site Generation) approaches effortlessly 👍.

Pros

Waku struck the perfect balance we were looking for—a compact footprint on both client and server sides, along with a clear division of domains.

The front page did an excellent job of clearly and efficiently explaining the concepts of client-/server-side components: data fetching, SEO, routing—all the puzzle pieces began to fall into place.

We bootstrapped an app and attempted a minimal setup migration. The community and the author on Discord were incredibly responsive, offering valuable tips and explanations on various concepts and strategies.

Sounds like a dream, right? Well, yeah...

Cons

The unstyled concept was functioning flawlessly, but we had to abandon styled-components almost immediately. The documentation covered CSS modules well, but lacked information on styled components and similar approaches. At that point, we realized that sticking to a well-tried solution might backfire... 🙈

Similar to Qwik, the use of contexts in Waku also appeared to be challenging and required significant refactoring to manage props drilling effectively.

Moreover, as we were experimenting with it, new features were continuously being released, making the framework feel somewhat unstable and experimental as well.

What’s Next?

In the end, we found ourselves back where we started, but with newfound knowledge and confidence in our choice.

Pros

Next.js stands out as the most seasoned of all React-based full-stack frameworks. With dozens of examples and templates available, and hundreds of resolved issues on GitHub backed by multiple contributors, there's reassurance that it won’t just disappear over the weekend because the original author decided to move on from his project.

It’s also a match made in heaven for Vercel deployment. True to its promises, some features (notably PPR) are exclusively viable on Vercel due to the tight integration and finely tuned setup.

Cons

Server-side components still didn't make much sense with us at that time 😅

However, we decided it was time to shed our apprehensions and start tinkering!

Take 1 - Heads-on!

We opted for the app router as it appeared more modern and future-proof. Moreover, it seemed like a logical next step from react-router. It also supports server components, which were crucial for our application. Plus, the layout fragments really seemed promising!

With our mindset focused on minimal changes and limited time commitment, we set up the basics that would allow us to work with styled-components and render them on a blank page. Once this foundation was laid, we began to migrate (or more accurately, copy/paste 😅) our components into the Next.js-based repository.

One component,
Two components, done!
Errors during compilation,
None!

Well, not exactly. We were soon overwhelmed with errors like:

You're importing a component that needs createContext. It only works in a Client
Component but none of its parents are marked with "use client", so they're Server
Components by default.

  │ Learn more: https://nextjs.org/docs/getting-started/react-essentials
  │ ...

But we came prepared, haha! We just needed to tag some files with use client. So this one, that one... and that one too!

In the end, we marked almost EVERYTHING with use client and inadvertently exposed our Hasura token to the public domain. Not exactly what we had planned, but hey, at least it was functioning. A living and “breathing” system. Yes! 👍

Take 2 - We Require More Minerals

The next step was to migrate the rest of the pages. So, we thought, why not transfer about a hundred files at once? What could possibly go wrong? Fortunately, with our root layout file flagged as use client, everything below it was also tagged as "dirty," and thus the compiler remained silent, untroubled by our actions.

However, trouble started brewing as soon as we began refactoring pages into server-side components...

Here’s the snag: client components can’t import server components. Yet, we desperately needed that ThemeProvider from styled-components to function correctly. Moreover, various other context providers needed to be positioned at the top, so they were accessible for data reading across the board.

We plunged into the refactoring, attempting to determine what should remain a server component and what needed to be client-side. Yet, a relentless cascade of - It only works in a Client Component - made it seem like we were running in circles, getting nowhere fast.

It was time to pull back, reassess, and develop a new "pipeline" for how we would transition our SPA into the promised land of SSR.

Take 3 - Slow, but Steady

We stripped everything down to the bare bones and began piecing the pages back together, labeling only the absolutely essential elements as client components. Fortunately, most of these necessities were related to styled-components and nestled within the styles.tsx files.

Hooks, particularly useState and useSearchParams, were reliable indicators that a file belonged on the client side of the network boundary. However, some could seamlessly receive searchParams props directly from page.tsx without switching allegiances.

We tackled the migration one route at a time, and it all seemed to be going smoothly, until we encountered the more complex pages—like those for accounts or transactions:

These pages featured some static elements—like status and transfers at the top—and more dynamic components controlled by tabs. We considered collecting all the data and distributing it to child components via context, but that approach would only be effective in this specific scenario. The account page, in particular, demanded more diverse data, which would necessitate pulling from the server or refreshing the page with new search parameters.

This led us to the decision to utilize parallel routes for implementing the tabs. This strategy allowed us to establish clear distinctions in data fetching for each tab without the complication of tight coupling. As a result, the render tree remained neat and tidy, while all the logic was appropriately segregated within its own domains:

At this point layout.tsx in the sub-route /tx/[id] operates as a component, alongside page.tsx and all the parallel routes. We used Suspense to effectively display loading states, ensuring that user experience remains smooth and uninterrupted during data fetching. Importantly, we carefully manage security by not exposing our token when fetching data.

Houston, We Have a Problem

While most of the components and pages function as intended, some fall short...

Take our custom table component, for instance. In the SPA setup, displaying the loading state was straightforward—we simply retrieved it from the context. However, in the SSR framework, components like the table header and pagination controls need to be visible before the data is fetched. This necessitated some serious refactoring and clever component rearrangement.

Before, our context provider enveloped the table; now, this needs to be shifted into the children block because data fetching occurs server-side, across the network boundary. We refactored the code, injecting additional props into the table (since it could no longer access these from the context) and ended up with the following configuration:

While most of the components and pages works as intended, some don’t…

For example, our bespoke table component. In SPA implementation it was easy to show loading state - we can simply pull it from context. But in SSR our table - at least header and pagination controls - should be visible before data is fetched. That was asking for a refactoring and some component juggling.

Previously, we had context provider wrapping up table, now it should be part of the children block, cause data fetching is on server side of network boundary. We refactored that code, passed extra props to the table (cause now it couldn’t read them from context) and end up with following:

AccountTransactionsProvider is a server component that fetches the data and then passes it into TableDataProvider via props. And TableDataProvider is a client component that can properly work with contexts:

That was an Aha! moment in understanding how to compose server and client components. You can’t import server components from client boundary, BUT, you can render the result of their execution in your client components. You just need to pass them as children or render props!

So the following composition is perfectly fine:

        <RootServerComponent>  {/* <--------- SERVER */}
            <ClientComponent renderProp={<SDFComponent/>}> {/* <--------- CLIENT */}

                {/* the following code will be passed as "children" */}
                <SmallServerComponent> {/* <--------- SERVER */}
                    <InnerClientComponent> {/* <--------- CLIENT */}
                        <ServerCounterComponent /> {/* <--------- SERVER */}
                    </InnerClientComponent>
                </SmallServerComponent>

                {/* ... and then we can control where to put SDFComponent in layout */}
            </ClientComponent>
        </RootServerComponent>

If you prefer not to manage this composition at the root level and aim for modularity, you can achieve this by enhancing your ClientComponent to accept additional properties—for example, a renderProp. You can then trust that it will include the necessary representation, allowing you to construct your layout in any preferred manner.

Personally, I consider the Render Props pattern to be one of React's most powerful features.

The Final Hurdle

The very last “challenge” involved transitioning from the useSearchParams hook provided by react-router to its counterpart in next.js. The twist with Next.js is that while it lets you read the search parameters, it doesn’t offer a direct setter. This requires a more hands-on approach involving a trio of hooks: usePathname, useRouter, and useSearchParams. To manage this, you have to construct your own setter. The process would typically look something like this:

  const searchParams = useSearchParams();
  const router = useRouter();
  const pathname = usePathname();

  // later in code

  const params = new URLSearchParams(searchParams?.toString() || "");

  if (field) {
    params.set(field, fieldValue);
    params.set(field, fieldValue);
  } else {
      params.delete(field)
  }

  router.replace(pathname + "?" + params.toString(), { scroll: false });

We moved this into a convenient hook, so we could reuse the code and update multiple parameters simultaneously—a necessity for managing the filters in our table.

Cherries on top 🍒🍰

Leveraging Next.js, a server-side solution, made setting OpenGraph metadata, titles, and descriptions for our pages simply a breeze. This final requirement was almost effortlessly fulfilled. However, we encountered a hiccup with @vercel/og, which refused to render fonts properly, even the bold variant of the default one.

After some troubleshooting, we discovered that Noto Sans, included in the package, only supports a 400 weight. Attempts to load custom fonts from the file system did not pan out as expected—the documentation and examples lacked clear guidance on implementation. Furthermore, deployment introduced peculiar bugs, even though the local solutions worked just fine.

Despite these challenges, experimenting with Satori (the library that lets you create SVG/PNG images by defining them with HTML) proved to be quite enjoyable. We would definitely consider using this package in future projects.

Additionally, caching was readily available right out of the box, allowing us to lessen the load on our servers and enhance the overall user experience.

Postmortem

Aside from the initial confusion surrounding server components, the majority of the migration process unfolded smoothly.

The groundwork established during the SPA implementation proved to be robust and resilient, carrying us through the migration with only minimal adjustments needed.

Most of our headaches stemmed from styled-components. Despite the merits of this CSS-in-JS library, it doesn’t mesh as seamlessly with server components. Traditional CSS methodologies, such as BEM (Block, Element, Modifier), CSS modules, or even utility-first frameworks like Tailwind, would have alleviated many of our difficulties. This lesson is a key takeaway that we plan to carry forward into our future projects.

This is how we've utilized our expertise and built solid data-driven application

Max Daunarovich — Fri, 03 May 2024 15:34:55 +0000

Introduction

One of the key projects FindLabs has created and currently supports is FlowDiver - the Flow Blockchain block explorer. It allows you to inspect different information about the blockchain, without directly interfacing with it (which can require a specific setup and knowledge). For example, you will be able to explore which transactions were included in a recent block, what arguments and code were used for said transactions and what events were emitted as a side effect of changes to network’s state.

There was a single solution on a market back then - FlowScan - which was providing the same kind of information, but there were no public API projects could tap into and private one had it’s own issues - inconsistent data, complex data fetching or inability to filter specific results out, etc.

We’ve seen the potential and interest in the community and started the work from the data layer. When we got the confirmation and understanding the gargantuan scale of the task we bootstrapped front-end app and continued from there.

This post is about our journey - what decisions we’ve made and where they lead us. Grab a popcorn and prepare for a ride! :)

How we tailored it

Pick your poison

Given our team's collective proficiency within the React ecosystem, we decided to leverage this expertise for our project. Initially, we contemplated utilizing Next.js; however, due to the limited practical experience with this technology among key engineers and the pressing timeline to develop the first prototype, we opted for a Single Page Application(SPA) approach. For bundling, we selected Vite, primarily due to its super fast build times, simplicity of configuration, and potential for a nearly seamless transition to server-side rendering.

Styled Components

Next key elements are styled-components and accompanying it styled-system libraries. These gave us a clear separation of CSS rules at the component level and provided a nice way to implement our building blocks.

Yes, it increased the initial bundle size, but that chunk would be reusable and would only be loaded once. Additionally, lazy loading the routes allowed us to cleanly split the app into separate blocks, further minimizing the loading time.

Atomic System

We were loosely following Atomic Design principle to slice our interface into reusable parts. The smallest possible elements would be living under components/atoms, bigger “brothers” and “sisters” would form molecules which would be composed into organisms. This methodology provided a solid foundation and established component composition as the core principle of our design approach.

React Router

React Router v6 was picked as a stable routing solution to support lazy loaded routes, domain code splitting and it was potentially an easier way to port the app to Next.js. Following Atomic Design, we created a pages folder and gathered files for respective routes there. In retrospect, this was a great decision, which made transition to server-side rendering a breeze.

State

Application architecture is rather simple and can be seen as a lose composition of separate modules. Data fetched on a single route is never reused on another route, which makes it easy to describe using React’s useState and urql’s useQuery . Occasional calls to chain were sewn together with backend data using useEffect resolvers. Overall, the system doesn’t require complex state management and data juggling, which made it easier to split tasks between team members and work in parallel.

Context

A good portion of the application consists of tabular representation of data. Data in said tables can be sorted, paginated and filtered. During the design stage we were able to identify repetitive patterns across these component and plan implementation accordingly.

Disregarding props-drilling technique in favor of a more reliable and elegant solution we looked for inspiration elsewhere. Another project of ours .find was using Typesense/Algolia components, which looked a bit like black-box/magic, but at the same time provided a clean approach to build complex and highly customizable solutions.

Our Table component lives within the confines of our data provider and can be expanded with pagination, sorting and filtering solutions. All of the aforementioned parts are decoupled from each other and could be customized for current needs. Some tables are using on-chain data and some use locally stored data. Filtering/sorting logic is purely client-side, while others pull filtered/sorted data directly from the backend and require customized variables for GraphQL queries.

Hasura, urql and Graphql

Our backend sports a huge Postgress database, which is exposed via Hasura service in the form of a GraphQL endpoint. This endpoint provides a schema which paired with graphql-codegen generator to get accurate representation on the client side with all the necessary types and variables for the hooks.

Typescript

While initially we fancied the idea of dropping Typescript to keep momentum and maximum velocity, in the end we are happy we didn’t go that route and decided to do it “right” from the start.

TypeScript offers several benefits to a React project, particularly when collaborating with multiple team members. It introduces static typing, which helps catch errors during compile-time rather than at runtime. This not only enhances the quality of the code but also cuts down on the time needed for debugging. The clear typing system also makes the code more readable and acts as its own documentation, making it easier for team members to understand one another's work. Additionally, TypeScript provides robust tooling that includes autocompletion, type checking, and advanced refactoring capabilities, all of which significantly boost developer efficiency. Moreover, the use of generated types from codegen has allowed for the expansion of generic types, ensuring accurate typing of table elements. It's akin to watching puzzle pieces fit together perfectly.

Deployment

Choosing Vercel was a natural decision as it has become the default method for launching apps that are accessible to a wide audience. The simplicity of configuring environment variables, domains, and other settings facilitated this choice. We have implemented feature branch deployment to guarantee that the code is operational and prepared for peer review.

What went “wrong”

Exposed token

We were initially okay with using an exposed token because there were ways to restrict token rights—either by limiting calls to only those from Flowdiver or by rate limiting the data and frequency of requests. However, this was not an ideal solution as we aimed for a scenario where the token would never be exposed to the client.

No SEO whatsoever

The technology we chose did not offer an easy way for pages to be indexed by search engines. The control over page titles was subpar—looking at you, Helmet—and definitely needed improvement.

Over-engineering

In our quest to perfectly compose complex blocks, we ventured a bit too far into premature optimization. It wasn’t disastrous, but it did mean that some aspects were overcomplicated when they could have been simpler and easier to maintain. We learned our lesson and refactored this overly complex code when we transitioned to a Next.js solution.

Hooks limitations

While the useQuery hooks from urql provided straightforward and clean access to backend data, things got tricky when we needed to combine data from multiple sources. Hooks have to be called conditionally, which led to more complex logic involving one or more useEffect hooks. Although urql allows you to call a query directly and convert the result to a promise, hooks were more convenient, so we endured the complexity and later refactored in Next.js.

Atomic, shmatomic…

We did our best to adhere to the Atomic design approach when creating components. However, the system sometimes didn’t clearly indicate where components should be placed. In some cases, it was obvious that an atom could go anywhere, but in other scenarios, it made more sense to position it near a molecule or organism, especially if it was seldom reused.

This approach didn’t break the app but certainly led to an uneasy feeling that the next person to maintain it might face some challenges and a somewhat rough path.

What Next?

As we continued to roll out new features, we began to explore what it would take to migrate everything to Next.js. This move could address some of the fundamental issues we faced with our current setup and provide a clearer path for the app's growth.

Find out how we did it and the challenges we faced in the next chapter! 😉

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 - Замечательная среда разработки и прототипирования прямо в вашем браузере