Sismo Resources
📃

Cheatsheet: Build Your Sismo Connect Request

This tutorial explains how to customize your Sismo Connect request within your app template.

Template Cheatsheets:

📃
Cheatsheet: zkForm Template
📃
Cheatsheet: zkDrop Template
📃
Cheatsheet: zkTelegramBot Template

🙇🏼
Contact us if you need help creating your Pull Request: 👉  Telegram | Discord | App Request form

Pre-requisites

‣

Full Request Object with all Options (Cheatsheet)

This is an example of a request that uses all features of Sismo Connect. You can delete those that you do not need and update with your appId and groupIds. Here is what it will look like to users:

sismoConnectRequest: {
	// 	// Add your appId here
	appId: "{{ auto-fill }}", // Your Sismo Connect Application will be automatically created based on your application metadata
	auths={[
      // request users to share an ethereum wallet
      { authType: AuthType.EVM_ACCOUNT,  isOptional: false }, // delete if not needed
      // request users to share their github account
      { authType: AuthType.GITHUB,  isOptional: false }, // delete if not needed
      // propose users to share their twitter account
      { authType: AuthType.TWITTER, isOptional: true }, // delete if not needed
      // propose users to share their telegram account
      { authType: AuthType.TELEGRAM, isOptional: true }, // delete if not needed
    ]}
    // Claims = request users to create a ZK Proof that they are part of a group
    // and make claims about their value in the group 
    // group example: Stand with Crypto NFT Minters
		// Data Group where value for each user = number of minted token
    // https://sismo-prod-hub-data.s3.eu-west-1.amazonaws.com/group-snapshot-store/0xfae674b6cba3ff2f8ce2114defb200b1/1688203882.json
    // try this demo app to understand: https://demo.apps.sismo.io/aave-chan-initiative/aci-swag
    // users prove they are part of the group of DAO delegators.
    claims={[
      {
        // Stand with Crypto NFT Minters
				// Data Group where value for each user = number of minted token
        // https://sismo-prod-hub-data.s3.eu-west-1.amazonaws.com/group-snapshot-store/0xfae674b6cba3ff2f8ce2114defb200b1/1688203882.json
				// request users just to be part of the group, no matter their value
        groupId: "0xfae674b6cba3ff2f8ce2114defb200b1", // replace with your groupId
      },
      {
        // Gitcoin Passport Holders 
				// Data Group where value for each user = sybil-resistance score
        // https://sismo-prod-hub-data.s3.eu-west-1.amazonaws.com/group-snapshot-store/0x1cde61966decb8600dfd0749bd371f12/1688218897.json
        // Request users part of the group with value >= 15
        groupId: "0x1cde61966decb8600dfd0749bd371f12",  // replace with your groupId
        claimType: ClaimType.GTE, // a member of the group with the value greater or equal to 15
        value: 15,
      },
      {
        // Stand with Crypto NFT Minters
				// Request users part of the group with value = 10
        groupId: "0xfae674b6cba3ff2f8ce2114defb200b1",  // replace with your groupId
        claimType: ClaimType.EQ, // a member of the group with the value equal to 10, example: dhadrien.sismo.eth minted 10
        value: 10,
      },
      {
        // Gitcoin Passport Holders Data Group
				// Request users part of the group with value = 15
        groupId: "0x1cde61966decb8600dfd0749bd371f12",
        claimType: ClaimType.EQ, // a member of the group with the value == 15
        value: 15, 
        isSelectableByUser: true, // can selectively discloe more if user wants
        isOptional: true,
      },
      {
        // Stand with Crypto NFT Minter Holders
				// Request users to choose what value to reveal
        groupId: "0xfae674b6cba3ff2f8ce2114defb200b1",
        claimType: ClaimType.GTE, // member of the group
        isSelectableByUser: true, // user can selectively disclose more if they want
        isOptional: true, // user can choose not to reveal
      },
      {
        // Gitcoin Passport Holders, 
        // Request users > 25, they can reveal more than that if they want
        groupId: "0x1cde61966decb8600dfd0749bd371f12",
        claimType: ClaimType.GTE, // a member of the group with the value greater or equal to 5
        value: 25,
        isSelectableByUser: true, // user can selectively discloe more if they want
      },
			// we ask the user to sign a message, they can update it
	    signature={{message: "I love Sismo!", isSelectableByUser: true}}
    ]}
}
‣

The Request Object explained step by step

The main part of any Sismo Connect Application is the Request object since it contains all the information that we want our users to prove and/or granularly share with the application.

For instance we can request:

  • Account Ids (web2 like GitHub, Twitter, or web3 like Ethereum address) with authRequests
  • Group Membership Proof with claimRequests
  • Signatures to arbitrary messages with signature

A typical Sismo Connect Request looks like this:

sismoConnectRequest: {
	// Replace with your appId here
	appId: "0x02bcb449a6bd1062017cf0315375afdf",
  authRequests: [{ authType: AuthType.VAULT }],
  claimRequests: [
	  {
			// aave-chan
	    groupId: "0xf0285dcfe412b24a6ac9a1c365b7b35d",
    },
  ],
	signature: { message: "I love Sismo" }
},

Resulting in the following request:

image

It has 4 main properties that we will cover one by one.

‣

1. appId

appId: "0x02bcb449a6bd1062017cf0315375afdf",

Applications within Sismo Connect have their own appId. You can find yours once you created your App on the page Factory Apps Explorer:

image
‣

2. authRequests

authRequests: [{ authType: AuthType.VAULT }],

This contains a list of authentications from accounts (web2, like GitHub or Twitter, or web3, like an Ethereum account) we want to request from our users. Various AuthTypes are possible:

  • AuthType.VAULT : The request returns the user’s vaultId.
  • AuthType.GITHUB : The request returns the user’s GitHub account id.
  • AuthType.TWITTER : The request returns the user’s Twitter account id.
  • AuthType.EVM_ACCOUNT : The request returns the user’s Ethereum address.
  • AuthType.TELEGRAM : The request returns the user’s Telegram account id.
  • Additionally, you can add the isOptional: true to an authRequest to give optionality to users for sharing their accounts.
‣
Example for authType with all Types and one optional:
authRequests: [
	{ authType: AuthType.VAULT },
	{ authType: AuthType.GITHUB },
	{ authType: AuthType.TWITTER },
	{ authType: AuthType.EVM_ACCOUNT },
	{ authType: AuthType.TELEGRAM, isOptional: true },
],
image

This example will request all with Sismo Connect available authTypes. By default all are required. The telegram is set to isOptional: true so the user can decide if they like to share this or not. You can customize to which are optional by add the isOptional: true to an authType.

⚠️
Read more about AuthType in our documentation.
‣

3. claimRequests

claimRequests: [
	  {
			// sismo-community
	    groupId: "0xd630aa769278cacde879c5c0fe5d203c",
    },
 ],
‣
Result:
image

This part contains the information needed to request Zero-Knowledge proof, which verifies membership in a particular group. For the above example, it uses the groupId for the group “sismo-community”. You can see this group in our factory here.

You can get a groupId by

Customizing the groupId

Your Sismo Connect application might not actually be useful with the group “sismo-community”. This is where you can change the groupId to one that fits better with your usecase. Users can make Zero-Knowledge Proof of group membership from a Data Source.

⚠️
Read our documentation for more information about Core Compontents.

Once you created or found a group, you can edit the groupId within the claimRequest:

claimRequests: [
	  {
			// nouns-dao-nft-holders
	    groupId: "0x311ece950f9ec55757eb95f3182ae5e2",
    },
 ],
‣
Result:
image

In this example, we changed the groupId to “nouns-dao-nft-holders”. The request will now be for proof of ownership of at least one Nouns DAO NFT.

⚠️
Read more about claims in our documentation. See our factory to explore all the available groups or to create new groups from the interface: https://factory.sismo.io/ For a guide on how to create your Data Group within the factory, check out our documentation: Sismo Factory: Create a Data Group in 5 Minutes

Customizing the value

The “sismo-community” consists of 3 Levels. To request a proof of membership for level 2 or higher, we can modify the request to add the value keyword:

claimRequests: [
	  {
			// sismo-community
	    groupId: "0xd630aa769278cacde879c5c0fe5d203c",
			value: 2,
    },
 ],
‣
Result
image

Similarly, if we only want to request proof for level 3 or higher, we can change the value to 3.

Customizing the claimType

By default, the request will always be with the claim type “greater than or equal”. Meaning, we requested proof for a value that is equal to or higher than what we specified with value. If we want the claim to be equal to the value, we can add the option claimType: ClaimType.EQ

‣
Example for ClaimType.EQ:
claimRequests: [
	  {
	    groupId: "0xd630aa769278cacde879c5c0fe5d203c",
			value: 2,
			claimType: ClaimType.EQ
    },
 ],

Here we request a proof for group membership of exactly level 2.

image

Adding multiple groupIds

For different use cases, we might want to add multiple groupId's for a claimRequest. One example: we request one additional proof to prevent sybil-attacks (a user creating multiple wallets to exploit the system). For that we can use the group “gitcoin-passport-holders”. Gitcoin Passport Website: https://passport.gitcoin.co/

claimRequests: [
	  {
			// nouns-dao-nft-holders
	    groupId: "0x311ece950f9ec55757eb95f3182ae5e2",
    },
		{
			// gitcoin-passport-holders
			groupId: "0x1cde61966decb8600dfd0749bd371f12",
			value: 15,
		},
 ],
‣
Result
image

As you can see, we added the second group with the id: 0x1cde61966decb8600dfd0749bd371f12, which is the Gitcoin Passport holder. In addition, we added a value of 15, to request a proof for users that their Gitcoin Passport is equal to or above a value 15. The higher the value, the more accounts the users need to add to their Gitcoin Passport and the harder it becomes to Sybil attack.

ℹ️ You can add multiple groupId's this way, just add them to the claimRequest object shown above.

Adding optional groups

Sometimes we want to give our users the optionality of providing a proof for Group Membership. For example, we can offer higher rewards for optional groups but still offer a base reward for the non-optional proofs of Group Membership. We can adjust the example to allow the optionality to proof Group Member of “nouns-dao-nft-holders”. We do this with the property isOptional: true. The example claimRequest will then look like this:

claimRequests: [
	  {
			// nouns-dao-nft-holders
	    groupId: "0x311ece950f9ec55757eb95f3182ae5e2",
			isOptional: true,
    },
		{
			// gitcoin-passport-holders
			groupId: "0x1cde61966decb8600dfd0749bd371f12",
			value: 15,
		},
 ],
‣
Result
image

We adjusted the request such that, the ownership of the Nouns DAO NFT is optional (a user may choose to prove ownership) and the ownership of a Gitcoin Passport of a score 15 or higher is non-optional.

For example with multiple requests

‣
Here is an example with multiple different groups, optionalities and values.
claimRequests: [
	  {
			// nouns-dao-nft-holders
	    groupId: "0x311ece950f9ec55757eb95f3182ae5e2",
			isOptional: true,
    },
		{
			// gitcoin-passport-holders
			groupId: "0x1cde61966decb8600dfd0749bd371f12",
			value: 15,
		},
		{
			// sismo-factory-users
			groupId: "0x05629c9a54e30d8c8aea911a48cd9e30",
		},
		{
			// sismo-community
			groupId: "0xd630aa769278cacde879c5c0fe5d203c",
		},
 ],
image

⚠️
Read more about claims in our documentation. See our factory to explore all the available groups or to create new groups from the interface: https://factory.sismo.io/ For a guide on how to create your Data Group within the factory, check out our documentation: Sismo Factory: Create a Data Group in 5 Minutes
‣

4. signature

signature: { message: "I love Sismo" }
‣
Result
image

The last property is the signature. This is an optional property, if you don’t need it, you can remove it.

This is very similar to signing a message with your Ethereum wallet, whereas here it will request a signature to be signed with the user's Data Vault. This allows your application to verify arbitrary data, such as an Ethereum address.

Read why this can be useful, especially for onchain applications: Why a signature is often needed when verifying proofs onchain?

⚠️
Read more about signatures in our documentation.

⚠️
Feel free to customize the sismoConnectRequest to fit your objective. Read our documentation for more information: https://docs.sismo.io/. If you have any questions or trouble setting up your own group or creating your app, reach out to us to our Telegram or Discord.