> For the complete documentation index, see [llms.txt](https://decentralabs-2.gitbook.io/decentralabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://decentralabs-2.gitbook.io/decentralabs-docs/smart-contracts/concepts/labs.md).

# Labs and metadata

## On-chain lab record

Every laboratory is an ERC-721 token. Its token ID is the stable identifier used by reservations, access authorization, reputation and settlement.

| `LabBase` field | Protocol meaning                                                              |
| --------------- | ----------------------------------------------------------------------------- |
| `uri`           | URI of the off-chain lab metadata JSON.                                       |
| `price`         | Raw service-credit price per second, using `10,000,000` raw units per credit. |
| `accessURI`     | Provider routing or service endpoint identifier.                              |
| `accessKey`     | Public routing identifier; never a password or bearer token.                  |
| `createdAt`     | On-chain registration time.                                                   |
| `resourceType`  | `0` is exclusive physical/remote capacity; `1` is concurrent FMU capacity.    |

The metadata document is descriptive. Changing JSON at `uri` cannot change the stored price, resource type, owner or reservation state. Validate its schema and availability off-chain before publishing a lab.

## Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Created: addLabWithPucHash / addLabWithIntent
    Created --> Listed: listLab
    Created --> Deleted: deleteLab
    Listed --> Unlisted: unlistLab or transfer
    Unlisted --> Listed: listLab
    Unlisted --> Deleted: deleteLab
    Deleted --> [*]
```

This diagram describes only the on-chain lab lifecycle. `Unlisted` keeps the token and its obligations alive, while `Deleted` burns the token and removes the active lab record. Gateway content uses a separate local lifecycle (`PendingTombstone`, `PROCESSING`, `Tombstoned`, `PURGED`) and must not be described as an additional contract state.

`addAndListLabWithPucHash` combines creation and listing. The corresponding `*WithPucHash` functions atomically bind a non-zero creator PUC hash. The production facet does not compile or expose the legacy `addLab` and `addAndListLab` variants without PUC. Both direct and intent-based creation use the PUC-aware library paths. `getPucHash` deliberately remains available after a burn so off-chain deletion cleanup can authenticate the record.

Intent-based creation also requires a non-zero PUC hash. Subsequent `*WithIntent` lab changes check that hash in addition to consuming the signed intent. New or reconciled Diamonds therefore expose only the PUC-aware and intent-based creation paths.

## Listing, changes and deletion

`listLab` makes a lab eligible for new reservations and clears its stop-intake flag. `unlistLab` removes it from new intake while preserving existing reservation obligations. The legacy `listToken` and `unlistToken` selectors are intentionally forbidden from the production surface.

The owner may update URI, price and access identifiers. Changing `resourceType` is blocked while active bookings exist. Deletion is blocked while the lab has pending requests, active reservations or an unsettled receivable position; it unlists the lab, stops intake, burns the token and removes it from the active catalog only once those obligations are clear.

An ERC-721 transfer unlists the lab. Any non-terminal reservation (`PENDING`, `CONFIRMED` or `ACCESS_AUTHORIZED`) prevents transfer. Reservations are never reassigned to a new provider, so the current owner, Gateway and contractual responsibilities remain fixed for every active booking. Treat a transfer as an operational handover only after all reservation obligations are terminal.

## Capacity model

| Resource type | On-chain scheduling                                                       | Operational responsibility                                        |
| ------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `0`           | Inserts confirmed ranges into the interval calendar and rejects overlaps. | One exclusive physical or remote resource per booked range.       |
| `1`           | Does not apply the exclusive calendar conflict rule in the same way.      | FMU/runtime capacity and concurrency remain provider-side policy. |

The numeric on-chain value is authoritative. Metadata can describe capacity, but cannot turn an exclusive lab into a concurrent resource.

## Reservation commission

The platform commission on a paid reservation is 40% by default, leaving 60% of the lab price as the provider share. A particular lab may negotiate a lower rate based on its commercial circumstances, such as high equipment value, purchase or operating cost, size, capacity or specialized maintenance. The contract does not determine eligibility from metadata or lab attributes; after the platform and provider agree on a rate, a default admin records it with `setLabReservationCommission(labId, commissionBps)`. For example, `2,500` sets a 25% platform commission and a 75% provider share. Use `getLabReservationCommission` to read the effective rate and whether it is an override.

An override takes effect for reservations confirmed after the update. It has no automatic expiration; use `clearLabReservationCommission(labId)` to restore the 40% default when the negotiated term ends. Existing confirmed reservations retain the provider share stored at their confirmation. Fixed booking charges are separate from this commission: an internal own-lab booking always incurs four credits, while a free booking at an external lab incurs two credits.

## Reputation

`LabReputationFacet` exposes score, rating and event counters. A completed access-authorized reservation records a completion only when the required SessionStarted evidence exists. Provider-initiated cancellation records a separate cancellation event. Operators may use the read values for discovery, but they are not an authorization mechanism.