> For the complete documentation index, see [llms.txt](https://docs.nftx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nftx.io/art-blocks/project-wrapper.md).

# Project Wrapper

ArtBlocksProjectWrapper — wrapping and unwrapping Art Blocks tokens, the ID mapping, live metadata proxying, and the recovery path.

`ArtBlocksProjectWrapper` is the ERC-721 that stands in for a single Art Blocks project. One clone exists per `(core, projectId)` pair, deployed by the [Wrapper Factory](https://docs.nftx.io/art-blocks/wrapper-factory.md), and it holds the originals backing every wrapped token it has issued.

Custody is strictly 1:1. `totalSupply` always equals the number of originals the wrapper legitimately holds on the core — there is no path that mints a wrapped token without an original behind it.

## Token IDs

A wrapped token's ID is the underlying's **token number** — the part after the project prefix:

```
wrappedId = underlyingId % 1,000,000
```

Fidenza `78000123` wraps to `123`. Since each wrapper serves exactly one project, that number is unambiguous within it. Two helpers do the conversion for you:

```solidity
function underlyingTokenId(uint _wrappedId) returns (uint underlyingId_);
function wrappedTokenId(uint _underlyingId) returns (uint wrappedId_);
```

## Wrapping

Two supported routes, and they mint the same thing:

{% tabs %}
{% tab title="safeTransferFrom" %}
Send the original to the wrapper. The receiver hook mints your wrapped token in the same transaction.

```solidity
IERC721(core).safeTransferFrom(msg.sender, wrapper, 78000123);
// -> you now hold wrapped token 123
```

{% endtab %}

{% tab title="approve + wrap" %}
Approve the wrapper on the core, then have it pull the token.

```solidity
IERC721(core).setApprovalForAll(wrapper, true);
IArtBlocksProjectWrapper(wrapper).wrap(78000123);
// -> returns 123, minted to you
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Do **not** deposit with a plain `transferFrom`. It triggers no receiver callback, so no wrapped token is minted and the wrapper cannot tell who sent it. The token is not lost, but claiming it becomes a race — see [Recovery](#recovery).
{% endhint %}

## Unwrapping

```solidity
function unwrap(uint _wrappedId, address _recipient);
```

Burns your wrapped token and releases the original to `_recipient`. Always available, with no owner able to prevent it and no fee.

Two recipients are rejected outright: the zero address, which would destroy the wrapped token and strand the original, and the wrapper itself, which would re-enter the receiver hook and re-mint a wrapped token belonging to nobody. Both revert rather than silently doing something surprising.

## Recovery

```solidity
function recover(uint _underlyingId) returns (uint wrappedId_);
```

The escape hatch for an original that arrived via plain `transferFrom` and so never minted a wrapped token. It mints one to the caller, but only for a token the wrapper verifiably holds on the core with no wrapped counterpart already in existence.

{% hint style="danger" %}
Recovery is **first-caller-claims**. With no admin, there is no way for the contract to know who originally sent the token, so anyone may claim it. If you have deposited by plain `transferFrom`, call `recover` in the same transaction — otherwise you are racing whoever spots it first.
{% endhint %}

A token from a *different* project that gets forced into the wrapper can never be claimed here: the check is keyed on the wrapper's own project, never on what the caller asks for. Such tokens stay where they are, permanently. Treat them as donations.

## Metadata

Nothing is stored locally and nothing is snapshotted — every metadata call resolves against the core at read time, so any Art Blocks migration is reflected the moment it happens.

| Function        | Behaviour                                                                    |
| --------------- | ---------------------------------------------------------------------------- |
| `name()`        | The core's current project name, read live                                   |
| `symbol()`      | Derived as `wAB<projectId>-<CORE4HEX>` — e.g. `wAB78-D270` for Fidenza on V1 |
| `tokenURI(id)`  | Forwarded to the core's renderer for the underlying token                    |
| `tokenHash(id)` | The generative hash, resolved across core versions                           |

If the core reverts, that revert bubbles up unchanged. We would rather serve no metadata than fabricate it.

## Events

| Event                                                                                                           | Fired when                                          |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `TokenWrapped(address indexed _owner, uint256 indexed _wrappedId, uint256 _underlyingId)`                       | An original is wrapped                              |
| `TokenUnwrapped(address indexed _owner, address _recipient, uint256 indexed _wrappedId, uint256 _underlyingId)` | A wrapped token is burned and the original released |
| `TokenRecovered(address indexed _claimant, uint256 indexed _wrappedId, uint256 _underlyingId)`                  | An unbacked deposit is claimed                      |

Standard ERC-721 `Transfer` and `Approval` events fire as usual but are not indexed by the NFTX subgraph — the three events above already capture every mint and burn, and per-token ownership is out of the indexer's scope.

## Safety envelope

No owner, no pause, no fees, no upgrade path. Nobody — not the factory, not its owner, not us — can move a token out of a wrapper except its holder, by unwrapping.

The one trust assumption is the core itself: the wrapper proxies metadata from it and depends on it to report transfers truthfully. Both `wrap` and `unwrap` assert ownership on the core *after* the transfer, so a core that lies about having moved a token reverts loudly instead of leaving an unbacked wrapped token behind. A misbehaving core can still degrade the wrapper bound to it, but it can reach no other wrapper and not the factory.
