Sismo Docs
  • Welcome to Sismo
    • What is Sismo?
  • Build with Sismo Connect
    • Overview
    • Installation
    • Sismo Connect Cheatsheet
    • Tutorials
      • Get Your appId - Create a Sismo Connect App
      • Onchain Tutorial (1/2): Code Your Airdrop Contract With Privately-Aggregated Data
      • Onchain Tutorial (2/2): Deploy Your Airdrop Contract
    • Technical Documentation
      • Sismo Connect Configuration
      • Auths
      • Claims
      • Signature
      • Packages
        • Sismo Connect Client: Request
        • Sismo Connect React: Request
        • Sismo Connect Server: Verify Offchain
        • Sismo Connect Solidity Library: Verify Onchain
    • FAQ
  • Data Groups
    • Overview
    • Tutorials
      • Factory Guide: Create a Data Group in 5 Minutes
      • Sismo Hub Guide: Create Data Groups Programmatically
      • Sismo Hub Guide: Add a Data Provider to the Sismo Factory
    • Sismo Hub
      • Sismo Hub Repository
        • Group Generators
        • Data Providers
        • Data Operators
        • Command Line Interface
      • Accounts Registry Tree
  • Data Vault
    • Overview
    • Vault Identifiers
    • Proving Schemes
      • Hydra-S1
      • Hydra-S2
    • Commitment Mapper
  • Resources
    • Deployed Contract Addresses
    • Sismo API
      • API Links
      • Query From a Client
      • Group
        • Get groups
        • Get group snapshots
      • Common Parameters
      • Advanced Filtering
      • Transaction
  • Links
    • Sismo Landing Page
    • Sismo Factory
    • Sismo App Store
    • Sismo Builder Resources
    • GitHub
    • Discord
    • Twitter
    • Blog
Powered by GitBook
On this page
  • Type definitions
  • Integrations
  • Making an AuthRequest - Front-end integration
  • Verifying an AuthRequest
  1. Build with Sismo Connect
  2. Technical Documentation

Auths

Sismo Connect can be used to authenticate a user from multiple sources, either from web2 or web3.

Type definitions

The AuthRequest is an object with the following properties:

  • AuthType (required): defines the type of authentication required. The following authType are currently supported:

    • VAULT: Sismo Connect returns the user's vaultId for the application that requested it. It is a deterministic anonymous identifier (hash(userVaultSecret, AppId, ..)) See more information about Vault Identifiers here.

    • GITHUB: Sismo Connect returns the user's GitHub account id.

    • TWITTER Sismo Connect returns the user's Twitter account id.

    • EVM_ACCOUNT: Sismo Connect returns the user's Ethereum address.

    • TELEGRAM : Sismo Connect returns the user's Telegram account id.

  • userId (optional): requests the user to have a predefined account.

  • isOptional(optional): by default set to false. Allows the user to optionally authenticate with this AuthType.

// Types (typescript version)
enum AuthType {
    VAULT = 0,
    GITHUB = 1,
    TWITTER = 2,
    EVM_ACCOUNT = 3,
    TELEGRAM = 4,
}

type AuthRequest = {
    authType: AuthType;
    userId?: string;
    isOptional?: boolean;
};

Integrations

Authentication requests are made in the front end using either the sismo-connect-react package or the sismo-connect-client package. Requests are then verified either in a back end using the sismo-connect-server package or in a smart contract using the sismo-connect-solidity package.

Making an AuthRequest - Front-end integration

Making an AuthRequest is only possible in the front end as the request redirects users to the Sismo Data Vault app, where users can generate a zero-knowledge proof.

The SismoConnectButton React component is available from the sismo-connect-react package. It is a wrapper of the sismo-connect-client package.

  • AuthRequests are passed as props of the SismoConnectButton either through:

    1. the auth props for one authentication request: AuthRequest or,

    2. the auths props for several authentication requests: AuthRequest[]

  • Responses are received through either:

    1. the onResponse: (response: SismoConnectResponse) => void callback for offchain verification or,

    2. the onResponseBytes (response: string) => void callback for onchain verification.

One AuthRequest - code example

app.tsx
import { SismoConnectButton, AuthType, SismoConnectClientConfig, SismoConnectResponse } from "@sismo-core/sismo-connect-react";

<SismoConnectButton 
    // the client config created
    config={config}
    // request a proof of account ownership 
    // (here Vault ownership)
    auth={{authType: AuthType.VAULT}}
    onResponse={async (response: SismoConnectResponse) => {
	//Send the response to your server to verify it
	//thanks to the @sismo-core/sismo-connect-server package
    }}
    onResponseBytes={async (bytes: string) => {
        //Send the response to your contract to verify it
        //thanks to the @sismo-core/sismo-connect-solidity package
    }}
/>

Multiple AuthRequests - code example

app.tsx
// You can also create several auth requests 
// in the same button
import { SismoConnectButton, AuthType, SismoConnectClientConfig, SismoConnectResponse } from "@sismo-core/sismo-connect-react";

<SismoConnectButton 
    config={config}
    // request multiple proofs of account ownership 
    // (here Vault ownership and Twitter account ownership)
    auths={[
        {authType: AuthType.VAULT},
        {authType: AuthType.TWITTER},
    ]}
    onResponse={async (response: SismoConnectResponse) => {
	//Send the response to your server to verify it
	//thanks to the @sismo-core/sismo-connect-server package
    }}
    onResponseBytes={async (bytes: string) => {
        //Send the response to your contract to verify it
        //thanks to the @sismo-core/sismo-connect-solidity package
    }}
/>

The useSismoConnect hook is available from the sismo-connect-react package. It is a wrapper of the sismo-connect-client package. The useSismoConnect hook exposes the sismoConnect variable.

  • One or multiple AuthRequests can be made using the sismoConnect.request() method available on the sismoConnect variable.

  • The response could be received through either:

    1. the sismoConnect.getResponse() method for offchain verification or,

    2. the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

App.tsx
import { useSismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-react";

const { sismoConnect } = useSismoConnect({ config });

// Making the request a proof of account ownership 
// (here Vault ownership)
function onClick(){
  sismoConnect.request({
      auth: {authType: AuthType.VAULT}
    });
}

// Proofs are available in two differents types depending on usage (offchain or onchaon verification)
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

Multiple AuthRequests - code example

App.tsx
import { useSismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-react";

const { sismoConnect } = useSismoConnect({ config });

// Making the request for multiple proofs of account ownership 
// (here Vault ownership and Twitter account ownership)
function onClick(){
  sismoConnect.request({
      auths: [
      {authType: AuthType.VAULT},
      {authType: AuthType.TWITTER},
      ]   
    });
}

// Proofs are available in two differents types depending on usage (offchain or onchaon verification)
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

The sismo-connect-client package exposes a SismoConnect variable.

  • One or multiple AuthRequests can be made using the sismoConnect.request() method available on a SismoConnect instance.

  • The response could be received through either:

    1. the sismoConnect.getResponse() method for offchain verification or,

    2. the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

app.ts
import { SismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-client";

const sismoConnect = SismoConnect({config});

// Making the request a proof of account ownership 
// (here Vault ownership)
function onClick(){
  sismoConnect.request({
      auth: {authType: AuthType.VAULT}
    });
}

// Receive the proofs in two different formats
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

Multiple AuthRequests - code example

app.ts
import { SismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-client";

const sismoConnect = SismoConnect({config});

// Making the request for multiple proofs of account ownership 
// (here Vault ownership and Twitter account ownership)
function onClick(){
  sismoConnect.request({
      auths: [
      {authType: AuthType.VAULT},
      {authType: AuthType.TWITTER},
      ]   
    });
}

// Receive the proofs in two different formats
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

Verifying an AuthRequest

Once a user has generated a ZKP on the Data Vault app, your application must verify it. This can be achieved in onchain smart contracts or offchain back ends.

The sismo-connect-server package exposes a SismoConnect variable.

One or multiple AuthRequests can be verified offchain on a backend server using the sismoConnect.verify() method available on a SismoConnect instance.

  • If the proof is valid sismoConnect.verify() returns a result of type SismoConnectVerifiedResult else it will throw an error,

  • the result.getUserId() can be called as shown below to get the userId of the corresponding type.

One AuthRequest - code example

import { SismoConnect, SismoConnectVerifiedResult, AuthType } from "@sismo-core/sismo-connect-server";

const sismoConnect = SismoConnect({config});

async function verifyResponse(sismoConnectResponse: SismoConnectResponse) {
  // verifies the proofs contained in the sismoConnectResponse
  // with respect to the different auths
  // i.e. user prove they own a Vault
  const result: SismoConnectVerifiedResult = await sismoConnect.verify(
    sismoConnectResponse,
    {
      // proofs in the sismoConnectResponse should be valid
      // with respect to a Vault ownership
      auth: { authType: AuthType.VAULT },
    }
  )

  // vaultId = hash(userVaultSecret, appId).
  // the vaultId is an app-specific, anonymous identifier of a vault
  const vaultId = result.getUserId(AuthType.VAULT)
}

If you are using Nextjs, you will need to add this config in the next.config.js file to be able to verify the proof. You can find more information here.

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ["@sismo-core/sismo-connect-server"],
  },
}

module.exports = nextConfig

Multiple AuthRequests - code example

import { SismoConnect, SismoConnectVerifiedResult, AuthType } from "@sismo-core/sismo-connect-server";

const sismoConnect = SismoConnect({config});

async function verifyResponse(sismoConnectResponse: SismoConnectResponse) {
  // verifies the proofs contained in the sismoConnectResponse
  // with respect to the different auths
  // i.e. user prove they own a Vault, a Twitter account
  const result: SismoConnectVerifiedResult = await sismoConnect.verify(
    sismoConnectResponse,
    {
      // proofs in the sismoConnectResponse should be valid
      // with respect to a Vault and Twitter account ownership
      auths: [
        { authType: AuthType.VAULT }, 
        { authType: AuthType.TWITTER }
      ],
    }
  )

  // vaultId = hash(userVaultSecret, appId).
  // the vaultId is an app-specific, anonymous identifier of a vault
  const vaultId = result.getUserId(AuthType.VAULT)
  // you can also get the twitterId of the user
  const twitterId = result.getUserId(AuthType.TWITTER)
}

The sismo-connect-solidity package exposes a Sismo Connect Library, which can be inherited by your contract either using Foundry or Hardhat.

The Sismo Connect Library exposes:

  • a verify() function, which allows you to verify a proof generated by the Sismo Vault app with respect to some requests directly in your contract. The verify() function takes an object containing:

    1. a responseBytes send from the front end,

    2. an auth or auths corresponding to the authentification request made in the front end.

  • a buildAuth() helper to recreate the AuthRequest made in the front-end

  • a SismoConnectHelper.getUserId() helper to retrieve the userId of the corresponding type once the proof has been verified.

One AuthRequest - code example

contract MyContract is SismoConnect { // inherits from Sismo Connect library
 
// call SismoConnect constructor with your appId
constructor(bytes16 appId) SismoConnect(buildConfig(appId)) {}

    function doSomethingUsingSismoConnect(bytes memory sismoConnectResponse) public {    
        SismoConnectVerifiedResult memory result = verify({
            responseBytes: sismoConnectResponse,
            // we want users to prove that they own a Sismo Vault
            // we are recreating the auth request made in the frontend to be sure that 
            // the proof provided in the response is valid with respect to this auth request
            auth: buildAuth({authType: AuthType.VAULT}),       
        });
    
        // if the proofs is valid, we can take the userId from the verified result
        // in this case the userId is the vaultId (since we used AuthType.VAULT in the auth request) 
        // it is the anonymous identifier of a user's vault for a specific app 
        // --> vaultId = hash(userVaultSecret, appId)
        uint256 vaultId = SismoConnectHelper.getUserId(result, AuthType.VAULT);
        
        // do something with this vaultId for example
    }
}

Multiple AuthRequests - code example

contract MyContract is SismoConnect { // inherits from Sismo Connect library
 
// call SismoConnect constructor with your appId
constructor(bytes16 appId) SismoConnect(buildConfig(appId)) {}

    function doSomethingUsingSismoConnect(bytes memory sismoConnectResponse) public {    
        // we want users to prove that they own a Sismo Vault and a Twitter Id
        // we are recreating the auth request made in the frontend to be sure that 
        // the proof provided in the response is valid with respect to this auth request
        
        AuthRequest[] memory auths = new AuthRequest[](2);
        auths[0] = buildAuth({authType: AuthType.VAULT})
        auths[1] = buildAuth({authType: AuthType.TWITTER})
        
        SismoConnectVerifiedResult memory result = verify({
            responseBytes: sismoConnectResponse,
            auths: auths,       
        });
        
        // --> vaultId = hash(userVaultSecret, appId)
        uint256 vaultId = SismoConnectHelper.getUserId(result, AuthType.VAULT);
        uint256 twitterId = SismoConnectHelper.getUserId(result, AuthType.TWITTER);     
        
        // do something with this vaultId and the twitterID
    }
}
PreviousSismo Connect ConfigurationNextClaims

Last updated 1 year ago