Email Association

Overview

A necessary step before a user can trade his/her assets is to go through the most minimal KYC: use a verified email. Each web3 address needs to be associated to a verified email.

Assets can be created to web3 addresses that have never been associated to any email. It is only when those assets engage in trading that email association is required.

This is a necessary step to be able to transact in FIAT, required by any 3rd party payments provider, as well as to offer trading services in many countries. It protects clients and their users.

A web3 address can only be associated, at any given time, to one email. However, multiple web3 addresses can be associated to the same email.

Associating an email to a web3 address

Email association needs to be done only once per user. In this process:

1. The Universe owner is responsible for verifying the user's email by whatever method is preferred.

2. The Universe owner relays the user's signature accepting to link the email to a web3 address.

The first step is business as usual.

The second step is easily done by following this example. By executing the mutation described below, the Universe Owner states that the user's email has been verified, and that the user wishes to link a web3 address to such email. The backend checks that the mutation comes from the Universe Owner by verifying the b2b token, and the user's intention by verifying the user's signature.

NodeJS

const { digestLinkAddress, sign } = require('freeverse-marketsigner-js');

// Compute the digest to be signed:
const digest = digestLinkAddress({ email, web3address });

// sign with your favorite method,
// using a user's web3 account instantiated from a privKey in this example:
const signature = sign({ digest, web3account: userWeb3Account });
const signatureWithout0x = signature.substring(2, signature.length);

const graphQLMutation = `
  mutation {
    linkWeb3AddressToEmail(
      input: {
        email: "${email}",
        alias: "${alias}",
        web3Address: "${userWeb3Address}",
        signature: "${signatureWithout0x}",
        universeName: "The Amazing Game",
        language: "en",
        sendEmail: true,
      }
    )
  }`;

This mutation needs the proper universe owner b2b auth token to be included in the headers.

It is important to properly verify emails. For example, cashout links will be sent directly to the email associated to a given web3 address.

The parameter sendEmail is optional, with the default value true. If the mutation is successful and sendMail is true, the user will receive an email informing that the provided web3Address has been linked to the corresponding email.

universeName is also optional.

The language parameter is mandatory; currently, the email languages supported are English ("en") and Spanish ("es").

If a web3 address has already been linked with an email, the following query will return a bound boolean with value true:

GraphQL

query {
  userById(id: "0xf3Bdc620f7B6824678f27733767F1cDF747C440b") {
    bound
  }
}

Unlinking an email from a web3 address

An email can be unlinked from a web3 address. This can be useful in cases where a user changes email and wants to dissociate his web3 address from the old email. Once done, the user will be able to link the new email to the web3 address.

Unlinking a web3 address from an email can be done following this example. By executing the mutation described below, the Universe Owner unlinks a web3 address from the provided email.

NodeJS

const { digestUnlinkAddress, sign } = require('freeverse-marketsigner-js');

// Compute the digest to be signed:
const digest = digestUnlinkAddress({
  email,
  web3Address: userWeb3Address,
});

// sign with your favorite method,
// using a user's web3 account instantiated from a privKey in this example:
const signature = sign({ digest, web3account: userAccount });
const signatureWithout0x = signature.substring(2, signature.length);

// inject results into final mutation to send to graphQL endpoint
const unlinkWeb3AddressMutation = `
mutation{
    unlinkWeb3Address(input: {
      email: "${email}",
      signature: "${signatureWithout0x}"
      web3Address: "${userWeb3Address}"
    })
  }
`;
console.log(unlinkWeb3AddressMutation);

This mutation needs the proper universe owner b2b auth token to be included in the headers.

Note that the signature needs to be provided by the owner of the web3address

On success, the unlinkWeb3Address mutation will return a boolean with value true.