Key ConceptsDocument-Token Binding

Document-Token Binding

The core innovation that permanently links ERC tokens to real-world documents.

Overview

Document-Token Binding is Integra’s foundational architecture that creates a permanent, cryptographic link between blockchain tokens and the real-world documents they represent. Unlike traditional NFTs that store only metadata, Integra tokens are bidirectionally bound to their source documents, ensuring that every token can prove its authenticity and every document knows its associated tokens.

The Two-Layer Architecture

Layer 1: Document Registry

The Document Registry establishes permanent document identity:

struct Document {
    bytes32 integraHash;      // Unique document identifier
    bytes32 documentHash;     // SHA-256 of document content
    bytes32 referenceHash;    // IPFS CID or storage reference
    address owner;            // Document controller
    address tokenizer;        // Associated tokenizer contract
}

Key properties:

  • integraHash is permanent and unique
  • documentHash proves content hasn’t changed
  • One document can have multiple tokens (via ERC-1155)

Layer 2: Tokenizer Contracts

Tokenizers mint standard ERC tokens bound to documents:

// Bidirectional mapping in all tokenizers
mapping(bytes32 => uint256) public integraHashToTokenId;
mapping(uint256 => bytes32) public tokenIdToIntegraHash;

This ensures:

  • Every token knows its document (tokenIdToIntegraHash)
  • Every document knows its tokens (integraHashToTokenId)
  • The binding is immutable once established

How Binding Works

Registration Flow

1. User creates document
   ↓
2. Hash document content (SHA-256)
   ↓
3. Register in Document Registry
   ↓
4. Receive integraHash (unique ID)
   ↓
5. Tokenizer creates token slot
   ↓
6. Token permanently linked to integraHash

Verification Flow

1. Someone receives token
   ↓
2. Look up integraHash from token
   ↓
3. Query Document Registry
   ↓
4. Get documentHash and referenceHash
   ↓
5. Fetch document from storage
   ↓
6. Verify hash matches
   ↓
7. Document authenticity confirmed

The integraHash

Every document gets a unique identifier:

integraHash = keccak256(abi.encodePacked(
    documentHash,      // Content hash
    referenceHash,     // Storage reference
    msg.sender,        // Registrant
    block.timestamp    // Registration time
));

Properties:

  • Globally unique across all chains
  • Deterministic given inputs
  • Cannot be predicted before registration
  • Permanent and immutable

Why Binding Matters

Traditional NFTs

Token Metadata → {"image": "ipfs://...", "name": "..."}
                 ↑
                 Can be changed
                 No proof of underlying asset
                 Anyone can create fake

Integra Tokens

Token → integraHash → Document Registry → documentHash → Real Document
        ↑                                 ↑
        Permanent link                    Cryptographic proof
        Cannot be broken                  Content verified

Verifying Ownership

Simple Verification

// Get document info from token
const integraHash = await tokenizer.tokenIdToIntegraHash(tokenId);
const doc = await registry.getDocument(integraHash);
 
// Verify document content
const storedHash = doc.documentHash;
const actualHash = sha256(documentContent);
const isAuthentic = storedHash === actualHash;

Complete Verification

import { verifyDocument } from '@integra/sdk';
 
const result = await verifyDocument({
  tokenId,
  tokenizer: ownershipTokenizerAddress,
  documentContent,
});
 
console.log(result.isAuthentic);      // true/false
console.log(result.owner);            // Current owner
console.log(result.registrationDate); // When registered

Use Cases

Property Deeds

Property Deed PDF → documentHash → Registry → NFT
                                              ↓
Anyone can verify: "This NFT represents THIS specific deed"

Rental Agreements

Lease Agreement → documentHash → Registry → Landlord Token + Tenant Token
                                            ↓
Both parties can prove: "We are parties to THIS agreement"

Certificates

Diploma → documentHash → Registry → Soulbound Token
                                    ↓
Employer can verify: "This credential represents THIS diploma from THIS school"

Technical Deep Dive

Why Two Hashes?

documentHash: Proves the exact content

// SHA-256 of actual document bytes
bytes32 documentHash = sha256(documentContent);

referenceHash: Points to storage location

// IPFS CID where document is stored
bytes32 referenceHash = ipfsCIDToBytes32(cid);

Why both?

  • documentHash can verify ANY copy of the document
  • referenceHash tells you WHERE to get the document
  • Separation allows storage flexibility

Immutability Guarantees

Once a document is registered:

  1. integraHash cannot change - Derived from registration inputs
  2. documentHash cannot change - Stored immutably
  3. Token binding cannot change - Set once during claim
  4. Only ownership can transfer - As expected for property rights

Best Practices

Document Preparation

  1. Finalize document before registration
  2. Use consistent hashing algorithm (SHA-256)
  3. Store document in permanent storage (IPFS, Arweave)
  4. Keep local backup of original

Verification

  1. Always verify documentHash matches
  2. Check registration timestamp
  3. Verify tokenizer is legitimate
  4. Confirm owner identity through attestations

Related Documentation

7. Trust GraphOverview