# How to verify Address-Ownership

## Certificates

Certificates provide proof of ownership for a specific address. In combination with wallets, they offer a standardized method for signing agreements or creating a sign-in experience with VeChain.

Common use cases include user identification through sign-in and request verification between services.

### Anatomy

The structure of a certificate is clearly defined and includes a purpose, payloads, domain, and signer.

```ts
interface Certificate {
    /**
     * The purpose field indicates the intended use or context of the certificate.
     * For example, it could be used for identification, verification, or attestation.
     */
    purpose: string;

    /**
     * The payload field holds the actual content of the certificate.
     * This content can be of various types, such as text, images, or other data.
     */
    payload: {
        type: string;
        content: string;
    };

    /**
     * The domain field represents the specific context or domain for which the certificate is valid.
     * It helps ensure that the certificate is only applicable within the intended context.
     */
    domain: string;

    /**
     * The timestamp field records the time at which the certificate was created or issued.
     * This provides a temporal reference for the certificate's validity.
     */
    timestamp: number;

    /**
     * The signer field indicates the address of the entity that signs the certificate.
     * It is the public key address of the entity that issues the certificate.
     */
    signer: string;

    /**
     * The signature field contains the cryptographic signature generated by the issuer's private key.
     * This signature ensures the integrity and authenticity of the certificate's content.
     */
    signature?: string;
}
```

### Sign

To sign a certificate yourself, you will need to:

1. Obtain the signer's address.
2. Encode the certificate object into a JSON string. Avoid using `JSON.stringify` directly, as the key order may vary, potentially causing verification failures across different platforms, use `certificate.encode()` instead.
3. Sign the encoded string.

If you possess only the private key, you can derive the public address from its corresponding public key:

```js
// calculate signer from private key
const publicKey = secp256k1.derivePublicKey(privateKey);
cert.signer = addressUtils.fromPublicKey(publicKey);
```

Signing example:

```js
// encode & sign
const jsonStr = certificate.encode(cert);
const rawSignature = secp256k1.sign(blake2b256(jsonStr), privateKey);
const signature = `0x${rawSignature.toString('hex')}`;
```

Adding the `signature` attribute to the certificate turns it into a signed certificate, available for verification on other platforms.

{% hint style="info" %}
An API verification can consist of a client sending JSON.stringified and base64 encoded version in the headers. The API can then decode and verify the certificate.
{% endhint %}

### Verify

Verification is done using `certificate.verify(cert)` which will throw in case of any error. Catching errors is therefor important:

```js
try {
  certificate.verify(signedCert);
  console.log('verification successful')
}
catch (err) {
  console.log('verification failed', err.message)  
}
```

## Example Projects

### Sign & Verify

{% embed url="<https://stackblitz.com/github/vechain-energy/example-snippets/tree/v1.0.0/sdk/certificate?ctl=1&embed=1&file=index.mjs&hideExplorer=1&hideNavigation=1&view=editor>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vechain.org/developer-resources/how-to-verify-address-ownership.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.