ARC-1643 - Security Token Document Registry

ARCs/arc-1643.md

@@ -0,0 +1,86 @@
+---
+arc: 1643
+title: Security Token Document Registry
+description: Standardized document metadata (URI + hash) registry for security tokens
+author: Ludovit Scholtz (@scholtz)
+discussions-to: https://github.com/algorandfoundation/ARCs/discussions
+status: Draft
+type: Standards Track
+category: Interface
+sub-category: Application
+created: 2025-09-03
+requires: 88
+replaces:
+---
+
+# ARC-1643: Security Token Document Registry
+
+## Abstract
+
+ARC-1643 standardizes on-chain references to off-chain documents (e.g., Offering Memorandum, Subscription Agreement, Financial Reports) tied to a security token implementation. Each document is stored as a record containing a name, URI, cryptographic hash, and timestamp to ensure integrity and auditability.
+
+## Motivation
+
+Regulated assets require discoverable, tamper-evident links to disclosure documents. Ethereum's ERC-1643 provides a model; this ARC adapts it to Algorand using global state and boxes for scalable metadata while minimizing transaction costs and enabling rich indexing.
+
+## Specification
+
+### Document Record
+
+Fields:
+
+- `name: bytes` (key)
+- `uri: bytes` (UTF-8; may be IPFS, HTTPS)
+- `hash: bytes32` (SHA-256 or multihash subset; implementers SHOULD clarify algorithm)
+- `timestamp: uint64` (block round or Unix timestamp if oracle-supplied)
+- `doc_type: uint64` (optional classification enum)
+
+### Storage
+
+Each document stored in a box named `doc-<hashPrefix>` or `doc-<nameHash>`. A global index box `doc-index` maintains msgpack array of (name, hash) pairs for enumeration.
+
+### Methods (ABI Recommendations)
+
+ARC-1643 methods are namespaced with `arc1643_`.
+
+- `arc1643_set_document(name: bytes32, uri: string, hash: bytes32)`
+- `arc1643_get_document(name: bytes32) -> (uri: string, hash: bytes32, timestamp: uint64)`
+- `arc1643_remove_document(name: bytes32) -> (void)`
+- `arc1643_get_all_documents() -> (names: bytes32[])`
+
+`arc1643_set_document` MUST overwrite existing and update index; timestamp set to current round unless provided by trusted oracle.
+
+### Events (Logs)
+
+- Tag 0x21 arc1643_document_updated | name | uri | hash
+- Tag 0x22 arc1643_document_removed | name | uri | hash
+
+### Integrity
+
+Clients SHOULD verify retrieved document content hash matches stored `hash`. URIs SHOULD support secure transport (HTTPS / IPFS). Multi-hash encoding MAY be used; if so, store canonical multihash bytes rather than raw digest.
+
+### Pagination (Optional)
+
+If document count large, support `arc1643_document_names_page(cursor: uint64, limit: uint64)`.
+
+## Security Considerations
+
+- Only issuer/governance may set documents.
+- Avoid storing sensitive document content on-chain; store only references + hash.
+- Ensure name collisions are handled deterministically (overwrite or reject; this ARC chooses overwrite).
+
+## Backwards Compatibility
+
+Can be integrated into an ARC-1400 unified application or standalone for general-purpose asset document registries.
+
+## Reference Implementation
+
+[arc1643.algo.ts](https://github.com/scholtz/arc-1400/blob/main/projects/arc-1400/smart_contracts/security_token/arc1643.algo.ts)
+
+## Rationale
+
+Simplified CSV index removal in reference impl reduces on-chain mutation complexity while preserving future extensibility by pagination extension.
+
+## Copyright
+
+CC0 1.0 Universal.