# Parameters

Parameters are named values attached to a token or to the whole contract. They are a project's general
configuration layer: a program reads them, metadata is derived from them, and [effects](effects.md)
re-run when they change.

## Scopes

A parameter is set at one of two scopes:

- **Contract scope**: one value for the whole project.
- **Token scope**: a value for a single token.

When both scopes set the same key, the token value wins. This is how a project sets a default for every
token and overrides it for specific ones.

## Values

A parameter maps a `key` to bytes. A flag, `valueIsHash`, says how to read the value. When it is false,
the value is the literal. When it is true, the value is the `keccak256` of a larger value stored as one
on-chain blob, up to about 24 KB, read back with `tokenParamData` or `contractParamData`. A value larger
than that is held off-chain and referenced by a locator parameter.

Setting and clearing are distinct: an empty value is a valid value, and removing a key is a separate
operation, so a reader can tell "set to empty" from "unset." Each change records `updatedBy`, the
authorized address that made it, as on-chain provenance. The events are `TokenParamConfigured`,
`ContractParamConfigured`, and their `...Cleared` counterparts.

## Configurable parameters

A parameter becomes governed by attaching an on-chain schema. Because the schema is on-chain, any
frontend can build the configuration UI directly from the chain, with no off-chain definition. A per-key
schema declares:

- **Type**: one of `Bool`, `Select`, `Uint256Range`, `Int256Range`, `DecimalRange`, `HexColor`, `Timestamp`, `String`, or `Bytes`.
- **Authorization**: who may set the value. `Artist` (the contract owner), `TokenOwner`, or a specific `Address`, and OR-combinations of these.
- **Constraints**: the select options, or the min and max for a range.
- **Lock**: an optional timestamp after which the value can no longer change.

This is the model Art Blocks calls PostParams, with the same type set plus `Bytes`. A schema is set with
`ParamSchemaConfigured`.

The `TokenOwner` authorization honors delegate.xyz. A wallet the token owner has delegated to can
configure the parameter as the owner, so a token held in a vault is configured from a hot wallet. It is
on by default, set at deploy, and fail-closed: a missing or unexpected registry means "not delegated,"
never a revert. The registry is announced with `DelegateRegistrySet`.

## Hooks

Three project-level hooks transform on-chain state into results at points in the parameter lifecycle. A
hook operates on on-chain state only, so its behavior is deterministic and any resolver reproduces it.
In this version a hook is set as an address, and its logic is the implementation's.

- **configureHook**: runs when a parameter is written.
- **augmentHook**: runs at read time, computing results from the current on-chain state as metadata or token data is assembled. It can add keys or override stored ones, stores nothing, and emits no event. Because its output is computed live rather than stored, it reflects the latest state and can hold large derived values.
- **transferHook**: runs on an ownership change. A mint is a transfer from the zero address, so it also runs at mint. This is the mechanism for output that depends on the owner: on transfer it persists or derives a parameter and emits `TokenParamConfigured`. It goes beyond a write-time-only model such as PostParams, which has no transfer-triggered behavior.

Hooks are set with `HooksConfigured`.

## Canonical decode

Each type decodes to a canonical string, so a generator injects a consistent value: `HexColor` becomes
`#rrggbb`, `Timestamp` becomes a Unix time, `DecimalRange` is fixed-point with ten decimals, `Bytes`
becomes base64, and `String` is UTF-8. Parameters reach a program through
[token data](code-projects.md#tokendata), and a parameter change is a trigger for
[effects](effects.md).

## Seeds

A mint-time seed is a parameter with a dedicated source, so it is assigned once and settled. See
[seeds](code-projects.md#seeds).