# EIP712 Signature

# Intro

A signature scheme consists of a hashing algorithm and a signing algorithm. The signing algorithm of choice in Ethereum is secp256k1. The hashing algorithm of choice is keccak256.

EIP712 defines a standard API for Web3 Provider (e.g., wallets) to generate signatures over human-readable data where the signature can be verified either by a Smart Contract on the Ethereum Blockchain, or completely offchain.

The rational is to use existing Web3 Providers and their secure key management system to produce signatures that are compliant with the JSON-LD and more specifically, the Linked Data Signatures (LDS) data model.

Since EIP712 requires the parameters to the EIP712 signature generating functions relies on JSON schemas, implementers need to ensure that the linked data document matches the EIP712 JSON schema that will be provided to the EIP712 signature function.

## EIP712 Signature

To generate the signature, EIP712 requires `TypedData` which is a JSON object containing type information, domain separator parameters and the message object.

`TypedData` MUST be a JSON object according to the EIP712 specification and contains properties `types`, `domain`, `primaryType` and `message`.

`types` MUST be a JSON array with two entries. The first entry refers to the `EIP712Domain` property that contains the JSON schema according to the EIP712 specification. The second entry MUST be the JSON schema of the message to be signed in the EIP712 format.

`message` MUST be the linked data object that contains the message to be signed.

The following is a non-normative example of the EIP712 `TypedData` object:

{
    'types': {
        'EIP712Domain': [
          { 'name': 'name', 'type': 'string' },
          { 'name': 'version', 'type': 'string' },
          { 'name': 'chainId', 'type': 'uint256' },
          { 'name': 'salt', 'type': 'bytes32' },
        ],
        ... messageDataEip712Schema
    },
    'domain': {
        'name': 'https://www.example.com',
        'version': '2',
        'chainId': 1,
        'salt': '§$§AdwerWO_IE()§%fd__',
    },
    'primaryType': 'VerifiableCredential',
    'message': {
        ... messageData
    }
}

The following is a non-normative example of the JSON schema for the message to be signed according to EIP712:

{
  'VerifiableCredential': [
    { 'name': '@context', 'type': 'string[]' },
    { 'name': 'type', 'type': 'string[]' },
    { 'name': 'id', 'type': 'string' },
    { 'name': 'issuer', 'type': 'string' },
    { 'name': 'issuanceDate', 'type': 'string' },
    { 'name': 'credentialSubject', 'type': 'CredentialSubject' },
    { 'name': 'credentialSchema', 'type': 'CredentialSchema' }
  ],
  'CredentialSchema': [
    { 'name': 'id', 'type': 'string' },
    { 'name': 'type', 'type': 'string' },
  ],
  'CredentialSubject': [
    { 'name': 'type', 'type': 'Person' },
    { 'name': 'id', 'type': 'string' }
  ],
  'Person': [
    { 'name': 'type', 'type': 'string' },
    { 'name': 'id', 'type': 'string' },
    { 'name': 'name', 'type': 'string' }
  ]
}

The following is a non-normative example of the `message` object:

{
    '@context': [
        'https://www.w3.org/2018/credentials/v1',               'https://www.example.com/context/v1',
        'https://schema.org/Person'
    ],
    'type': [
        'VerifiableCredential',
        'VerifablePerson'
    ],
    'id': 'https://example.com/person/1234',
    'issuer': 'did:example:bbbb',
    'issuanceDate': '2010-01-01T19:23:24Z',
    'credentialSubject': {
        'id': 'did:example:aaaa',
        'type': 'Person',
        'name': 'Vitalik'
    },
    'credentialSchema': {
        'id': 'https://www.example.com/schemas/v1',
        'type': 'Eip712SchemaValidator2021'
    }
}

[JCS] normalization of `TypedData` is required before the EIP712 signature is generated.

## Proof Representation

The cryptographic material used to represent a linked data proof is called the proof type.

This specification relies on the output of the EIP712 signature function.

### Ethereum EIP712 Signature 2021

The `verificationMethod` property of the proof SHOULD be a URI. Dereferencing the `verificationMethod` SHOULD result in an object of type `EcdsaSecp256k1VerificationKey2019` or `EcdsaSecp256k1RecoveryMethod2020`.

The `type` property of the proof MUST be `EthereumEip712Signature2021`.

The `created` property of the proof MUST be an [ISO_8601] formated date string.

The `proofPurpose` property of the proof MUST be a string, and SHOULD match the verification relationship expressed by the verification method controller.

The `proofValue` property of the proof MUST be the hex encoded output of the EIP712 signature function according [EIP712].

The `eip712Domain` property MUST be the EIP712Domain that was used to generate the EIP712 signature.

The following is a non-normative example of an `EthereumEip712Signature2021` proof:

'proof' {
    'type': 'EthereumEIP712Signature2021',
    'created': '2019-12-11T03:50:55Z',
    'proofPurpose': 'assertionMethod',
    'proofValue': '0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c',
    'verificationMethod': 'did:example:aaaa#key-1',
    'eip712': {
        'messageDataEip712Schema': 'https://example.com/schemas/v1',
        'domain': { ... },        
        'primaryType': '...'
    }    
}