Skip to main content

WalletUtils

Overview​

Namespace containing WalletUtils utilities

Functions​

approve​

Sends an approval response to FCL with the provided data. This indicates that the user has approved the requested operation (authentication, transaction signing, etc.) and includes the resulting data (signatures, account information, etc.).

Sends "FCL:VIEW:RESPONSE". with status "APPROVED".

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.approve(data)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.approve(data)

Usage​


_19
// Approve authentication with account data
_19
import { approve } from "@onflow/fcl"
_19
_19
const accountData = {
_19
f_type: "AuthnResponse",
_19
f_vsn: "1.0.0",
_19
addr: "0x1234567890abcdef",
_19
services: [
_19
{
_19
f_type: "Service",
_19
f_vsn: "1.0.0",
_19
type: "authz",
_19
method: "HTTP/POST",
_19
endpoint: "https://wallet.example.com/authz"
_19
}
_19
]
_19
}
_19
_19
approve(accountData)

Parameters​

data​
  • Type: any
  • Description: The approval data to send back to FCL (signatures, account info, etc.)

Returns​

void

close​

Closes the wallet service window/iframe and notifies FCL that the service is shutting down. This should be called when the user cancels an operation or when the wallet service needs to close itself.

Sends "FCL:VIEW:CLOSE".

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.close()

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.close()

Returns​

void

decline​

Sends a decline response to FCL indicating that the user has rejected or cancelled the requested operation. This should be called when the user explicitly cancels an operation or when an error prevents the operation from completing.

Sends "FCL:VIEW:RESPONSE". with status "DECLINED".

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.decline(reason)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.decline(reason)

Usage​


_10
// Decline when user cancels authentication
_10
import { decline } from "@onflow/fcl"
_10
_10
document.getElementById('cancel-btn').addEventListener('click', () => {
_10
decline("User cancelled authentication")
_10
})

Parameters​

reason​
  • Type: string
  • Description: Human-readable reason for declining the request

Returns​

void

encodeAccountProof​

Encodes account proof data for cryptographic signing on the Flow blockchain. This function creates a standardized message format that combines the application identifier, account address, and nonce into a format suitable for cryptographic signing. The encoded message can then be signed by the account's private key to create an account proof.

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.encodeAccountProof(accountProofData, includeDomainTag)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.encodeAccountProof(accountProofData, includeDomainTag)

Usage​


_11
// Basic account proof encoding
_11
import { encodeAccountProof } from "@onflow/fcl"
_11
_11
const accountProofData = {
_11
address: "0x1234567890abcdef",
_11
nonce: "75f8587e5bd982ec9289c5be1f9426bd12b4c1de9c7a7e4d8c5f9e8b2a7c3f1e9", // 64 hex chars (32 bytes)
_11
appIdentifier: "MyAwesomeApp"
_11
}
_11
_11
const encodedMessage = encodeAccountProof(accountProofData)
_11
console.log("Encoded message:", encodedMessage)

Parameters​

accountProofData​
  • Type:

_10
export interface AccountProofData {
_10
address: string
_10
nonce: string
_10
signatures: CompositeSignature[]
_10
}

includeDomainTag (optional)​
  • Type: boolean
  • Description: Whether to include the FCL domain tag in the encoding

Returns​

string

encodeMessageFromSignable​

Encodes a message from a signable object for a specific signer address.

This function determines whether the signer should sign the transaction payload or envelope based on their role in the transaction (authorizer, proposer, or payer), then encodes the appropriate message for signing.

Payload signers include authorizers and proposers (but not payers) Envelope signers include only payers

The encoded message is what gets signed by the account's private key to create the transaction signature.

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.encodeMessageFromSignable(signable, signerAddress)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.encodeMessageFromSignable(signable, signerAddress)

Usage​


_25
import * as fcl from "@onflow/fcl";
_25
_25
// This function is typically used internally by authorization functions
_25
// when implementing custom wallet connectors or signing flows
_25
_25
const signable = {
_25
voucher: {
_25
cadence: "transaction { prepare(acct: AuthAccount) {} }",
_25
authorizers: ["0x01"],
_25
proposalKey: { address: "0x01", keyId: 0, sequenceNum: 42 },
_25
payer: "0x02",
_25
refBlock: "a1b2c3",
_25
computeLimit: 100,
_25
arguments: [],
_25
payloadSigs: []
_25
}
_25
};
_25
_25
// For an authorizer (payload signer)
_25
const authorizerMessage = fcl.encodeMessageFromSignable(signable, "0x01");
_25
console.log("Authorizer signs:", authorizerMessage);
_25
_25
// For a payer (envelope signer)
_25
const payerMessage = fcl.encodeMessageFromSignable(signable, "0x02");
_25
console.log("Payer signs:", payerMessage);

Parameters​

signable​
  • Type: any
  • Description: The signable object containing transaction data and voucher
signerAddress​
  • Type: any
  • Description: The address of the signer to encode the message for

Returns​


_10
(signable: Signable, signerAddress: string) => string

injectExtService​

Injects an external authentication service into the global FCL extensions array. This function is used by wallet providers to register their authentication services with FCL, making them available for user authentication. The service must be of type "authn" and have a valid endpoint.

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.injectExtService(service)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.injectExtService(service)

Usage​


_10
// Register a wallet authentication service
_10
const walletService = {
_10
type: "authn",
_10
endpoint: "https://example-wallet.com/fcl/authn",
_10
method: "HTTP/POST",
_10
identity: { address: "0x123..." },
_10
provider: { name: "Example Wallet" }
_10
}
_10
fcl.WalletUtils.injectExtService(walletService)

Parameters​

service​
  • Type: Service
  • Description: The authentication service to inject. Must have type "authn" and a valid endpoint

Returns​

void

onMessageFromFCL​

Sets up a message listener to receive messages from the parent FCL application. This function is used by wallet services to listen for specific message types from FCL and respond accordingly. It handles message filtering, data sanitization, and provides context about the message origin for security purposes.

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.onMessageFromFCL(messageType, cb)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.onMessageFromFCL(messageType, cb)

Usage​


_20
// Listen for authentication requests from FCL
_20
import { onMessageFromFCL } from "@onflow/fcl"
_20
_20
const removeListener = onMessageFromFCL("FCL:VIEW:READY:RESPONSE", (data, context) => {
_20
console.log("FCL is ready for communication")
_20
console.log("Message from:", context.origin)
_20
console.log("Ready data:", data)
_20
_20
// Verify origin for security
_20
if (context.origin === "https://myapp.com") {
_20
initializeWalletServices()
_20
} else {
_20
console.warn("Unexpected origin:", context.origin)
_20
}
_20
})
_20
_20
// Stop listening when wallet service closes
_20
window.addEventListener("beforeunload", () => {
_20
removeListener()
_20
})

Parameters​

messageType​
  • Type: string
  • Description: The specific message type to listen for (e.g., "FCL:VIEW:READY:RESPONSE")
cb (optional)​
  • Type:

_10
(data: any, context: { origin: string; }) => void

  • Description: Callback function executed when a matching message is received

Returns​


_10
() => void

ready​

Initiates the communication handshake between a wallet service and FCL. This function listens for the "FCL:VIEW:READY:RESPONSE" message from FCL and automatically sends "FCL:VIEW:READY" to indicate the wallet service is ready to receive requests. This is typically the first function called when a wallet service loads.

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.ready(cb, msg)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.ready(cb, msg)

Usage​


_11
// Basic wallet service initialization
_11
import { ready } from "@onflow/fcl"
_11
_11
ready((data, context) => {
_11
console.log("FCL is ready to communicate")
_11
console.log("FCL origin:", context.origin)
_11
console.log("Ready data:", data)
_11
_11
// Wallet service is now ready to handle authentication requests
_11
initializeWalletUI()
_11
})

Parameters​

cb​
  • Type:

_10
(data: any, context: { origin: string; }) => void

  • Description: Callback function executed when FCL responds with ready confirmation
msg (optional)​
  • Type:

_10
export interface PollingResponse {
_10
f_type: "PollingResponse"
_10
f_vsn: "1.0.0"
_10
status: "APPROVED" | "DECLINED" | "REDIRECT"
_10
reason: string | null
_10
data: any
_10
}

  • Description: Optional message payload to include with ready signal

Returns​

void

redirect​

Sends a redirect response to FCL indicating that the operation requires a redirect to complete. This is used when the wallet service needs to redirect the user to another URL (such as a native app deep link or external service).

Sends "FCL:VIEW:RESPONSE". with status "REDIRECT".

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.redirect(data)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.redirect(data)

Usage​


_10
// Redirect to native wallet app
_10
import { redirect } from "@onflow/fcl"
_10
_10
redirect({
_10
f_type: "RedirectResponse",
_10
f_vsn: "1.0.0",
_10
url: "flow-wallet://sign?transaction=abc123",
_10
callback: "https://myapp.com/callback"
_10
})

Parameters​

data​
  • Type: any
  • Description: Redirect data containing the target URL and any additional parameters

Returns​

void

sendMsgToFCL​

Sends messages from a wallet or service back to the parent FCL application. This function handles communication between wallet UIs (running in iframes, popups, or redirects) and the main FCL application. It automatically detects the communication method (redirect, iframe, or popup) and sends the message accordingly.

Import​

You can import the entire package and access the function:


_10
import * as fcl from "@onflow/fcl-core"
_10
_10
fcl.WalletUtils.sendMsgToFCL(type, msg)

Or import the namespace directly:


_10
import { WalletUtils } from "@onflow/fcl-core"
_10
_10
WalletUtils.sendMsgToFCL(type, msg)

Usage​


_10
// Send approval response with signature data
_10
import { sendMsgToFCL } from "@onflow/fcl"
_10
_10
sendMsgToFCL("FCL:VIEW:RESPONSE", {
_10
f_type: "CompositeSignature",
_10
f_vsn: "1.0.0",
_10
addr: "0x1234567890abcdef",
_10
keyId: 0,
_10
signature: "abc123..."
_10
})

Parameters​

type​
  • Type: string
  • Description: The message type identifier (e.g., "FCL:VIEW:RESPONSE", "FCL:VIEW:READY")
msg (optional)​
  • Type:

_10
export interface PollingResponse {
_10
f_type: "PollingResponse"
_10
f_vsn: "1.0.0"
_10
status: "APPROVED" | "DECLINED" | "REDIRECT"
_10
reason: string | null
_10
data: any
_10
}

  • Description: Optional message payload containing response data

Returns​

void

Rate this page