@starknet-foundation/starkex-auth

@starknet-foundation/starkex-auth

A React component for authenticating with StarkEx applications.

Installation

First, create a new React app:

npx create-react-app my-react-app

or with Vite:

npx init vite@latest my-react-app --template react

Then, install the package in your project directory:

With Yarn:

yarn add @starknet-foundation/starkex-auth

With pnpm:

pnpm add @starknet-foundation/starkex-auth

With npm:

npm install @starknet-foundation/starkex-auth

Usage

There are 2 types of authentication flow components: StarkExWalletAuth and StarkExBasicAuth.

StarkExWalletAuth - This flow is used when the user is signing in with a StarkEx wallet.

StarkExBasicAuth - This flow is used when the user is signing in with a username and password.

StarkExWalletAuth

import {StarkExClientApp, StarkExWalletAuth} from '@starknet-foundation/starkex-auth';

function WalletApp() {
  return (
    <StarkExWalletAuth
      onConnectWalletClick={() => {
        // Show wallet modal
      }}
    />
  );
}

Props

import {StarkExClientApp, StarkExWalletAuth} from '@starknet-foundation/starkex-auth';

function App() {
  return (
    <StarkExWalletAuth
      connectWalletText="Click me"
      connectWalletProps={{isDisabled: true, isLoading: false}}
      onConnectWalletClick={() => {
        // Show wallet modal
      }}
    />
  );
}

onConnectWalletClick: () => void - Function that is called when the user clicks the connect wallet button.

connectWalletText: string - The text that is displayed on the connect wallet button.

connectWalletProps: ButtonProps - Possible props to pass to the connect wallet button.

See Here for a full list of props.

StarkExBasicAuth

import {StarkExBasicAuth, StarkExClientApp} from '@starknet-foundation/starkex-auth';

function BasicApp() {
  return (
    <StarkExBasicAuth
      onSignInClick={() => {
        // Sign in logic here
      }}
    />
  );
}

Props

import {StarkExBasicAuth, StarkExClientApp} from '@starknet-foundation/starkex-auth';

function App() {
  return (
    <StarkExBasicAuth
      usernameLabel="Email"
      usernamePlaceholder="Enter your email"
      usernameError={false}
      usernameErrorMsg="Email is invalid"
      onUsernameChange={username => {
        // Username change logic here
      }}
      passwordLabel="Password"
      passwordPlaceholder="Enter your password"
      passwordError={false}
      passwordErrorMsg="Password is invalid"
      onPasswordChange={password => {
        // Password change logic here
      }}
      forgotPasswordLabel="Forgot password?"
      onForgotPasswordClick={username => {
        // Forgot password logic here
      }}
      signInLabel="Sign In"
      onSignInClick={async (username, password) => {
        // Sign in logic here
      }}
    />
  );
}

onSignInClick: (username: string, password: string) => void - Function that is called when the user clicks the sign in button.

See Here for a full list of props.

StarkExAuthProvider

The StarkExAuthProvider component is a React Context Provider that provides the StarkExAuthContext to all of its children. Use the hook useStarkExAuthContext() to access the context.

import {
  StarkExAuthProvider,
  StarkExClientApp,
  StarkExWalletAuth,
  useStarkExAuthContext
} from '@starknet-foundation/starkex-auth';

function App() {
  return (
    <StarkExAuthProvider appId={StarkExClientApp.RHINO} redirectUrl="https://provisions-portal.com">
      ...
    </StarkExAuthProvider>
  );
}

Props

appId - The StarkEx application ID. This is used to identify the application that the user is signing in to. Possible values are:

export enum StarkExClientApp {
  IMMUTABLE = 'immutablex',
  DYDX = 'dydx',
  SORARE = 'sorare',
  RHINO = 'rhinofi'
}

redirectUrl - The URL that the user will be redirected to after signing in. As a rule of thumb, this URL should be the Starknet Provisions website. Please contact us to receive the correct URL based on the environment. For testing purposes, you can use any URL.

Example for using StarkExAuthProvider with StarkExWalletAuth:

• Import the StarkExAuthProvidercomponent and wrap your app with it.
• Import the StarkExWalletAuth component and add it to your app.

import {
  StarkExAuthProvider,
  StarkExClientApp,
  StarkExWalletAuth,
  useStarkExAuthContext
} from '@starknet-foundation/starkex-auth';

function App() {
  return (
    <StarkExAuthProvider appId={StarkExClientApp.RHINO} redirectUrl="https://provisions-portal.com">
      <WalletApp />
    </StarkExAuthProvider>
  );
}

function WalletApp() {
  const {sigParams, redirect} = useStarkExAuthContext();
  const [account, setAccount] = useState('');

  // After the user connects their wallet
  useEffect(() => {
    async function signAndRedirect() {
      let sig = null;
      // Get stark key from wallet
      const starkKey = await getStarkKeyFromWallet();
      if (Array.isArray(sigParams)) {
        // Sign stark key with message params
        sig = await sign(starkKey, sigParams);
      }
      // Redirect to provisions website
      redirect({starkKey, identity: account, sig});
    }

    if (account) {
      signAndRedirect();
    }
  }, [account]);

  return (
    <StarkExWalletAuth
      onConnectWalletClick={() => {
        // Show wallet modal
      }}
    />
  );
}

Example for using StarkExAuthProvider with StarkExBasicAuth:

• Import the StarkExAuthProvidercomponent and wrap your app with it.
• Import the StarkExBasicAuth component and add it to your app.

import {
  StarkExAuthProvider,
  StarkExBasicAuth,
  StarkExClientApp,
  useStarkExAuthContext
} from '@starknet-foundation/starkex-auth';

function App() {
  return (
    <StarkExAuthProvider
      appId={StarkExClientApp.SORARE}
      redirectUrl="https://provisions-portal.com"
    >
      <BasicApp />
    </StarkExAuthProvider>
  );
}

function BasicApp() {
  const {sigParams, redirect} = useStarkExAuthContext();

  return (
    <StarkExBasicAuth
      onSignInClick={async (username, password) => {
        let sig = null;
        // Get stark key from wallet
        const starkKey = await getStarkKey(username, password);
        if (Array.isArray(sigParams)) {
          // Sign stark key with message params
          sig = await sign(starkKey, sigParams);
        }
        // Redirect to provisions website
        redirect({starkKey, identity: username, sig});
      }}
    />
  );
}

Note: You must use useStarkExAuthContext inside a nested component of StarkExAuthProvider for it to work.

Signature parameters

Usage

import {useStarkExAuthContext} from '@starknet-foundation/starkex-auth';

function MyComponent() {
  const {sigParams} = useStarkExAuthContext();

  return (
    <div>
      <pre>Signature params: {sigParams}</pre>
    </div>
  );
}

sigParams

The sigParams array contains the parameters that you need to sign with the user's stark key. It contains the address of the Starknet account that the user is signing in with to the Provisions portal and the contract ID which is the contract that the user will claim his tokens from. Both of these parameters are passed from the Provisions portal as query params (recipient and contract_id) and read and parsed automatically. To test this, you can add ?recipient=0x28c70549121&contract_id=0xbc614e to the URL when you are building your auth page.

Note: The sigParams may be null if the starknet_address QS is not passed from the Provisions portal. This can happen if the user is not signed in to the Provisions portal and only wants to do eligibility check.

Redirect handler

Usage

import {useStarkExAuthContext} from '@starknet-foundation/starkex-auth';

function MyComponent() {
  const {redirect} = useStarkExAuthContext();

  useEffect(() => {
    redirect({
      starkKey: '0x...',
      sig: {r: '0x...', s: '0x...'},
      identity: 'username'
    });
  }, []);

  return (
    <div>
      <p>Redirecting...</p>
    </div>
  );
}

redirect({starkKey, identity, sig})

The redirect function is a function that you can call to redirect the user to the Provisions website. It takes an object with the following properties:

• starkKey - The stark public key of the user.
• identity - The identity of the user. This can be the username/email/ethereum address or any other identifier.
• sig (optional) - The approval signature result for the stark key and the Starknet address of the user.

Children components

You can also add children components to the different auth components.

Usage

import {StarkExBasicAuth, StarkExWalletAuth} from '@starknet-foundation/starkex-auth';

function BasicApp() {
  return (
    <StarkExBasicAuth>
      <div>
        <p>Some text</p>
      </div>
    </StarkExBasicAuth>
  );
}

function WalletApp() {
  return (
    <StarkExWalletAuth>
      <div>
        <p>Some text</p>
      </div>
    </StarkExWalletAuth>
  );
}