Achievo Frontend Randomness Documentation

Overview

To log in to Achievo, the frontend connection requires a specific token ID minted for the user's address, along with a signature and a message signed by the user for Achievo authentication.

Authentication Process

1. Wallet Signature Generation

Using Viem, generate a signature from the user's wallet:

const ACHIEVO_MESSAGE = "ACHIEVO LOGIN";
const walletSignature = await walletClient?.signMessage({
  account: walletClient?.account.address,
  message: ACHIEVO_MESSAGE,
});

2. JWT Generation

With React v18 and Viem, call the endpoint to generate the JWT (JSON Web Token):

const { data: jwt } = await axios.post(
  `${ACHIEVO_BASE_URL}/v1/auth/login/nftGating`,
  {
    tokenId: NFT_GATING_TOKEN_ID, // Provided by the Achievo team
    address: walletClient?.account.address,
    signature: walletSignature,
    smartContractAddress: SMART_CONTRACT_ADDRESS, // Provided by the Achievo team
    tenantId: TENANT_ID, // Provided by the Achievo team
    message: walletMessage,
  }
);
return { jwt };

3. Call the randomness service

Once authenticated, you can call the randomness service using the JWT. By passing decode: true in the body, you will receive integer values in the response.

Note: pass exactly the user address in the params

const getRandomness = async () => {
  const {
    data: { randomData, nonce, signature, decodedItems },
  } = await axios.post(
    `${ACHIEVO_BASE_URL}/v1/public/randomness/signature/items/${walletClient?.account.address}`,
    {
      layers: [{ dataQty: 1 }],
      decode: true,
    },
    {
      headers: { Authorization: achievoJWT },
    }
  );
  return { randomData, nonce, signature, decodedItems };
};

Conclusion

This documentation outlines the steps for frontend authentication and accessing the randomness service in Achievo using React v18 and Viem. It covers the process of generating a wallet signature, obtaining a JWT, and making authenticated requests to the randomness service.

Request schema:

This is the Zod schema to use the layers:

  body: z.object({
    layers: z
      .array(
        z.object({
          dataQty: z.number().optional(),
          tier: z.nativeEnum(TierNumber).optional(),
          tiers: z.array(z.nativeEnum(TierNumber)).optional(),
          level: z.number().min(0).optional(),
          levels: z.array(z.number().min(0)).optional(),
          category: z.number().optional(),
          collection: z.string().optional(),
          collections: z.array(z.string()).optional(),
          excludeCategories: z.array(z.number()).min(1).optional(),
        })
      )
      .min(1),
    decode: z.boolean().optional().default(false),
  }),
  params: z.object({
    address: z.string(),
  }),
  headers: HeaderJWT,

Supported tiers:

enum TierNumber {
  COMMON, // 0
  UNCOMMON, // 1
  RARE, // 2
  LEGENDARY, // 3
  MYTHICAL, // 4
  CELESTIAL, // 5
  ARCANE, // 6
  ETHEREAL, // 7
}