### Install and Run @twin.org/attestation-cli

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Demonstrates how to install the attestation CLI globally using npm and then run it. Alternatively, it shows how to execute the CLI directly using npx without a global installation.

```shell
npm install @twin.org/attestation-cli -g
twin-attestation
```

```shell
npx "@twin.org/attestation-cli"
```

--------------------------------

### Example Attestation Get Output

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Example JSON output when retrieving attestation details, showing attestation ID, creation timestamp, owner, data, and proof.

```json
{
  "id": "attestation:iota:aW90YS1uZnQ6dHN0OjB4MDI3M2M3ZGEyZjJhZjg1YTE1ZWMwZTQ0OWRmOWI3NTQwNWYzYWExOTQzZmYzMjJkM2ZlODIxMDFlNzEzMzYxYg==",
  "created": "2024-06-19T14:08:50Z",
  "ownerIdentity": "did:iota:tst:0x197c348b8ff62f515ca9685f7a4b567a073a0e6c492c641fdd029d909126da93",
  "data": {
    "docName": "bill-of-lading.pdf",
    "fingerprint": "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f",
    "mimeType": "application/pdf"
  },
  "proof": {
    "type": "jwt",
    "value": "eyJraWQiOiJkaWQ6aW90YTp0c3Q6MHgxOTdjMzQ4YjhmZjYyZjUxNWNhOTY4NWY3YTRiNTY3YTA3M2EwZTZjNDkyYzY0MWZkZDAyOWQ5MDkxMjZkYTkzI2F0dGVzdGF0aW9uIiwidHlwIjoiSldUIiwiYWxnIjoiRWREU0EifQ.eyJpc3MiOiJkaWQ6aW90YTp0c3Q6MHgxOTdjMzQ4YjhmZjYyZjUxNWNhOTY4NWY3YTRiNTY3YTA3M2EwZTZjNDkyYzY0MWZkZDAyOWQ5MDkxMjZkYTkzIiwibmJmIjoxNzE4ODA2MTMwLCJ2YyI6eyJAY29udGV4dCI6Imh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwidHlwZSI6IlZlcmlmaWFibGVDcmVkZW50aWFsIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiZG9jTmFtZSI6ImJpbGwtb2YtbGFkaW5nLnBkZiIsImZpbmdlcnByaW50IjoiMHhmMGI5NWE5OGIzZGJjNWNlMWM5Y2U1OWQ3MGFmOTVhOTc1OTlmMTAwYTcyOTZlY2RkMWViMTA4YmViZmEwNDdmIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYifX19.7MF1NR5glR_4XIAAgo_BhZ-nlJKLE3T5GS4zEsBRTHK8_nV-RsZupdEJw_F62f6pj1nGP2xVV7M3yCjPG7G5Dg"
  }
}
```

--------------------------------

### Attestation CLI Help and Command Details

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Shows how to display the general help information for the attestation CLI and how to get detailed help for a specific command, such as 'attestation-create'. This is useful for understanding available options and subcommands.

```shell
twin-attestation --help
```

```shell
twin-attestation attestation-create --help
```

--------------------------------

### Generate Address and Update Wallet Environment File

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Shows how to generate addresses from a seed and store them in an environment file. This example uses the 'address' command, specifying the environment file, HRP, seed, count of addresses, and merging options.

```shell
# Generate an address and store it in the env file
twin-attestation address --load-env wallet.env --hrp tst --seed !SEED --count 4 --env wallet.env --merge-env
```

--------------------------------

### Create Attestation using CLI

Source: https://context7.com/twinfoundation/attestation/llms.txt

Guides through the process of creating an attestation using the command-line interface. It covers installation, environment setup, identity creation, and the final attestation creation command.

```bash
# Install CLI globally
npm install @twin.org/attestation-cli -g

# Create config.env with network settings
cat > config.env << 'EOF'
NODE_URL="https://api.testnet.iotaledger.net"
FAUCET_URL="https://faucet.testnet.iotaledger.net/api/enqueue"
EXPLORER_URL="https://explorer.iota.org/iota-testnet/"
EOF

# Generate wallet seed and mnemonic
twin-attestation mnemonic --env wallet.env

# Generate addresses from seed
twin-attestation address --load-env wallet.env --hrp tst --seed !SEED --count 4 --env wallet.env --merge-env

# Fund the address
twin-attestation faucet --load-env config.env --address !ADDRESS_0

# Create identity for attestation owner
twin-attestation identity-create --load-env config.env wallet.env --seed !SEED --controller !ADDRESS_0 --env identity.env

# Add verification method to identity
twin-attestation verification-method-add --load-env config.env wallet.env identity.env --seed !SEED --did !DID --type verificationMethod --id attestation --env verification-method.env

# Create data.json with content to attest
cat > data.json << 'EOF'
{
  "docName": "bill-of-lading.pdf",
  "fingerprint": "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f",
  "mimeType": "application/pdf"
}
EOF

# Create the attestation
twin-attestation attestation-create \
  --load-env config.env wallet.env verification-method.env \
  --seed !SEED \
  --owner !ADDRESS_0 \
  --verification-method-id !DID_VERIFICATION_METHOD_ID \
  --private-key !DID_VERIFICATION_METHOD_PRIVATE_KEY \
  --data-json data.json \
  --env attestation.env
```

--------------------------------

### Request Funds from Faucet

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Demonstrates how to request funds from the faucet for a specific address. This uses the 'faucet' command, loading environment variables from 'config.env' and specifying the target address.

```shell
# Add some funds to the address generated in the previous step
twin-attestation faucet --load-env config.env --address !ADDRESS_0
```

--------------------------------

### Configure Node and Faucet URLs

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Configuration settings for connecting to the IOTA testnet node and faucet. This `config.env` file is essential for most `twin-attestation` operations.

```shell
NODE_URL="https://api.testnet.iotaledger.net"
FAUCET_URL="https://faucet.testnet.iotaledger.net/api/enqueue"
EXPLORER_URL="https://explorer.iota.org/iota-testnet/"
```

--------------------------------

### Retrieve Attestation Details

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Fetches the details of a specific attestation using its ID. It requires the configuration and attestation environment files.

```shell
twin-attestation attestation-get --load-env config.env attestation.env --id !ATTESTATION_ID
```

--------------------------------

### Install TWIN Attestation Models with npm

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-models/README.md

This snippet shows how to install the @twin.org/attestation-models package using npm. This is the primary method for integrating the attestation models into your project.

```shell
npm install @twin.org/attestation-models
```

--------------------------------

### Create Attestation

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Creates an attestation for the specified data. It loads configuration from multiple environment files, requires owner and verification method details, and stores the attestation ID in `attestation.env`.

```shell
twin-attestation attestation-create --load-env config.env wallet.env verification-method.env --seed !SEED --owner !ADDRESS_0 --verification-method-id !DID_VERIFICATION_METHOD_ID --private-key !DID_VERIFICATION_METHOD_PRIVATE_KEY --data-json data.json --env attestation.env
```

--------------------------------

### Install TWIN Attestation Service using npm

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-service/README.md

This snippet shows how to install the TWIN Attestation Service package using npm. It is a prerequisite for using the service in your project.

```shell
npm install @twin.org/attestation-service
```

--------------------------------

### Attestation Transfer Confirmation JSON Structure

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Example JSON output after successfully transferring an attestation. It includes details like the attestation ID, creation timestamp, owner identity, data fingerprint, proof, the new holder's identity, and the transfer timestamp.

```json
{
  "id": "attestation:iota:aW90YS1uZnQ6dHN0OjB4MDI3M2M3ZGEyZjJhZjg1YTE1ZWMwZTQ0OWRmOWI3NTQwNWYzYWExOTQzZmYzMjJkM2ZlODIxMDFlNzEzMzYxYg==",
  "created": "2024-06-19T14:08:50Z",
  "ownerIdentity": "did:iota:tst:0x197c348b8ff62f515ca9685f7a4b567a073a0e6c492c641fdd029d909126da93",
  "data": {
    "docName": "bill-of-lading.pdf",
    "fingerprint": "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f",
    "mimeType": "application/pdf"
  },
  "proof": {
    "type": "jwt",
    "value": "eyJraWQiOiJkaWQ6aW90YTp0c3Q6MHgxOTdjMzQ4YjhmZjYyZjUxNWNhOTY4NWY3YTRiNTY3YTA3M2EwZTZjNDkyYzY0MWZkZDAyOWQ5MDkxMjZkYTkzI2F0dGVzdGF0aW9uIiwidHlwIjoiSldUIiwiYWxnIjoiRWREU0EifQ.eyJpc3MiOiJkaWQ6aW90YTp0c3Q6MHgxOTdjMzQ4YjhmZjYyZjUxNWNhOTY4NWY3YTRiNTY3YTA3M2EwZTZjNDkyYzY0MWZkZDAyOWQ5MDkxMjZkYTkzIiwibmJmIjoxNzE4ODA2MTMwLCJ2YyI6eyJAY29udGV4dCI6Imh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwidHlwZSI6IlZlcmlmaWFibGVDcmVkZW50aWFsIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiZG9jTmFtZSI6ImJpbGwtb2YtbGFkaW5nLnBkZiIsImZpbmdlcnByaW50IjoiMHhmMGI5NWE5OGIzZGJjNWNlMWM5Y2U1OWQ3MGFmOTVhOTc1OTlmMTAwYTcyOTZlY2RkMWViMTA4YmViZmEwNDdmIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYifX19.7MF1NR5glR_4XIAAgo_BhZ-nlJKLE3T5GS4zEsBRTHK8_nV-RsZupdEJw_F62f6pj1nGP2xVV7M3yCjPG7G5Dg"
  },
  "holderIdentity": "did:iota:tst:0x7eb877f0212b7aef197fbebf1c2816489d16b6a619f730cb3a371ace1075aed0",
  "transferred": "2024-06-19T13:45:40.694Z"
}
```

--------------------------------

### Install TWIN Attestation CLI using npm

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/README.md

This snippet shows how to install the TWIN Attestation CLI package using npm. It is a prerequisite for using the command-line tool.

```shell
npm install @twin.org/attestation-cli
```

--------------------------------

### Create Attestation with Options

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Illustrates the command to create an attestation, detailing the various options available such as specifying the seed, owner, verification method ID, private key, and data source. It also covers output formatting options like JSON and environment file generation.

```shell
twin-attestation attestation-create \
  --seed <seed> \
  --owner <owner> \
  --verification-method-id <verification-method-id> \
  --private-key <private-key> \
  --data-json <data-json> \
  --no-console \
  --json <filename> \
  --merge-json \
  --env <filename> \
  --merge-env \
  --node <url> \
  --explorer <url>
```

--------------------------------

### Generate Mnemonic and Wallet Environment File

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

This command sequence demonstrates generating a mnemonic and storing it in a wallet environment file. It uses the 'mnemonic' command with the '--env' option to create or update a 'wallet.env' file.

```shell
# Generate a seed and mnemonic and store it in the env file
twin-attestation mnemonic --env wallet.env
```

--------------------------------

### Add Verification Method to Identity

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Adds a verification method to an identity. Requires environment files for configuration and wallet, along with a seed and DID. The output is stored in `verification-method.env`.

```shell
twin-attestation verification-method-add --load-env config.env wallet.env identity.env --seed !SEED --did !DID --type verificationMethod --id attestation --env verification-method.env
```

--------------------------------

### Attestation Create API

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

This command allows you to create an attestation. The owner address must have sufficient funds to store the data. The seed and funds can be generated using the mnemonic and faucet commands. You must also have an identity with a verification method used to generate the verifiable credential for the attestation.

```APIDOC
## POST /attestation-create

### Description
Creates an attestation for provided data.

### Method
POST

### Endpoint
twin-attestation attestation-create

### Parameters
#### Query Parameters
- **--seed** (string) - Required - The seed for the owner address in hex or base64 used to fund the attested storage, or start with ! to read environment variable.
- **--owner** (string) - Required - The address of the attestation owner, or start with ! to read environment variable.
- **--verification-method-id** (string) - Required - The full verification method id including did, or start with ! to read environment variable.
- **--private-key** (string) - Required - The private key for the verification method id, in either hex or base64 form, or start with ! to read environment variable.
- **--data-json** (string) - Required - A JSON file to read which includes the data for attestation.
- **--no-console** (boolean) - Optional - Hides the output in the console.
- **--json** (string) - Optional - Creates a JSON file containing the output.
- **--merge-json** (boolean) - Optional - If the JSON file already exists merge the data instead of overwriting.
- **--env** (string) - Optional - Creates an env file containing the output.
- **--merge-env** (boolean) - Optional - If the env file already exists merge the data instead of overwriting.
- **--node** (string) - Optional - The url for the node endpoint, or an environment variable name containing the url. (default: "!NODE_URL")
- **--explorer** (string) - Optional - The url for the explorer endpoint, or an environment variable name containing the url. (default: "!EXPLORER_URL")

### Request Example
```shell
twin-attestation attestation-create --seed <your_seed> --owner <your_owner_address> --verification-method-id <your_verification_method_id> --private-key <your_private_key> --data-json ./data.json
```

### Response
#### Success Response (200)
- **attestation_id** (string) - The ID of the created attestation.

#### Response Example
```json
{
  "attestation_id": "some_attestation_id"
}
```
```

--------------------------------

### Get and Verify Attestation using CLI

Source: https://context7.com/twinfoundation/attestation/llms.txt

Demonstrates how to retrieve and verify an attestation using its ID via the command-line interface. It also shows the expected output format.

```bash
# Verify attestation and display details
twin-attestation attestation-get --load-env config.env attestation.env --id !ATTESTATION_ID

# Output:
# {
#   "id": "attestation:iota:aW90YS1uZnQ6dHN0OjB4MDI3M2M3ZGEyZjJhZjg1YTE1ZWMwZTQ0OWRmOWI3NTQwNWYzYWExOTQzZmYzMjJkM2ZlODIxMDFlNzEzMzYxYg==",
#   "created": "2024-06-19T14:08:50Z",
#   "ownerIdentity": "did:iota:tst:0x197c348b8ff62f515ca9685f7a4b567a073a0e6c492c641fdd029d909126da93",
#   "data": {
#     "docName": "bill-of-lading.pdf",
#     "fingerprint": "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f",
#     "mimeType": "application/pdf"
#   },
#   "proof": {
#     "type": "jwt",
#     "value": "eyJraWQiOiJkaWQ6aW90YTp0c3Q6..."
#   }
# }
```

--------------------------------

### Get Attestation Information using IAttestationComponent

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-models/docs/reference/interfaces/IAttestationComponent.md

The `get` method resolves and verifies an attestation by its ID, returning a promise with the attestation's details. It requires the attestation ID as a string parameter.

```typescript
/**
 * Resolve and verify the attestation id.
 * @param id The attestation id to verify.
 * @returns Promise<IAttestationInformation> The verified attestation details.
 */
get(id: string): Promise<IAttestationInformation>;
```

--------------------------------

### Create Identity for Attestation Ownership

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

This command illustrates the creation of an identity intended to own an attestation. It utilizes the 'identity-create' command, loading environment variables from multiple files and specifying the seed, controller address, and output environment file.

```shell
# Create an identity to own the attestation
twin-attestation identity-create --load-env config.env wallet.env --seed !SEED --controller !ADDRESS_0 --env identity.env
```

--------------------------------

### Attestation Get API

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-service/docs/reference/functions/attestationGet.md

Retrieves and verifies an attestation ID.

```APIDOC
## GET /twinfoundation/attestation

### Description
Resolves and verifies the attestation id.

### Method
GET

### Endpoint
/twinfoundation/attestation

### Parameters
#### Query Parameters
- **componentName** (string) - Required - The name of the component to use in the routes.
- **request** (IAttestationGetRequest) - Required - The request object containing attestation details.

### Request Example
```json
{
  "componentName": "exampleComponent",
  "request": {
    "attestationId": "some-attestation-id"
  }
}
```

### Response
#### Success Response (200)
- **IAttestationGetResponse** - The response object with attestation verification details.

#### Response Example
```json
{
  "attestationId": "some-attestation-id",
  "isVerified": true,
  "details": "Attestation verified successfully."
}
```
```

--------------------------------

### Standard Git Commit Messages

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Examples of conventional commit messages used for features, fixes, documentation, and other changes. These messages follow a strict format to ensure clarity and automation.

```shell
git commit -m "feat: add JWT token validation"
git commit -m "fix: prevent endless loop in data lookup"
git commit -m "docs: update installation instructions"
```

--------------------------------

### Define Data for Attestation

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

A JSON structure representing the data to be attested. It includes document name, a cryptographic fingerprint, and MIME type. This file is used as input for the `attestation-create` command.

```json
{
  "docName": "bill-of-lading.pdf",
  "fingerprint": "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f",
  "mimeType": "application/pdf"
}
```

--------------------------------

### OpenAttestationConnector - Get Attestation

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-connector-open-attestation/docs/reference/classes/OpenAttestationConnector.md

Retrieves and verifies attestation details using its unique identifier.

```APIDOC
## GET /attestations/{id}

### Description
Resolve and verify the attestation id.

### Method
GET

### Endpoint
/attestations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The attestation id to verify.

### Response
#### Success Response (200)
- **IAttestationInformation** - The verified attestation details.

#### Response Example
```json
{
  "id": "urn:uuid:123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "@context": "https://schema.org/",
    "@type": "Person",
    "name": "Jane Doe"
  },
  "holder": "did:example:12345"
}
```
```

--------------------------------

### GET /attestations/{id}

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-rest-client/docs/reference/classes/AttestationRestClient.md

Resolve and verify the attestation id. This endpoint retrieves the details of a specific attestation.

```APIDOC
## GET /attestations/{id}

### Description
Resolve and verify the attestation id.

### Method
GET

### Endpoint
/attestations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The attestation id to verify.

### Response
#### Success Response (200)
- **IAttestationInformation** - The verified attestation details.

#### Response Example
```json
{
  "id": "attestation-12345",
  "data": {
    "@context": "http://schema.org",
    "@type": "Person",
    "name": "Jane Doe",
    "jobTitle": "Software Engineer"
  },
  "holder": "did:example:123",
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Verify Attestation Transfer with Twin CLI

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Retrieves attestation details using the twin-attestation CLI to confirm a successful transfer. The output JSON will show updated `holderIdentity` and `transferred` fields.

```bash
twin-attestation attestation-get --load-env config.env wallet.env attestation.env identity2.env --seed !SEED --id !ATTESTATION_ID
```

--------------------------------

### Transfer Attestation Ownership with Twin CLI

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Transfers an attestation to a new holder using the twin-attestation CLI. It requires environment files for configuration and specifies the attestation ID, new holder address, and holder identity. The original issuer remains intact.

```bash
twin-attestation attestation-transfer --load-env config.env wallet.env attestation.env identity2.env --seed !SEED --id !ATTESTATION_ID --holder-address !ADDRESS_1 --holder-identity !DID
```

--------------------------------

### Transfer Attestation

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/examples.md

Transfers an existing attestation to a new holder. This process involves funding the new address, creating a new identity for the recipient, and then performing the transfer. The seed of the current owner is required.

```shell
# Add some funds to the second address generated earlier
twin-attestation faucet --load-env config.env --address !ADDRESS_1

# Create new identity on the second address
twin-attestation identity-create --load-env config.env wallet.env --seed !SEED --controller !ADDRESS_1 --env identity2.env
```

--------------------------------

### Get and Verify Attestation (REST API)

Source: https://context7.com/twinfoundation/attestation/llms.txt

Retrieves and verifies an attestation using its unique ID. The response includes comprehensive attestation details, such as verification status, proof, owner identity, and the original attested data. It accepts JSON format for the response.

```bash
curl -X GET "https://localhost/attestation/attestation:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg==" \
  -H "Accept: application/json"
```

--------------------------------

### Prepare Production Version (GitHub Action)

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Instructions for using the 'Versions Prepare' GitHub Action to prepare the 'main' branch for a production release by merging 'next' into 'main'.

```yaml
# Example workflow snippet (actual action configuration may vary)
- name: Prepare Main Branch
  uses: twinfoundation/attestation/.github/workflows/versions-prepare.yml@main
  with:
    target_branch: main
    type: production
```

--------------------------------

### Prepare Prerelease Version (GitHub Action)

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Instructions for using the 'Prepare Release' GitHub Action to create prerelease versions from the 'next' branch. This action handles version bumping and changelog updates.

```yaml
# Example workflow snippet (actual action configuration may vary)
- name: Prepare Release
  uses: twinfoundation/attestation/.github/workflows/prepare-release.yml@main
  with:
    branch: next
    semver_type: prerelease
```

--------------------------------

### attestationCreate()

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-service/docs/reference/functions/attestationCreate.md

Signs the data and returns the proof for attestation creation.

```APIDOC
## POST /attestationCreate

### Description
Signs the data and returns the proof for attestation creation.

### Method
POST

### Endpoint
/attestationCreate

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **httpRequestContext** (IHttpRequestContext) - Required - The request context for the API.
- **componentName** (string) - Required - The name of the component to use in the routes.
- **request** (IAttestationCreateRequest) - Required - The request object.

### Request Example
```json
{
  "httpRequestContext": { /* ... IHttpRequestContext object ... */ },
  "componentName": "exampleComponent",
  "request": { /* ... IAttestationCreateRequest object ... */ }
}
```

### Response
#### Success Response (200)
- **ICreatedResponse** (object) - The response object with additional http response properties.

#### Response Example
```json
{
  "status": 201,
  "data": { /* ... ICreatedResponse object ... */ },
  "headers": { /* ... http headers ... */ }
}
```
```

--------------------------------

### Get Class Name - TypeScript

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-connector-nft/docs/reference/classes/NftAttestationConnector.md

Returns the runtime class name of the NftAttestationConnector component. This method is part of the IAttestationConnector interface implementation.

```typescript
const className: string = connector.className();
```

--------------------------------

### CLI Class run() Method

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/reference/classes/CLI.md

Executes the CLI application with the provided arguments and options.

```APIDOC
## run(argv, localesDirectory?, options?)

### Description
Run the app with the given arguments and options.

### Method
`Promise<number>`

### Endpoint
N/A (Method within a class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Method Parameters
- **argv** (`string[]`) - Required - The process arguments.
- **localesDirectory?** (`string`) - Optional - The directory for the locales, defaults to relative to the script.
- **options?** (`object`) - Optional - Additional options.
  - **overrideOutputWidth** (`number`) - Optional - Override the output width.

### Returns
- `Promise<number>` - The exit code of the application.
```

--------------------------------

### Prepare Production Release (GitHub Action)

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Instructions for using the 'Prepare Release' GitHub Action on the 'main' branch to create production releases (major, minor, or patch). This action generates a PR with version bumps and changelog updates.

```yaml
# Example workflow snippet (actual action configuration may vary)
- name: Prepare Release
  uses: twinfoundation/attestation/.github/workflows/prepare-release.yml@main
  with:
    branch: main
    semver_type: major # or minor, patch
```

--------------------------------

### Initialize and Use AttestationService

Source: https://context7.com/twinfoundation/attestation/llms.txt

Shows how to set up and use the AttestationService for backend attestation operations. It requires registering connectors and can create and retrieve attestations.

```typescript
import { AttestationService } from "@twin.org/attestation-service";
import { AttestationConnectorFactory } from "@twin.org/attestation-models";
import { NftAttestationConnector } from "@twin.org/attestation-connector-nft";

// Register the NFT connector
AttestationConnectorFactory.register(
  "nft",
  () => new NftAttestationConnector({
    identityConnectorType: "identity",
    nftConnectorType: "nft",
    config: {
      tag: "MY-ATTESTATION"
    }
  })
);

// Create the service
const attestationService = new AttestationService({
  config: {
    defaultNamespace: "nft",
    verificationMethodId: "attestation-assertion"
  }
});

// Use the service
const id = await attestationService.create({
  "@context": "https://schema.org",
  "type": "Product",
  "name": "Organic Coffee Beans",
  "identifier": "SKU-12345"
});

const attestationInfo = await attestationService.get(id);
```

--------------------------------

### Get NFT Attestation Information - TypeScript

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-connector-nft/docs/reference/classes/NftAttestationConnector.md

Retrieves and verifies the details of a specific NFT attestation using its ID. Returns a promise that resolves with the attestation information.

```typescript
const attestationInfo: IAttestationInformation = await connector.get(attestationId);
```

--------------------------------

### Publish Prerelease Version (GitHub Action)

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Instructions for using the 'Publish Release' GitHub Action to publish prerelease packages to NPM with the 'next' tag and create GitHub releases marked as prerelease.

```yaml
# Example workflow snippet (actual action configuration may vary)
- name: Publish Release
  uses: twinfoundation/attestation/.github/workflows/publish-release.yml@main
  with:
    npm_tag: next
```

--------------------------------

### GET /attestation/{attestationId} - Get/Verify Attestation

Source: https://context7.com/twinfoundation/attestation/llms.txt

Retrieves and verifies an attestation by its ID. Returns the complete attestation information including verification status, proof, owner identity, and the original attested data.

```APIDOC
## GET /attestation/{attestationId}

### Description
Retrieves and verifies an attestation by its ID. Returns the complete attestation information including verification status, proof, owner identity, and the original attested data.

### Method
GET

### Endpoint
/attestation/{attestationId}

### Parameters
#### Path Parameters
- **attestationId** (string) - Required - The unique identifier of the attestation.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "https://localhost/attestation/attestation:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg==" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200 OK)
- **@context** (array) - The schema contexts.
- **type** (string) - The type of the information returned (e.g., "Information").
- **id** (string) - The unique identifier of the attestation.
- **dateCreated** (string) - The date and time the attestation was created.
- **ownerIdentity** (string) - The DID of the attestation owner.
- **holderIdentity** (string) - The DID of the current attestation holder.
- **attestationObject** (object) - The original attested JSON-LD object.
- **proof** (object) - The proof of the attestation.
  - **type** (string) - The type of proof (e.g., "JwtProof").
  - **value** (string) - The value of the proof.
- **verified** (boolean) - Indicates if the attestation has been verified.

#### Response Example
```json
{
  "@context": [
    "https://schema.twindev.org/attestation/",
    "https://schema.twindev.org/common/",
    "https://schema.org"
  ],
  "type": "Information",
  "id": "attestation:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg==",
  "dateCreated": "2024-06-18T13:34:51Z",
  "ownerIdentity": "did:iota:tst:0x8992c426116f21b2a4c7a2854300748d3e94a8ce089d5be62e11f105bd2a0f9e",
  "holderIdentity": "did:iota:tst:0x8992c426116f21b2a4c7a2854300748d3e94a8ce089d5be62e11f105bd2a0f9e",
  "attestationObject": {
    "@context": "https://schema.org",
    "type": "DigitalDocument",
    "name": "bill-of-lading",
    "mimeType": "application/pdf",
    "fingerprint": "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f"
  },
  "proof": {
    "type": "JwtProof",
    "value": "eyJraWQiOiJkaWQ6aW90YTp0c3Q6MHg4OTkyYzQyNjExNmYyMWIyYTRjN2EyODU0MzAwNzQ4ZDNlOTRhOGNlMDg5ZDViZTYyZTExZjEwNWJkMmEwZjllI2F0dGVzdGF0aW9uIiwidHlwIjoiSldUIiwiYWxnIjoiRWREU0EifQ..."
  },
  "verified": true
}
```
```

--------------------------------

### Transfer Attestation using CLI

Source: https://context7.com/twinfoundation/attestation/llms.txt

Explains how to transfer an existing attestation to a new holder using the CLI. It includes steps for funding the new holder's address, creating their identity, and executing the transfer command.

```bash
# Fund second address for new holder
twin-attestation faucet --load-env config.env --address !ADDRESS_1

# Create identity for new holder
twin-attestation identity-create --load-env config.env wallet.env --seed !SEED --controller !ADDRESS_1 --env identity2.env

# Transfer attestation to new holder
twin-attestation attestation-transfer \
  --load-env config.env wallet.env attestation.env identity2.env \
  --seed !SEED \
  --id !ATTESTATION_ID \
  --holder-address !ADDRESS_1 \
  --holder-identity !DID

# Verify transfer by getting attestation again
twin-attestation attestation-get --load-env config.env attestation.env --id !ATTESTATION_ID
# Now shows holderIdentity and transferred date
```

--------------------------------

### Initialize and Use AttestationRestClient

Source: https://context7.com/twinfoundation/attestation/llms.txt

Demonstrates how to initialize the AttestationRestClient, create, retrieve, transfer, and destroy attestations. It handles HTTP communication with the attestation REST API.

```typescript
import { AttestationRestClient } from "@twin.org/attestation-rest-client";

// Initialize the client
const client = new AttestationRestClient({
  endpoint: "https://attestation-api.example.com"
});

// Create an attestation
const attestationObject = {
  "@context": "https://schema.org",
  "type": "DigitalDocument",
  "name": "invoice-2024-001.pdf",
  "mimeType": "application/pdf",
  "fingerprint": "0xabc123..."
};

const attestationId = await client.create(attestationObject);
console.log("Created attestation:", attestationId);
// Output: attestation:iota:aW90YS1uZnQ6...

// Verify and retrieve attestation
const info = await client.get(attestationId);
console.log("Verified:", info.verified);
console.log("Owner:", info.ownerIdentity);
console.log("Data:", info.attestationObject);

// Transfer to new holder
await client.transfer(
  attestationId,
  "did:iota:tst:0x06ae1034f9f4af1b408a0b54e877bb476259666a14f221400d3746aecefa7105",
  "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv"
);

// Destroy attestation
await client.destroy(attestationId);
```

--------------------------------

### Update Next Branch After Production Release (GitHub Action)

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Instructions for using the 'Versions Prepare' GitHub Action on the 'next' branch to update its versions to reflect the latest published production version.

```yaml
# Example workflow snippet (actual action configuration may vary)
- name: Update Next Branch
  uses: twinfoundation/attestation/.github/workflows/versions-prepare.yml@main
  with:
    target_branch: next
```

--------------------------------

### CLI Class Constructor

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/reference/classes/CLI.md

Initializes a new instance of the CLI class. This constructor is inherited from CLIBase.

```APIDOC
## new CLI()

### Description
Initializes a new instance of the CLI class.

### Method
Constructor

### Parameters
None

### Returns
- `CLI` - An instance of the CLI class.

### Inherited from
`CLIBase.constructor`
```

--------------------------------

### Publish Production Release (GitHub Action)

Source: https://github.com/twinfoundation/attestation/blob/next/CONTRIBUTING.md

Instructions for using the 'Publish Release' GitHub Action to publish stable packages to NPM with the 'latest' tag and create stable GitHub releases.

```yaml
# Example workflow snippet (actual action configuration may vary)
- name: Publish Release
  uses: twinfoundation/attestation/.github/workflows/publish-release.yml@main
  with:
    npm_tag: latest
```

--------------------------------

### actionCommandAttestationTransfer

Source: https://github.com/twinfoundation/attestation/blob/next/apps/attestation-cli/docs/reference/functions/actionCommandAttestationTransfer.md

Initiates the attestation transfer process by executing the actionCommandAttestationTransfer function. This function requires detailed options including the seed for signing, the attestation ID, and the new holder's identity and address.

```APIDOC
## POST /attestation/transfer

### Description
Action the attestation transfer command. This endpoint facilitates the transfer of an attestation from one holder to another.

### Method
POST

### Endpoint
/attestation/transfer

### Parameters
#### Request Body
- **seed** (string) - Required - The seed required for signing by the issuer.
- **id** (string) - Required - The id of the attestation to transfer in urn format.
- **holderIdentity** (string) - Required - The new holder identity of the attestation.
- **holderAddress** (string) - Required - The new holder address of the attestation.
- **node** (string) - Required - The node URL.
- **network** (string) - Optional - The network to use for connector.
- **explorer** (string) - Optional - The explorer URL.

### Request Example
```json
{
  "seed": "your_seed_here",
  "id": "urn:uuid:your-attestation-id",
  "holderIdentity": "new_holder_identity",
  "holderAddress": "0xNewHolderAddress",
  "node": "https://your.node.url",
  "network": "mainnet",
  "explorer": "https://your.explorer.url"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the successful initiation of the attestation transfer.

#### Response Example
```json
{
  "message": "Attestation transfer initiated successfully."
}
```
```

--------------------------------

### IAttestationServiceConstructorOptions

Source: https://github.com/twinfoundation/attestation/blob/next/packages/attestation-service/docs/reference/interfaces/IAttestationServiceConstructorOptions.md

Details the properties available for configuring the attestation service constructor.

```APIDOC
## Interface: IAttestationServiceConstructorOptions

Options for the attestation service constructor.

### Properties

#### config

- **config** (IAttestationServiceConfig) - Optional - The configuration for the service.
```

--------------------------------

### Initialize and Use NftAttestationConnector

Source: https://context7.com/twinfoundation/attestation/llms.txt

Details the NftAttestationConnector for creating NFT-backed attestations on IOTA. It covers creating, verifying, transferring, and destroying attestations, requiring prior registration of identity and NFT connectors.

```typescript
import { NftAttestationConnector } from "@twin.org/attestation-connector-nft";
import { IdentityConnectorFactory } from "@twin.org/identity-models";
import { NftConnectorFactory } from "@twin.org/nft-models";

// Connectors must be registered first
// IdentityConnectorFactory.register("identity", () => new IotaIdentityConnector(...));
// NftConnectorFactory.register("nft", () => new IotaNftConnector(...));

const connector = new NftAttestationConnector({
  identityConnectorType: "identity",
  nftConnectorType: "nft",
  config: {
    tag: "TWIN-ATTESTATION"
  }
});

// Create attestation with controller identity and verification method
const attestationId = await connector.create(
  "did:iota:tst:0x8992c426116f21b2a4c7a2854300748d3e94a8ce089d5be62e11f105bd2a0f9e",
  "did:iota:tst:0x8992c426116f21b2a4c7a2854300748d3e94a8ce089d5be62e11f105bd2a0f9e#attestation",
  {
    "@context": "https://schema.org",
    "type": "DigitalDocument",
    "name": "certificate-of-origin",
    "fingerprint": "0xdef456..."
  }
);

// Verify attestation
const result = await connector.get(attestationId);
if (result.verified) {
  console.log("Attestation is valid");
  console.log("Created:", result.dateCreated);
  console.log("Owner:", result.ownerIdentity);
} else {
  console.log("Verification failed:", result.verificationFailure);
}

// Transfer to new holder
await connector.transfer(
  "did:iota:tst:0x8992c426116f21b2a4c7a2854300748d3e94a8ce089d5be62e11f105bd2a0f9e",
  attestationId,
  "did:iota:tst:0x06ae1034f9f4af1b408a0b54e877bb476259666a14f221400d3746aecefa7105",
  "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv"
);

// Destroy attestation (burns the NFT)
await connector.destroy(
  "did:iota:tst:0x8992c426116f21b2a4c7a2854300748d3e94a8ce089d5be62e11f105bd2a0f9e",
  attestationId
);
```