03. RealSeal

Real-Seal

Real-Seal provides document and text signing with blockchain verification, enabling tamper-proof digital signatures with public/private sharing.

Overview

Purpose: Sign and verify documents and texts using blockchain-anchored cryptographic signatures.

Key Features:

  • Upload and sign PDF, Word, images, and other documents

  • Sign text content and URLs

  • Blockchain anchoring for tamper-proof verification

  • Share signed documents with specific addresses

  • Create public verification links

Location: src/packages/real-seal/


Documents

Upload Document

Upload a document to Real-Seal for signing.

Endpoint: POST /real-seal/documents/

Authentication: Required (JWT)

Request:

Request Body: FormData

  • file (required): Document file

  • title (optional): Custom title for the document

Supported File Types:

  • PDF: .pdf

  • Word: .doc, .docx

  • Excel: .xls, .xlsx

  • Images: .jpg, .jpeg, .png, .gif, .webp

  • Text: .txt, .md

  • Archives: .zip

File Size Limit: Check configuration via GET /real-seal/config

Response:

Example Response:

Usage:


Get Document Metadata

Fetch metadata for a specific document.

Endpoint: GET /real-seal/documents/{id}

Authentication: Required (JWT)

Parameters:

  • id (path): Document UUID

Implementation:

Response: DocumentMetadata object (see Upload Document)

Access Control:

  • Owner can always access

  • Shared addresses can access if in authorized_addresses

  • Public access only if public_enabled: true


Download Document

Download the actual document file.

Endpoint: GET /real-seal/documents/{id}/download

Authentication: Required (JWT)

Parameters:

  • id (path): Document UUID

Implementation:

Response: File blob with original content type

Usage:


List User Documents

List all documents owned by or shared with the authenticated user.

Endpoint: GET /real-seal/documents?with_shared_addresses=true

Authentication: Required (JWT)

Implementation:

Response:

Usage:


List Documents with Filters

List documents with advanced filtering options.

Endpoint: GET /real-seal/documents?scope=owned&...

Authentication: Required (JWT)

Query Parameters:

  • scope (optional): 'owned' or 'shared'

  • start_date (optional): ISO 8601 date string

  • end_date (optional): ISO 8601 date string

  • min_size (optional): Minimum file size in bytes

  • max_size (optional): Maximum file size in bytes

  • file_format (optional): MIME type filter

  • search (optional): Search in filename/title

Implementation:

Example Usage:


Sign Document

Sign a document with a blockchain-anchored cryptographic signature.

Endpoint: POST /real-seal/documents/{id}/sign

Authentication: Required (JWT)

Parameters:

  • id (path): Document UUID

Request:

Request Body:

Response: Updated DocumentMetadata with signature

Signature Process:

  1. Download document and calculate Blake2 hash

  2. Construct signing message: REAL_SEAL::SIGN_DOCUMENT::${documentHash}::${timestamp}

  3. Sign the message with wallet

  4. Submit signature, hash, and timestamp to backend

  5. Backend verifies signature matches owner and message

  6. Document marked as signed

Implementation:


Verify Document Signature

Verify that a document's signature is valid and hasn't been tampered with.

Endpoint: GET /real-seal/documents/{id}/verify

Authentication: Not required for public documents

Parameters:

  • id (path): Document UUID

Implementation:

Response:

Example Response:

Usage:


Share Document

Share a document with specific Gen6 addresses.

Endpoint: POST /real-seal/documents/{id}/share

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Document UUID

Request:

Request Body:

Response: Updated DocumentMetadata with authorized_addresses

Behavior:

  • If addresses is empty/undefined, shares with everyone

  • If addresses has values, shares only with those addresses

  • Replaces existing share list (not additive)

Usage:


Unshare Document

Revoke document access for specific addresses.

Endpoint: DELETE /real-seal/documents/{id}/share

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Document UUID

Request:

Request Body:

Response: Updated DocumentMetadata


Generate a public link for document verification without authentication.

Endpoint: POST /real-seal/documents/{id}/public

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Document UUID

Implementation:

Response:

Example Response:

Usage:


Disable public access to a document.

Endpoint: DELETE /real-seal/documents/{id}/public

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Document UUID

Implementation:

Response: Updated DocumentMetadata with public_enabled: false


Retrieve the current public link for a document (if enabled).

Endpoint: GET /real-seal/documents/{id}/public

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Document UUID

Implementation:

Response: PublicLinkResponse or 404 if not enabled


Delete Document

Permanently delete a document.

Endpoint: DELETE /real-seal/documents/{id}

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Document UUID

Implementation:

Response: 204 No Content

Warning: This action is permanent and cannot be undone.

Usage:


Public Document Access

Get Public Document Metadata

Access document metadata via public token (no authentication required).

Endpoint: GET /real-seal/public/{token}/metadata

Authentication: Not required

Parameters:

  • token (path): Public access token from public URL

Implementation:

Response: DocumentMetadata object

Usage:


Download Public Document

Download document via public token (no authentication required).

Endpoint: GET /real-seal/public/{token}/download

Authentication: Not required

Parameters:

  • token (path): Public access token

Implementation:

Response: File blob


Text Signing

Create Text to Sign

Create a text or URL entry for signing.

Endpoint: POST /real-seal/texts/

Authentication: Required (JWT)

Request:

Request Body:

Response:


Get Text Metadata

Fetch metadata for a specific text entry.

Endpoint: GET /real-seal/texts/{id}

Authentication: Required (JWT)

Parameters:

  • id (path): Text UUID

Implementation:

Response: TextMetadata object


Sign Text

Sign a text entry with a cryptographic signature.

Endpoint: POST /real-seal/texts/{id}/sign

Authentication: Required (JWT)

Parameters:

  • id (path): Text UUID

Request:

Signing Process:


Create and Sign Text (Single Call)

Create and sign a text in one API call.

Endpoint: POST /real-seal/texts/sign

Authentication: Required (JWT)

Request:

Usage: Convenience method to avoid separate create + sign calls.


List Text Entries

List text entries with optional filters.

Endpoint: GET /real-seal/texts/

Authentication: Required (JWT)

Query Parameters:

  • scope: 'owned' or 'shared'

  • type: 'text' or 'url'

  • start_date, end_date: Date range

  • search: Search in content/title

Implementation:

Response:


Delete Text

Delete a text entry.

Endpoint: DELETE /real-seal/texts/{id}

Authentication: Required (JWT - must be owner)

Parameters:

  • id (path): Text UUID

Implementation:


Text entries support the same sharing and public link features as documents:

  • POST /real-seal/texts/{id}/share - Share with addresses

  • DELETE /real-seal/texts/{id}/share - Revoke sharing

  • POST /real-seal/texts/{id}/public - Create public link

  • DELETE /real-seal/texts/{id}/public - Revoke public link

  • GET /real-seal/texts/{id}/public - Get public link

APIs identical to document endpoints (see above).


Query Account Balance

Check account balance for transaction fee estimation.

Blockchain Query: api.query.system.account()

Parameters:

  • address: SS58-355 encoded account address

Implementation:

Response: Account info including free balance for fee calculation

Usage: Automatically checked before document upload to ensure sufficient balance for blockchain transactions.


Blockchain Integration

Store Document Hash On-Chain

Anchor the document hash on the blockchain for immutable verification.

Extrinsic: api.tx.dataRegistry.storeData()

Parameters:

  • projectId: 886 (Real-Seal project ID)

  • dataHash: Blake2 hash of document content

Implementation:

Complete Signing Flow:


Configuration

Get Real-Seal Config

Retrieve Real-Seal configuration (e.g., max file size).

Endpoint: GET /real-seal/config

Authentication: Not required

Implementation:

Response:

Example Response:


Query Keys

TanStack Query Keys:


Next Steps

  • Ncrypt - Send encrypted messages

  • Identity - Link signed documents to verified identities

Last updated

Was this helpful?