Sign In With Ethereum

AppKit provides a simple solution for integrating with "Sign In With Ethereum" (SIWE), a form of authentication that enables users to control their digital identity with their Ethereum account. SIWE is a standard also known as EIP-4361.

One-Click Auth

One-Click Auth represents a key advancement within WalletConnect v2, streamlining the user authentication process in AppKit by enabling them to seamlessly connect with a wallet and sign a SIWE message with just one click. Connecting a wallet, proving control of an address with an off-chain signature, authorizing specific actions. These are the kinds of authorizations that can be encoded as "ReCaps". ReCaps are permissions for a specific website or dapp that can be compactly encoded as a long string in the message you sign and translated by any wallet into a straight-forward one-sentence summary. WalletConnect uses permissions expressed as ReCaps to enable a One-Click Authentication.

Configure your AppKit Client

To integrate SIWE with AppKit, you need to configure your AppKit client using Modal.Model.AuthPayloadParams, which are required to create a SIWE message for the user to sign:

 AppKit.setAuthRequestParams(authPayloadParams)

Example of AuthRequestParams

 val authParams = Modal.Model.AuthPayloadParams(
    chains = ["eip155:1", "eip155:137"],
    domain = "yourDappDomain.com",
    uri = "https://yourDappDomain.com/login",
    nonce = //uniqueNonce,
    statement = "I accept the Terms of Service: https://yourDappDomain.com/",
    methods = ["personal_sign", "eth_sendTransaction"],
    resources = null //// Here your dapp may request authorization with ReCaps
)

Configuring your AppKit client with Modal.Model.AuthPayloadParams will prioritize authentication requests over regular session proposals. If the wallet supports One-Click Auth, the session will be created and the user will automatically authenticate without needing to send another SIWE request over personal_sign. If the wallet does not support One-Click Auth, it will fall back to the session proposal. In this case, to authenticate the user, AppKit will send another session request to prove address ownership.

To check whether the user has signed a SIWE message, check onSessionAuthenticateResponse callback from AppKit.ModalDelegate:

fun onSessionAuthenticateResponse(response: Modal.Model.SessionAuthenticateResponse) {
    // Triggered when Dapp receives the session authenticate response from wallet

    if (response is Modal.Model.SessionAuthenticateResponse.Result) {
        if (response.session != null) {
            // Authentication successful, session established
        } else {
            // Authentication successful, but no session created (SIWE-only flow)
        }
    } else {
        // Authentication request was rejected or failed
    }
}

Fallback to SIWE Over Session Request

If the wallet connecting to your dapp does not support One-Click Auth, the SDK will fallback to the wc_sessionPropose method and create a session with the wallet. AppKit will then inform the user that they need to sign a message to prove address ownership. AppKit will send a SIWE request to the wallet, and once the wallet responds with a signed message, use onSIWEAuthenticationResponse callback to check the result:

 override fun onSIWEAuthenticationResponse(response: Modal.Model.SIWEAuthenticateResponse) {
    if (response is Modal.Model.SIWEAuthenticateResponse.Result) {
        // message and signature
    } else {
        //error
    }
}

Link Mode

The latest release of AppKit supports link mode, a low latency mechanism for transporting One-Click Auth requests and session requests over universal links, reducing the need for a WebSocket connection with the Relay. This significantly enhances the user experience when connecting native dApps to native wallets by reducing the latency associated with networking connections, especially when the user has an unstable internet connection.

To support link mode, configure your AppMetaData appLink with a valid universal link and set the linkMode property to true:

 val appMetaData = Core.Model.AppMetaData(
    ...
    appLink = "https://example.com/example_dapp",
    linkMode = true
)

CoreClient.initialize(
   metaData: appMetaData,
    ...
)

AppKit.initialize(Modal.Params.Init(core = CoreClient))

Once link mode is configured, your dApp will connect and send requests to wallets via app links after receiving proof from the wallet that it also supports link mode.

The wallet will also send responses using app links. Your app needs to pass these responses to the AppKit client so it can process them.

AppKit.handleDeepLink(url) { error -> 
    //handle error

}

Ensure to handle incoming app links in your Activity onCreate method and in onNewIntent callback.

Ensure that your App Link is properly configured in your app's Manifest file with the autoVerify set to true:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" android:host="your_host" />
</intent-filter>

For more information on how to configure app links for your app, refer to the Android Documentation.

For enabling links to app content check this documentation page.

For more information on how to interact with other apps using intents, see Android Intent Documentation.