Smart contract architecture

[Elli610]

EVM-verifier architecture

Introduction

On its EVM version, Alice's Ring should allow anyone to mint a Soul Bound Token (SBT) which will prove that the associated ring signature (saved on IPFS) was at least valid when the SBT was minted. This is the main purpose of the EVM-verifier.

On its first version, the EVM-verifier should only be able to allow solvency proof generation for any ERC20 token (and the native token of the chain). In the future, it should be able to allow any kind of proof generation about onChain caracteristics.

This will be achieved through simple smart contract that will allow anyone to mint a SBT by providing the ring signature, the minimal amount and the IPFS link to the signature (the signature is not saved onChain). The contract will check that the ring signature is valid and that all addresses own at least the minimal amount of tokens specified. If the proof is valid, the contract will mint a SBT and will save the the IPFS link, the signature hash and the proved amount on the contract storage.

Development tools

• dev and deployment tool: hardhat framework.
• testing: hardhat-waffle plugin.

Architecture

SBT generation

sequenceDiagram
  autonumber

  participant IPFS
  Actor User
  participant evm as EVM-Verifier 

  User->>User: Generate ring signature

  User->>IPFS: Save the signature on IPFS

  User->>evm: Provide the proof,<br>IPFS link and minimal amount

  evm->>evm: Verify the proof

  break If proof verification fails
    evm-->>User: Revert
  end

  evm->>evm: Mint a SBT    

Loading

Once the SBT has been generated on the proving address, anyone can assume that the ring signature was valid when the SBT was minted. Which means that at block n, the prover had at least minAmount tokens.

Main contract components

The SBT is an openzeppelin ERC721 token. The contract with the following custom functions:

Representation of a public key:

struct pubKey {
    uint256 x;
    uint256 y;
}

Representation of a ring signature:

struct signature {
    pubKey[] ring;
    uint256 c;
    string message;
    uint256[] responses;
}

enum Status {
    UNKNOWN, // the proof has not been verified on-chain, no proof has been minted
    MINTED // the proof has already been minted
}

We also need a mapping to save the status of each proof:

mapping(string => Status) public mintStatus; // hash(all the responses) (computed off-chain)

The custom functions

    /**
    * @notice safeTransferFrom is disabled because the nft is a sbt
    */
    function safeTransferFrom(address from, address to, uint256 tokenId) external pure;

    /**
    * @notice transferFrom is disabled because the nft is a sbt
    */
    function transferFrom(address from, address to, uint256 tokenId) external pure override;

    /**
    * @notice approve is disabled because the nft is a sbt and cannot be transferred
    */
    function approve(address to, uint256 tokenId) external pure override;

    /**
    * @notice getApproved is disabled because the nft is a sbt and cannot be transferred
    */
    function getApproved(uint256 tokenId) external pure override returns (address operator);

    /**
    * @notice setApprovalForAll is disabled because the nft is a sbt and cannot be transferred
    */
    function setApprovalForAll(address operator, bool _approved) public pure override;

    /**
    * @notice isApprovedForAll is disabled because the nft is a sbt and cannot be transferred -> the output will always be false
    */
    function isApprovedForAll(address owner, address operator) public pure override returns (bool)

   /**
   * @notice Mint an SBT
   *
   * @remarks
   * The sbt is minted to msg.sender
   * If the verification of the signature is okay see (https://github.com/Cypher-Laboratory/EVM-Verifier/issues/3) and : 
   * - If `mintStatus[proofId] == UNKNOWN`, the proof is minted and the status is set to `MINTED`
   * - If `mintStatus[proofId] == MINTED`, the proof has already been minted. Tx will revert
   * 
   * @param token - the erc20 address of the token we are proving the ownership of
   * @param minBalance - the balance threshold
   * @param signature - the signature object
   * @param uri - the IPFS uri
   * @param proofId - the hash of all the responses used in the proof
   */
   function mint(address token, uint256 minBalance, Signature signature, string uri, string proofId) public payable;

    /**
    * @notice delete all the caracteristics of tokenId (burn)
    *
    * @remarks
    * Only the owner of an sbt can burn it 
    *
    * @param tokenId is the id of the sbt to burn
    */
    function burn(uint256 tokenId) external;

How to verify a ring signature

The ring signature is saved on IPFS. The contract will only save the IPFS link. The contract will also save the hash of the signature. The hash is computed as follows:

    // TO BE DEFINED

Alice's Ring will provide 2 tools to verify a ring signature:

• A frontend that will allow anyone to verify a ring signature from the chain or from the IPFS link (not implemented yet)
• A smart contract that will allow anyone to verify a ring signature (not implemented yet)

Testing

// to be defined

Deployment

// to be defined

[LeJamon]

Curve name is not necessary, EVM is on based on secp256k1.
So the struct curve, should be global variable.

By the way, I think it will make more sense to verify the holding of the fund off-chain.
Because to do on-chain we need this :

• compute the address based on the pubkey
• check if the adresse hold the fund

Because for the moment, we only have a N complexity and not a log N complexity verifier, I think that we should only verify the crypto on-chain and the balances off-chain

[LeJamon]

Moreover, from the scroll documentation (https://docs.scroll.io/en/technology/chain/differences/) the SHA2_256 is not supported yet

[Elli610]

We have to test this and see how much gas we need to run it (I guess it will be high).

If we don't verify the balances onChain, at least we should provide a tool (front and API) to allow anyone to verify a proof ans the balances.

Only one question remains:
if we do so, do everybody should be able to mint an sbt from with data they want or should the sbt factory only respond to us ?

Allowing anybody to mint an sbt could allow people from the community to prove things we didn't plan initially is a good thing because it can give us ideas and other protocols could ask their users for custom proofs without needing us to update stuff.
If we provide the front and API I mentioned before to allow anyone to verify a proof, I don't really see any drawback.

WDYT ?

[Elli610]

About the missing hash function, maybe they implemented another one so the implementation will be easy to update.
If they don't, we won't be able to verify the proof onChain

[LeJamon]

The mint of the SBT will only be possible if a valid proof is given as argument.
I don't see drawbacks to allow every one to mint proof. I mean, you don't need the authorisation of uniswap to make a swap

[Elli610]

I meant if we do not verify the balances.

In this case, the proof can be cryptographically valid. If we mint an sbt which tells Bob owns 10 eth but at least one of the addresses does not own >=10 eth, something is wrong.

To avoid that, one solution is restricting the access to mint.
Another solution is to allow anyone to mint sbt with valid proofs and provide an offChain verifier to allow anyone to verify at anytime if the balance assumption made in an sbt is valid or not

[LeJamon]

Can you describe the general workflow for the STATUS please ?

[Elli610]

The status is a simple way to protect the contract against minting the same sbt twice (for 2 addresses).

It also allows the contract to know if the proof has been computed in our front end which means the user has already paid for the mint. Else, the proof has been generated by a third party so the sbt mint could be charged using the pricing function from the contract.

UNKNOWN -> Generated from third party
PAID -> Generated in Alice's frontend
MINTED -> The SBT has already been minted, the tx reverts