METADATA_KEY_ALLOWLIST.md

0. Purpose

Define metadata strictness per canonical GovernanceRecordType.

1. Global Rules

• Metadata must be flat string -> string.
• No nested objects, arrays, null, or undefined.
• Keys must be ASCII.
• Max key length: 64.
• Max value length: 512.
• Max entries per record: 32.

2. RecordType Metadata Registry

ACCESS_DECISION

recordType: ACCESS_DECISION

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• reason
• comment
• ticketId
• origin
• quorumId
• voteRound
• ratifierId

POLICY_FREEZE

recordType: POLICY_FREEZE

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• policyVersion
• effectiveFrom
• description

TENDER_TRANSITION

recordType: TENDER_TRANSITION

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• fromState
• toState
• reason
• externalReference
• authDecisionEntryHash
• authDecisionPayloadHash

AUCTION_TRANSITION

recordType: AUCTION_TRANSITION

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• fromState
• toState
• bidReference
• externalReference
• authDecisionEntryHash
• authDecisionPayloadHash

SETTLEMENT_INTENT

recordType: SETTLEMENT_INTENT

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• agreementId
• externalReference
• memo
• requestId
• authDecisionEntryHash
• authDecisionPayloadHash
• authDecisionAction
• authDecisionPolicyHash

SETTLEMENT_EVENT

recordType: SETTLEMENT_EVENT

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• externalTxId
• providerReference
• note
• authDecisionEntryHash
• authDecisionPayloadHash
• authDecisionAction
• authDecisionPolicyHash

KES_VERSION_PROPOSED

recordType: KES_VERSION_PROPOSED

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• version
• versionHash
• prevVersionHash
• termsHash
• specHash
• costHash
• milestonesHash
• penaltyMatrixHash
• settlementProfileHash
• authDecisionEntryHash
• authDecisionPayloadHash
• chainPrevVersionHashExpected
• chainPrevVersionHashProvided
• description
• proposalReason
• authorId
• royaltyBps
• royaltyAddress

KES_VERSION_RATIFIED

recordType: KES_VERSION_RATIFIED

Required metadata keys:

• None (explicit)

Allowed optional metadata keys:

• version
• versionHash
• authDecisionEntryHash
• authDecisionPayloadHash
• ratificationNote

3. Enforcement Rule

1. Determine canonical recordType.
2. Reject metadata keys outside its allowlist.
3. Apply global metadata constraints.