Decision records · ADR-009
ADR-009: Attestations implemented in a companion contract
The reference implements IARexAttest in a separate ARexAttestations contract bound to one token, because embedding it pushed the token over the EIP-170 size limit.
- Document ID
- ADR-009
- Date
- 2026-09-21
- Source
- docs/adr/ADR-009.md
| Field | Value |
|---|---|
| ID | ADR-009 |
| Subject area | Deployment |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | FR-11, NFR-07 (SDD §3) |
| Supersedes / superseded by | — |
Context
Layer 3 of the standard, IARexAttest, is a SHOULD: a token may implement it itself or through a companion. Implementing it inside ARexToken took the token to about 25.5 KB of deployed bytecode, above the 24,576-byte EIP-170 limit that every EVM chain enforces.
Issue
Where should the reference implementation put the attestation registry so that the token remains deployable everywhere?
Assumptions
- Layer 3 may be implemented by a companion contract (normative text).
- Hooks and integrators can be told the registry address at deployment.
Constraints
- Every contract must fit EIP-170 (NFR-07).
- No
delegatecalllibraries (they complicate upgrades and audits).
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
External libraries through delegatecall | Keeps one address | Harder upgrades and audits; linked-library deployment | Rejected |
| Remove features from the token | Fits in one contract | Loses functionality the standard needs | Rejected |
A companion ARexAttestations bound to the token | Small, separately auditable, no size pressure | Two addresses to publish | Accepted |
Decision
ARexAttestations implements IARexAttest for exactly one token, checks that the batch exists on that token, and manages trusted issuers per topic under ATTEST_ADMIN_ROLE. Hooks such as AttestationHook read it directly. The token does not report IARexAttest in supportsInterface.
Argument
Attestations are consulted by hooks and integrators, not by the token's own transfer logic, so separating them costs no functionality and removes the size constraint for good.
Consequences
Positive
- The token stays at 24,136 bytes.
- The registry can be audited, and in the future replaced, independently.
Negative
- Integrators must discover the registry address from deployment metadata, not from the token.
Obligations it creates
- Deployment manifests publish both addresses (the deployment scripts print them).
Implementation and evidence
| What | Where |
|---|---|
| Registry | contracts/reference/core/ARexAttestations.sol |
| Trust, revocation, expiry, gating | test/standard/ARexToken.test.js: only trusted issuers can attest; revocation and expiry are honoured, AttestationHook gates transfers on a per-commodity attestation |
| Size | ARexToken 24,136 bytes (SDD §15) |