Frontend Services

The frontend services handle all business logic and blockchain interactions. They provide clean abstractions over the Sui blockchain, Walrus storage, and encryption systems.

Service Overview

Core Services

• documents.service.ts: Document indexer and metadata management
• marketplace.service.ts: Marketplace transaction builders and listing management
• vault.service.ts: Regular document vault (hash-based verification)
• zk-vault.service.ts: Zero-knowledge document vault (commitment-based verification)
• walrus.service.ts: Decentralized storage operations
• seal.service.ts: Threshold encryption using Mysten Seal
• zkproof.service.ts: Zero-knowledge proof generation
• zk-commitments.service.ts: ZK commitment utilities

Documents Service

File: services/documents.service.ts

Document indexer and metadata management from the indexer API.

Functions

getAllDocuments()

Fetch all registered documents from indexer.

async function getAllDocuments(): Promise<Document[]>

getDocumentByTokenAddress(tokenAddress: string)

Get document metadata by RWA token address.

async function getDocumentByTokenAddress(
  tokenAddress: string
): Promise<Document | null>

getDocumentVersions(tokenAddress: string)

Retrieve version history for a document.

async function getDocumentVersions(
  tokenAddress: string
): Promise<DocumentVersion[]>

getDocumentAuditors(tokenAddress: string)

Get list of endorsing auditors.

async function getDocumentAuditors(
  tokenAddress: string
): Promise<Address[]>

formatTimestamp(timestamp: bigint)

Format blockchain timestamps to human-readable format.

function formatTimestamp(timestamp: bigint): string

getWalrusUrl(blobId: string)

Generate Walrus blob download URL.

function getWalrusUrl(blobId: string): string

Marketplace Service

File: services/marketplace.service.ts

Marketplace transaction builders and listing management.

Functions

buildListTx(marketplaceId: string, tokenId: string, price: bigint)

Create listing transaction.

function buildListTx(
  marketplaceId: string,
  tokenId: string,
  price: bigint
): TransactionBlock

buildUpdatePriceTx(marketplaceId: string, listingId: string, newPrice: bigint)

Update listing price transaction.

function buildUpdatePriceTx(
  marketplaceId: string,
  listingId: string,
  newPrice: bigint
): TransactionBlock

buildCancelTx(marketplaceId: string, listingId: string)

Cancel listing transaction.

function buildCancelTx(
  marketplaceId: string,
  listingId: string
): TransactionBlock

buildBuyTx(marketplaceId: string, listingId: string, paymentCoin: string, price: bigint)

Purchase token transaction.

function buildBuyTx(
  marketplaceId: string,
  listingId: string,
  paymentCoin: string,
  price: bigint
): TransactionBlock

getActiveListings()

Fetch all active marketplace listings from indexer.

async function getActiveListings(): Promise<Listing[]>

getListingById(listingId: string)

Get specific listing details.

async function getListingById(listingId: string): Promise<Listing | null>

Vault Service

File: services/vault.service.ts

Regular document vault (hash-based verification).

Functions

buildRegisterTx(...)

Register document with hash on-chain.

function buildRegisterTx(
  registryId: string,
  tokenAddress: string,
  blobId: string,
  blobObjectId: string,
  fileHash: Uint8Array,
  description: string,
  accessKey: Uint8Array,
  metadata: object
): TransactionBlock

buildAppendVersionTx(...)

Add new document version.

function buildAppendVersionTx(
  registryId: string,
  tokenAddress: string,
  blobId: string,
  blobObjectId: string,
  fileHash: Uint8Array,
  description: string,
  accessKey: Uint8Array,
  metadata: object
): TransactionBlock

buildEndorseTx(registryId: string, tokenAddress: string)

Endorse document as auditor.

function buildEndorseTx(
  registryId: string,
  tokenAddress: string
): TransactionBlock

getLatestBlobId(registryId: string, tokenAddress: string)

Get current Walrus blob ID from on-chain registry.

async function getLatestBlobId(
  registryId: string,
  tokenAddress: string
): Promise<string>

getLatestFileHash(registryId: string, tokenAddress: string)

Get on-chain document hash.

async function getLatestFileHash(
  registryId: string,
  tokenAddress: string
): Promise<Uint8Array>

getAccessKey(registryId: string, tokenId: string, tokenAddress: string)

Retrieve access key (with ownership verification).

async function getAccessKey(
  registryId: string,
  tokenId: string,
  tokenAddress: string
): Promise<Uint8Array>

ZK Vault Service

File: services/zk-vault.service.ts

Zero-knowledge document vault (commitment-based verification).

Functions

buildRegisterZKCommitmentTx(...)

Register document with ZK commitment.

function buildRegisterZKCommitmentTx(
  zkRegistryId: string,
  tokenAddress: string,
  commitment: Uint8Array,
  verifyingKeyId: string,
  accessKey: Uint8Array
): TransactionBlock

buildVerifyZKProofTx(...)

Verify Groth16 proof on-chain.

function buildVerifyZKProofTx(
  zkRegistryId: string,
  tokenAddress: string,
  verifyingKey: Uint8Array,
  publicInputs: Uint8Array[][],
  proofPoints: Uint8Array,
  curveId: number
): TransactionBlock

hasCommitment(zkRegistryId: string, tokenAddress: string)

Check if ZK commitment exists.

async function hasCommitment(
  zkRegistryId: string,
  tokenAddress: string
): Promise<boolean>

getCommitment(zkRegistryId: string, tokenAddress: string)

Retrieve ZK commitment from chain.

async function getCommitment(
  zkRegistryId: string,
  tokenAddress: string
): Promise<ZKCommitment>

getAccessKey(zkRegistryId: string, tokenId: string, tokenAddress: string)

Retrieve access key (with ownership verification).

async function getAccessKey(
  zkRegistryId: string,
  tokenId: string,
  tokenAddress: string
): Promise<Uint8Array>

Walrus Service

File: services/walrus.service.ts

Decentralized storage operations using Walrus Protocol.

Functions

upload(data: Uint8Array)

Upload encrypted data to Walrus network.

async function upload(data: Uint8Array): Promise<{
  blobId: string;
  objectId: string;
}>

download(blobId: string)

Download data from Walrus by blob ID.

async function download(blobId: string): Promise<Uint8Array>

Seal Service

File: services/seal.service.ts

Threshold encryption using Mysten Seal.

Functions

encrypt(data: Uint8Array, accessPolicy: SealAccessPolicy)

Threshold encryption with access policies.

async function encrypt(
  data: Uint8Array,
  accessPolicy: SealAccessPolicy
): Promise<EncryptedData>

decrypt(encryptedData: EncryptedData)

Threshold decryption for authorized users.

async function decrypt(
  encryptedData: EncryptedData
): Promise<Uint8Array>

Access Policies

Token ownership policies for access control:

interface SealAccessPolicy {
  type: 'token_ownership';
  tokenAddress: string;
  threshold: number; // Default: 2/3 servers
}

ZK Proof Service

File: services/zkproof.service.ts

Zero-knowledge proof generation utilities.

Functions

generateDocumentCommitment(documentHash: Uint8Array, ownerAddress: string, nonce: Uint8Array)

Create ZK commitment from document hash.

function generateDocumentCommitment(
  documentHash: Uint8Array,
  ownerAddress: string,
  nonce: Uint8Array
): Uint8Array

generateOwnershipProof(...)

Generate proof of token ownership.

async function generateOwnershipProof(
  documentHash: Uint8Array,
  ownerAddress: string,
  nonce: Uint8Array,
  commitment: Uint8Array
): Promise<ZKProof>

Uses Poseidon hash function for ZK-friendly commitments.

ZK Commitments Service

File: services/zk-commitments.service.ts

ZK commitment utilities and helpers.

Functions

• Commitment generation helpers
• Owner hash computation
• Public input preparation
• Verification utilities

Usage Patterns

Registering a Document

// 1. Encrypt document
const encrypted = await encryptDocument(file, key);
 
// 2. Upload to Walrus
const { blobId, objectId } = await walrusService.upload(encrypted);
 
// 3. Compute hash
const hash = await computeHash(file);
 
// 4. Build transaction
const tx = vaultService.buildRegisterTx(
  registryId,
  tokenAddress,
  blobId,
  objectId,
  hash,
  description,
  accessKey,
  metadata
);
 
// 5. Execute transaction
await suiClient.signAndExecuteTransactionBlock({
  signer: keypair,
  transactionBlock: tx,
});

Trading on Marketplace

// 1. Build buy transaction
const tx = marketplaceService.buildBuyTx(
  marketplaceId,
  listingId,
  paymentCoinId,
  price
);
 
// 2. Execute transaction
const result = await suiClient.signAndExecuteTransactionBlock({
  signer: keypair,
  transactionBlock: tx,
});
 
// 3. Access key automatically available to new owner

Error Handling

Services include comprehensive error handling:

• Transaction validation
• Network error handling
• Ownership verification
• Hash/commitment verification

Next Steps

• Learn about User Flows
• Review Smart Contracts
• Check Examples