Migration Guide from v3 to v4 for Web3Auth PnP Flutter SDK

Overview

This migration guide provides steps for upgrading from version 3(v3) to version 4(v4) of the Web3Auth PnP Flutter SDK. The guide outlines significant changes and enhancements, including the introduction of enableMFA method to initiate MFA setup flow, request method for transaction confirmation screens, launchWalletServices method for template wallet interface, updates to the Provider and the TypeOfLogin enum.

Changes in Detail

setResultUrl is now removed

With the new v4 update, there's a breaking change with the removal of the setResultUrl method, which was used to trigger the user UserCancelledException on Android.

From v4, developers won't be able to use the setResultUrl method.

enableMFA method

From v4, developers can now use the enableMFA method to initiate MFA setup flow for already logged in users.

Default Verifier

Usage

try {
  await Web3AuthFlutter.enableMFA();
} on UserCancelledException {
  log("User cancelled.");
} catch(e) {
  log("Unknown exception occurred");
}

Custom JWT Verifier

Usage

try {
    final loginParams = LoginParams(
        loginProvider: Provider.jwt,
        extraLoginOptions: ExtraLoginOptions(
            id_token: "YOUR_JWT_TOKEN",
        ),
    );

    await Web3AuthFlutter.enableMFA(loginParams);

} on UserCancelledException {
  log("User cancelled.");
} catch(e) {
    log("Unknown exceptionoccurred");
}

launchWalletServices method

From v4, developers can use the launchWalletServices to launches a WebView which allows them to use the templated wallet UI services. Developers can pass the ChainConfig to launch wallet services with a specific chain selected.

note

Access to Wallet Services is gated. You can use this feature in sapphire_devnet for free. The minimum pricing plan to use this feature in a production environment is the Scale Plan.

ChainConfig Arguments

Parameter	Description
chainNamespace	Custom configuration for your preferred blockchain. As of now only EVM supported. Default value is ChainNamespace.eip155.
decimals?	Number of decimals for the currency ticker. Default value is 18, and accepts int as value.
blockExplorerUrl?	Blockchain's explorer URL. (eg: https://etherscan.io)
chainId	The chain id of the selected blockchain in hex String.
displayName?	Display Name for the chain.
logo?	Logo for the selected chainNamespace & chainId.
rpcTarget	RPC Target URL for the selected chainNamespace & chainId.
ticker?	Default currency ticker of the network (e.g: ETH)
tickerName?	Name for currency ticker (e.g: Ethereum)

Usage

Usage

try {
  await Web3AuthFlutter.launchWalletServices(
    ChainConfig(
      chainId: "0x1",
      rpcTarget: "https://mainnet.infura.io/v3/$key",
    ),
  );
} on UserCancelledException {
  log("User cancelled.");
} catch(e) {
  log("Unknown exception occurred");
}

request method

Now, developers can use the request method to use the templated transaction confirmation screens for signing transactions. To retrive the signature for the request, developers can use the getSignResponse static method.

Usage

try {
  List<dynamic> params = [];
  // Message to be signed
  params.add("Hello, Web3Auth from Flutter!");
  // User's EOA address
  params.add("<User Address in Hex>");

  await Web3AuthFlutter.request(
    ChainConfig(
      chainId: "0x1",
      rpcTarget: "https://mainnet.infura.io/v3/$key",
    ),
    "personal_sign",
    params,
  );
} on UserCancelledException {
  log("User cancelled.");
} catch(e) {
  log("Unknown exception occurred");
}

final signResponse = await Web3AuthFlutter.getSignResponse();
log(signResponse.toString())

New Login Providers

v4 update brings two new providers. Now developers can use the SMS Passwordless and Farcaster login options.

SMS Passwordless

Usage

Future<void> initWeb3Auth() async {
  Uri redirectUrl;
  if (Platform.isAndroid) {
    redirectUrl = Uri.parse('{SCHEME}://{HOST}/auth');
    // w3a://com.example.w3aflutter/auth
  } else if (Platform.isIOS) {
    redirectUrl = Uri.parse('{bundleId}://auth');
    // com.example.w3aflutter://openlogin
  } else {
    throw UnKnownException('Unknown platform');
  }

  await Web3AuthFlutter.init(
    Web3AuthOptions(
      clientId: "WEB3AUTH_CLIENT_ID",
      network: Network.sapphire_mainnet,
      redirectUrl: redirectUrl,
    ),
  );
}

// Login
final Web3AuthResponse response = await Web3AuthFlutter.login(
  LoginParams(loginProvider: Provider.sms_passwordless,
    extraLoginOptions: ExtraLoginOptions(
      // The phone number should be in format of +{country_code}-{phone_number}
      login_hint: "+91-9911223311",
    ),
  ),
);

Farcaster

Usage

final Web3AuthResponse response = await Web3AuthFlutter.login(
  LoginParams(loginProvider: Provider.farcaster)
);