Skip to content

1.0.0
Compare
Choose a tag to compare
@justinbarry justinbarry released this 18 Apr 20:44
· 426 commits to master since this release
@onflow/[email protected]
8290784

FCL 1.0 Release Notes

FCL Changelog · SDK Changelog · Issues/Comments

⬆️ Install or Upgrade

npm i @onflow/[email protected]
yarn upgrade @onflow/[email protected]

🚨 Breaking Changes

🚨 Default HTTP Transport Layer

FCL now defaults to using the HTTP transport layer by default. Read more about the benefits here.

Migration to HTTP from GRPC

  1. In your FCL config, replace the accessNode.api to a HTTP enabled Access Node for Flow. Common endpoints are: 
// Configure SDK to use HTTP
fcl
  .config()
  .put("accessNode.api", "https://rest-testnet.onflow.org")

Or Keep using GRPC

  1. Import the send package as shown in the code sample
  2. Define sdk.transport in your FCL config.
import {send as grpcSend} from "@onflow/transport-grpc"
// Configure SDK to use GRPC
fcl
  .config()
  .put("sdk.transport", grpcSend)
  .put("accessNode.api", "https://access-testnet.onflow.org")

🚨 Numbers as strings

FCL currently encodes and decodes values from Cadence. In this breaking change, the decoded value for any Number types are now decoded as a String. The value required for any Number args when encoding needs to be a passed in as a String. Please modify any logic that depends on the type of the response from any FCL interactions.

// before 
return mutate({
    cadence: `
      transaction(a: Int) {
        prepare(acct: AuthAccount) {
          log(a)
        }
      }
    `,
    args: (arg, t) => [
      arg(6, t.Int),
    ],
    limit: 50,
  })
// after 
  const resp = await mutate({
    cadence: `
      transaction(a: Int) {
        prepare(acct: AuthAccount) {
          log(a)
        }
      }
    `,
    args: (arg, t) => [
      arg("6", t.Int), // value is a string now 
    ],
    limit: 50,
  })

🚨 FCL Discovery Configurations

The FCL Discovery Service allows dapps to hook into all available wallets on Flow. If you have been using the UI Version of FCL Discovery, we highly recommend adding the options shown below to your config to prevent Discovery from showing untrusted UI to your users. Read more about FCL Discovery features here.

import { config } from "@onflow/fcl"

config({
  "app.detail.title": "Kitty Items", // Shows user what dapp is trying to connect
  "app.detail.icon": "https://fcl-discovery.onflow.org/images/blocto.png" // shows image to the user to display your dapp brand
})

⚠️ Deprecations

⚠️ Block Signatures

Due to changes to the Access Node, for all block and collection objects used in FCL responses will no longer have signature fields (listed below). These fields were a legacy construct and will be replaced with verifiable BLS signatures in the long run.

  • block.collectionGuarantees.signatures
  • block.blockSeals.executionReceiptSignatures
  • block.blockSeals.resultApprovalSignatures
  • block.signatures

To be deprecated on the next release.

🎉 New Features

🎉 Signing as Payer with Multiple Keys

FCL will now support multiple partial weight signatures (produced by partial weight keys) for a payer of a transaction.

🎉 Extension Support (EXT/RPC)

FCL now supports browser extensions through a new method EXT/RPC. Learn how to build an end-to-end non-custodial FCL compatible chrome extension through a guide and example that was initially developed by the ZayCodes team for FLIP Fest.

🎉 Derive the TxID before sending the Tx

It is possible to intercept the voucher before sending a transaction, this is especially useful if you are trying to derive a TxID before sending it to the chain. See this example.

🎉 New FCL Methods

  • fcl.block
await fcl.block() // get latest finalized block
await fcl.block({sealed: true}) // get latest sealed block
await fcl.block({id: "abc"}) // get block by id
await fcl.block({height: 123}) // get block by height
  • fcl.account
await fcl.account("0x123") // Existing: get account at the latest block
await fcl.account("0x123", {height: 123}) // New: get account at the block with the provided height

🎉 FCL Discovery API

If you want more control over your authentication UI, the Discovery API is also simple to use as it exposes Discovery directly in your code via fcl. Read more here.

🎉 Added AppUtils

Added AppUtils.verifyUserSignatures and AppUtils.verifyAccountProof utilities to verify user signatures for an arbitrary message or account proof data.

⚠️ fcl.config.flow.network or options (fclCryptoContract) override is required to use this api. See FCL Configuration.

const isValid = await fcl.AppUtils.verifyUserSignatures(
  Buffer.from('FOO').toString("hex"),
  [{f_type: "CompositeSignature", f_vsn: "1.0.0", addr: "0x123", keyId: 0, signature: "abc123"}],
  {fclCryptoContract}
)
 
const isValid = await fcl.AppUtils.verifyAccountProof(
  "AwesomeAppId",
  accountProofData,
  {fclCryptoContract}
)

🎉 Wallet utils now send key information from dapp's FCL config

In addition to service and application configuration, FCL now sends useful client information as part of the post message or http request data

{
    services: await configLens(/^service\./),
    app: {
        detail: '',
        icon: ''
    }
    client: {
      fclVersion: VERSION,
      fclLibrary: "https://github.com/onflow/fcl-js",
      hostname: window?.location?.hostname ?? null
    }
}

🛠 Improvements

🛠 Webpack 5 & Bundler Compatibility

Webpack removed out-of-the-box polyfill for Node Standard Libraries for Webpack 5, which needed us to modify FCL to have it work with Webpack and other common bundling solutions. FCL now should work easily with most frameworks and bundlers without additional code or configuration needed.

🛠 Account Proof Service Enhancements

During user authentication, some FCL-compatible wallets will choose to support the FCL account-proof service. If a wallet chooses to support this service, and the user approves the signing of message data, they will return account-proof data and a signature(s) that can be used to prove a user controls an on-chain account.

In order to authenticate your users via a wallet provider's account-proof service, your application needs to
configure FCL by setting fcl.accountProof.resolver and providing two pieces of information.

The fcl.accountProof.resolver is an async resolver function used by FCL to retrieve account proof data
from your application server. It can be set in your application configuration under the fcl.accountProof.resolver
key. The resolved data should include a specific application identifier (appIdentifier) and a random nonce.
This data will be sent to the wallet for signing by the user. If the user approves and authentication is successful,
a signature is returned to the client in the data field of an account-proof service.

Updates also include improvements to the WalletUtils.encodeAccountProof encoding utility for wallets.

Additional details can be found in the proving-authentication documentation.

import {config} from "@onflow/fcl"

type AccountProofData {
  // e.g. "Awesome App (v0.0)" - A human readable string to identify your application during signing
  appIdentifier: string;  

  // e.g. "75f8587e5bd5f9dcc9909d0dae1f0ac5814458b2ae129620502cb936fde7120a" - minimum 32-byte random nonce as hex string
  nonce: string;          
}

type AccountProofDataResolver = () => Promise<AccountProofData | null>;

config({
  "fcl.accountProof.resolver": accountProofDataResolver
})

🛠 FCL Discovery UI

FCL Discovery has upgraded its default UI for displaying all wallets. This UI will only be used for FCL version 1.0 and higher. Read more about the improvements here.

🛠 Simplify accessing and using currentUser

The current user object can now be accessed without invoking a function. The syntax has been changed from currentUser() to currentUser This simplifies the interface and makes it more intuitive and conformed to the rest of the FCL API. This syntax change is not a breaking change but will likely be deprecated soon.

Examples of the new currentUser functionality.

import {currentUser} from "@onflow/fcl"
currentUser.snapshot()
currentUser.subscribe(callback)

Examples of currentUser as a param.

import {query, currentUser} from "@onflow/fcl"

await query({
  cadence: `
    pub fun main(currentUser: Address): Address {
      return currentUser
    }
  `,
  args: (arg, t) => [currentUser],
})

📖 New Documentation

  • Discovery
    • Added how to use the UI and API versions with the new FCL configurations and settings.
  • Account Proof
    • Updated to reflect new signature format and proper usage.
  • Wallet provider spec for EXT/RPC
    • Added EXT/RPC specification and information
  • Extension Guide
    • Learn how to build an end-to-end non-custodial FCL compatible chrome extension through a guide and example.
Assets 2
Loading