Add documentation for delegateBySig (#2927)

[hack3r-0m]

Fixes #2927

PR Checklist

• [x] Tests
• [x] Documentation
• [ ] Changelog entry

[hack3r-0m]

is CHANGELOG entry required for documentation edit?

[Amxx]

@hack3r-0m I don't think we need a changelog entry for that. We do however need to document that the domain separator includes a version field. Without that, your documentation is actually incorrect.

Maybe it would also be nice to add example of code to produce these signature.

[hack3r-0m]

thanks @Amxx, i have documented version, regarding example, how comprehensive it should be? should it use ethereum-js utils or ethers or web3? similiar to https://gist.github.com/ajb413/a5466a61558c0897491c378ce6682ad0#file-delegate-sign-js with version in domain seperator should work?

[Amxx]

In my opinion, the more the better.

I do believe that web3 doesn't support that natively.

I would definitely include ethers's Wallet._signTypedData

const signature = await wallet._signTypedData({
    chainId: 5,
    name: 'Mytoken',
    verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
    version: '1.0.0',
}, {
    // No need for Domain definition with ethers
    Delegation: [
        { name: 'delegatee', type: 'address' },
        { name: 'nonce', type: 'uint256' },
        { name: 'expiry', type: 'uint256' },
    ],
}, {
    delegatee: <some address>,
    nonce: <some nonce>,
    deadline: <some deadline>,
});

I would also include the jsonrpc way

const msgParams = JSON.stringify({
    domain: {
        chainId: 5,
        name: 'Mytoken',
        verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
        version: '1.0.0',
    },
    types: {
        EIP712Domain: [
             { name: 'name', type: 'string' },
             { name: 'version', type: 'string' },
             { name: 'chainId', type: 'uint256' },
             { name: 'verifyingContract', type: 'address' },
        ],
        Delegation: [
            { name: 'delegatee', type: 'address' },
            { name: 'nonce', type: 'uint256' },
            { name: 'expiry', type: 'uint256' },
        ],
    },
    message: {
        delegatee: <some address>,
        nonce: <some nonce>,
        deadline: <some deadline>,
    },
    primaryType: 'Delegation',
  });
const signature = await provider.send('eth_signTypedData_v4', [ from, msgParams ]);

[hack3r-0m]

thanks, @Amxx, version should be 1.0.0 or 1 while adding examples into docs? since https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/extensions/draft-ERC20Permit.sol#L36 uses 1 while the one you mentioned uses 1.0.0

official eip too does have any clarification whether it should be a semantic version or not.

[Amxx]

You are right, our code uses "1" ... then so should the examples !

[frangio]

Thank you @hack3r-0m! I agree we should say in the documentation that version is hardcoded to "1".

[hack3r-0m]

I have also replaced deadline from the above example with expiry to match the type's attribute.

[frangio]

This is great content but it's too much to include in the Solidity file itself... I'm trying to figure out where else we can put it.