Decision records · ADR-019

ADR-019: Capabilities in the standard, policy in profiles

A REX Core already gives implementations the tools that regulated trade needs: freezing and forced transfers (ERC 7943, ADR 003, ADR 012), pause, eligibility and the AREX:SANCTIONED code, attestations with trusted issuer

**Proposed** (2026-10-23). The two normative clarifications it brings (§3.5 originRef, §6 revocation) are MUST-level changes and follow the major-change rule of [GOVERNANCE.md](../GOVERNANCE.md)

Document ID: ADR-019
Date: 2026-10-23
Source: docs/adr/ADR-019.md

The standard fixes what exists and is guaranteed (roles, events, data shapes, revocation and pause semantics, privacy rules); who may use a capability, whether it is on, and which lists or authorities apply live in a versioned policy profile per jurisdiction and per organization, so a change of law is a profile update, never a new contract or a new standard version.

Field	Value
ID	ADR-019
Subject area	Scope of the standard, governance
Status	Proposed (2026-10-23). The two normative clarifications it brings (§3.5 `originRef`, §6 revocation) are MUST-level changes and follow the major-change rule of GOVERNANCE.md
Date	2026-10-23
Owners	A-REX Contributors; requested by the A-REX Platform (standard parity, owner decisions D3, D7, D8, D9 and D11, decided 2026-10-23)
Related requirements	AREX-CORE §3.5 (metadata, `originRef`), §4 (enforcement), §6 (attestations), §7 (codes), §8 (security considerations)
Supersedes / superseded by	— (amended 2026-10-23, see Amendment)

Context

A-REX Core already gives implementations the tools that regulated trade needs: freezing and forced transfers (ERC-7943, ADR-003, ADR-012), pause, eligibility and the AREX:SANCTIONED code, attestations with trusted issuers per topic, and a ban on personal data in originRef (ADR-008). What it does not say, and was being asked to say, is how they are used: who holds the enforcement role, who may pause a token, which sanctions lists a company screens against, who may withdraw a certificate.

The answers differ by jurisdiction and change with the law. Brazil applies the UN Security Council lists through Lei 13.810/2019; the United States applies OFAC; EU member states apply the EU consolidated list; the United Kingdom applies OFSI. Courts, recall authorities and data-protection authorities each set their own conditions. A regulated group may want stricter rules for its companies than the law requires. If any of this were written into the standard, every change of a list or a law would become a new version of the standard, or a new contract, and a token deployed in one country would carry another country's policy. ADR-013 already keeps the standard neutral on legal classification for the same reason.

Some things, on the other hand, must be the same everywhere, or the standard guarantees nothing: what a revocation means and who can make it, what pause stops and what it lets through, which data may never reach a public ledger.

Issue

Which rules belong in the normative text of A-REX Core, and which belong in policy that implementers configure per jurisdiction and per organization?

Assumptions

Implementations that serve regulated markets keep jurisdiction data (lists, authorities, legal references) outside the token and update it on their own schedule. The A-REX Platform keeps it in @arex/jurisdictions, versioned with effective dates like the regulations it encodes, and lets organizations and companies inherit, lock or tighten settings (its ORG-MODEL §3 classes I, I-lock, I-tight and C). Other implementations will keep their own.
Relying parties (buyers, auditors, indexers, other tokens) read A-REX data without knowing which profile the issuer applied. What they rely on has to be in the standard.

Constraints

ADR-001: only the specification and the interfaces are normative.
ADR-013: the standard takes no position on legal classification.
GOVERNANCE.md: a new or changed MUST is a major change.
Data that reaches a public ledger can never be erased (ADR-008).

Alternatives considered

Alternative	For	Against	Outcome
Write policy into the standard (for example "the enforcement role MUST be a 2-of-n multisig", "issuers MUST screen OFAC")	one rule for every deployment	wrong for most jurisdictions; every change of law is a major version; the standard would take legal positions ADR-013 refuses	Rejected
Leave everything, semantics included, to implementations	maximum freedom	a relying party cannot tell what a revocation or a pause means on a given token; harm to personal data on a public ledger cannot be undone afterwards	Rejected
Encode policy in contracts, one hook or token variant per jurisdiction	enforced on-chain	a list or law change means a new deployment, an audit and a migration; a token carries the policy of where it was first deployed	Rejected
Capabilities and their semantics in the standard; who, whether and which in versioned policy profiles	the guarantee is the same everywhere; policy changes as fast as the law	each implementation maintains its profiles; profiles are not checked by the conformance suite	Proposed

Decision (proposed)

The principle:

The standard fixes WHAT exists and is guaranteed: roles, events, data shapes, revocation and pause semantics, privacy rules. It changes rarely and is versioned.
WHO may use a capability, WHETHER it is on, and WHICH lists or authorities apply, lives in a policy profile. That is per jurisdiction, in @arex/jurisdictions, versioned with dates like regulations, and per org/company through the ORG-MODEL §3 classes (I, I-lock, I-tight, C).
A law or market change becomes a data/profile update, never a new contract or a new standard version.

(@arex/jurisdictions and ORG-MODEL are the A-REX Platform's; for this standard a profile is whatever an implementation uses to hold the same policy.)

What that puts on each side, with the decisions that prompted it:

Topic	Normative in the standard	In a policy profile
Origin privacy (D3)	`originRef` MUST NOT contain raw coordinates or natural-person identifiers and MUST NOT be derived from location (coordinates, plot geometry, or any hash or encoding of them); §3.5, ADR-008	which reference an issuer uses (a random reference, an EUDR due-diligence statement reference, a national registry identifier); where geolocation goes off-chain (for the EUDR, the EU Information System) and whether it is shared downstream
Freeze and forced transfer (D7)	`setFrozenTokens`, `forcedTransfer`, `Frozen`, `ForcedTransfer`, a dedicated role, the hook pipeline with `OP_FORCED_TRANSFER`, separation from administration; §4, §8, ADR-003, ADR-012	whether the role may be enabled at all (required or forbidden), who holds it (signers, threshold, whether a service provider may co-sign), which legal reference each use must carry (court order, recall id, authority request), whom to notify
Pause (D8)	what `pause` stops, `AREX:PAUSED`, forced transfers allowed while paused; §4, §7, ADR-012	who may pause and unpause, the confirmation and reason required, who is notified and how often, whether an organization locks it for its companies
Sanctions (D9)	the code `AREX:SANCTIONED` and the eligibility semantics of `canSend` / `canReceive`; §4, §7	which official lists apply (UN, OFAC, EU, OFSI, or a combination), how they are kept current, and that a person confirms a match before an account is marked
Attestation revocation (D11)	only the issuer of an attestation, or a revoker it delegated, may revoke it; `isAttested` semantics; trusted issuers per topic; §6	which issuers a token trusts per topic (the token's administrator decides); how an operator records that it disputes a certificate (off-chain, informative note in §6)

Normative changes made with this record (AREX-CORE.md and erc/erc-draft.md):

§3.5: originRef MUST NOT be derived from location (coordinates, plot geometry, or any hash or encoding of them). ADR-008 already rejected a hash of the coordinates; the rule now says so in the specification, and the earlier suggestion of a truncated geohash is withdrawn.
§6: only the issuer of an attestation, or a revoker the issuer delegated, may revoke it; an administrative role of the token or of the attestation contract may not. This matches W3C Verifiable Credential status lists, where only the issuer sets a credential's status, and ERC-3643 claim issuers, which revoke the claims they signed on their own claim issuer contract. An informative note says that an operator may mark a certificate disputed off-chain.

Argument

A relying party needs to know what a revocation, a pause or an originRef means on any conformant token, wherever it was deployed; that is what a standard is for, and it is cheap to keep stable because semantics rarely change. Who acts and under which law changes often and differs by place; keeping it in dated, versioned profile data lets an implementation follow a new sanctions regulation or a court's practice the day it applies, without asking every token holder to accept a new contract and without a major version of the standard. The two normative changes are the cases where leaving it to policy would break the guarantee: a location-derived originRef cannot be taken back once published, and a certificate that the token's administrator can withdraw is no longer the issuer's statement.

Consequences

Positive

A change of law (a new list, a new authority, a new legal basis) is a profile update.
The same token and the same reference contracts serve every jurisdiction.
Relying parties can depend on revocation, pause and privacy semantics without knowing the issuer's profile.

Negative

Profiles are not normative and the conformance suite does not check them; a relying party cannot tell from the token alone which profile was applied.
Every implementation maintains its own profiles, with their effective dates and upkeep.
The §6 change makes the reference ARexAttestations (arex-contracts), which lets ATTEST_ADMIN_ROLE revoke any attestation, non-conformant until that path is removed or replaced by a delegation the issuer grants.

Obligations it creates

arex-contracts: remove the administrator revoke path of ARexAttestations.revokeAttestation, or replace it with a revoker delegated by the issuer, and test it.
Implementations stop issuing originRef values derived from location. Values already on-chain cannot be erased; implementations mark them as legacy and document it.
A future informative document may describe a profile format; it is not part of this decision.

Implementation and evidence

What	Where
Normative text	AREX-CORE.md §3.5 (`originRef`) and §6 (revocation); the same in erc/erc-draft.md (`node scripts/check-erc-sync.mjs`)
Interface comment	contracts/IARexAttest.sol `revokeAttestation`
First consumer	A-REX Platform, `docs/STANDARD-PARITY.md` "Owner decisions" D1–D11; profiles in `packages/jurisdictions`
Reference implementation	pending in arex-contracts (`ARexAttestations.revokeAttestation`)

Amendment 2026-10-23: administrative revoke SHOULD NOT in 2.x, MUST NOT from 3.0

The sections above are the decision as proposed on 2026-10-23 and are left unchanged. This amendment softens one part of it for the 2.x line.

What changed. The Decision made the §6 rule a MUST: an administrative role of the token or of the attestation contract MUST NOT be able to revoke an attestation it did not issue. Released reference cores are immutable. Every arex-contracts release up to and including 2.0.0-alpha.4 ships an ARexAttestations whose ATTEST_ADMIN_ROLE can revoke any attestation, and the tokens deployed from them cannot be changed in place. A MUST in 2.x would make all of them non-conformant at once, and under GOVERNANCE.md it is a major change that cannot be accepted while fewer than two independent implementers exist.

Amended rule (AREX-CORE.md §6, erc/erc-draft.md and the NatSpec of IARexAttest.revokeAttestation).

The issuer MUST be able to revoke its attestation.
A revoker the issuer delegated MAY be able to revoke it; how an issuer delegates stays implementation-defined.
An administrative role SHOULD NOT be able to revoke an attestation it did not issue in 2.x, and MUST NOT from version 3.0. A 2.x implementation that keeps an administrative revoke SHOULD document it to issuers and relying parties.
Any other caller MUST be rejected.

The NatSpec change is a comment only; no signature, event, error or interface id changes. The §3.5 part of this record is not affected.

Reference implementation (arex-contracts branch attest-issuer-only, not released). ARexAttestations.revokeAttestation accepts only the issuer, or a revoker the issuer delegated, and reverts with ARexNotRevoker for anyone else, ATTEST_ADMIN_ROLE included. The role is kept for setTrustedIssuer. Delegation is an extension of the reference contract, outside IARexAttest, so the interface id is unchanged: setRevoker(revoker, allowed) acts for the caller over every attestation it issued, isRevoker(issuer, revoker) reads it, and RevokerUpdated records it. Releases up to 2.0.0-alpha.4 keep the admin revoke path; platforms that conform to this amendment never call it and revoke only as the issuer or as a revoker the issuer delegated.

Consequences.

Positive: existing deployments stay conformant to 2.x. The issuer-only rule is in the text now and becomes binding at 3.0 by changing the keyword only.
Negative: until 3.0 a relying party cannot assume from the standard alone that a token's administrator cannot withdraw a certificate. It has to check the implementation (the reference from the attest-issuer-only fix on) or the token's documentation.

Evidence. In arex-contracts, branch attest-issuer-only: test/foundry/ARexAttestationsRevoke.t.sol (test_IssuerRevokes, test_DelegatedRevokerRevokes, test_AdminCannotRevokeAttestationItDidNotIssue, test_StrangerCannotRevoke, testFuzz_NoOtherCallerRevokes, test_InterfaceIdUnchanged) and test/standard/ARexToken.test.js: only the issuer or a revoker it delegated can revoke; ATTEST_ADMIN_ROLE cannot. The conformance suite has no clause for the rule yet; in 2.x it would be a SHOULD clause.

ADR-001: only the specification and the interfaces are normative
ADR-003: freezing, forced transfers and eligibility from ERC-7943
ADR-008: no personal data on-chain
ADR-009: attestations in a companion contract
ADR-012: forced transfers while paused, through the hooks
ADR-013: no position on legal classification