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

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.

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

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:

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

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.

Related decisions

• 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