Docs Navigation
Current: Blockchain & Contracts
Open all sections
Overview
Getting Started
Role Guides
Compliance & Trust
Developer Reference
More
Home / Documentation / Blockchain & Contracts
Blockchain & Smart Contract Architecture
This page explains how Fractal's on-chain contracts are interconnected, how state moves across modules, and how platform actions map to contract calls.
This reference is based on the current contract suite in
packages/contracts. It documents current behavior, including optional modules that are deployed but not automatically wired into token transfer execution.System Interconnection Map
Identity Layer
IdentityRegistryStorage <-> IdentityRegistry <-> ClaimIssuer <-> Identity (per investor)
Operational Authority Layer
AgentRegistry (roles + any-role agent flag)
Tokenization Layer
TokenFactory -> FractalSecurityToken7518 (one per offering)
Distribution Audit Layer
FractalYieldDistributor (declaration record)
Optional Compliance Modules
TransferAgent (daily limits, cap table)
Rule144 (holding periods, affiliate limits)Contract Dependency Matrix
| Contract | Primary Role | Reads | Writes | Platform Interconnection |
|---|---|---|---|---|
Identity | Per-investor identity contract storing KYC claims | Claim IDs by topic | Claims and claim-issuer authorizations | Written by ClaimIssuer; referenced by IdentityRegistry |
ClaimIssuer | Verifies backend signatures and issues/revokes KYC claims | claimSigningKey, signature replay map | KYC claim status + expiry | Called by platform admin backend |
IdentityRegistry + Storage | Wallet-to-identity registry and KYC verification lookup | Stored identity mapping + ClaimIssuer verification | Identity mappings (via storage agent access) | Operational source of wallet identity status |
AgentRegistry | Permission root for operational agent wallets | Role state and any-role flag | Agent grants/revocations | Checked by token via `isAgent` |
TokenFactory | Deploys one token contract per offering | AgentRegistry and USDT address | Offering-to-token deployment records | Used by platform deploy pipeline |
FractalSecurityToken7518 | Core ERC-1155-based security token with compliance controls | Whitelist, tier, lock, freeze, cap, and partition state | Balances, locks, freeze flags, distribution claim state | Primary contract touched during mint/transfer/payout |
FractalYieldDistributor | Audit-only distribution declaration registry | Distribution records | Immutable distribution declaration entries | Complementary to token payout execution |
TransferAgent (optional module) | Transfer approval, daily limits, and holder registry | Daily volume and approvals | Cap table and transfer approval records | Standalone today; not auto-invoked by token transfer path |
Rule144 (optional module) | Holding-period and affiliate volume rule enforcement | Acquisition timestamps, affiliate flags | Quarterly volume + compliance config | Standalone today; can be queried by compliance layer |
Lifecycle Interconnection (Off-chain ↔ On-chain)
| Phase | Off-chain Responsibility | On-chain Calls | Expected Outcome |
|---|---|---|---|
| Investor identity onboarding | Backend verifies identity, signs claim payload, and initiates mapping of wallet to identity contract. | IdentityRegistryStorage.storeIdentity -> IdentityRegistry.registerWallet -> ClaimIssuer.issueKycClaim -> Identity.addClaim | Wallet can be resolved to an identity and a valid KYC claim with expiry. |
| Offering token deployment | Operator/admin triggers deploy with offering metadata and compliance caps. | TokenFactory.deployToken -> new FractalSecurityToken7518 -> setMaxBalance/setRetailCap -> ownership transfer | Dedicated token contract per offering with initial compliance parameters. |
| Allocation and issuance | Platform settles subscriptions and computes final token allocations. | token.batchWhitelist -> token.batchMint -> token.batchLockTokens (optional lockup) | Investor balances created on partition and lock schedules enforced. |
| Transfer lifecycle | UI/API initiates ERC-1155 transfer from wallet. | FractalSecurityToken7518._update -> _canTransfer checks -> transfer executes or reverts with reason | Transfer only succeeds when all compliance gates pass. |
| Distribution servicing | Operator funds token contract with payout token and computes distribution rounds. | token.createDistribution + token.payoutForDistribution OR token.batchPayout; optional audit declaration on FractalYieldDistributor.declareDistribution | Cashflow distribution execution plus immutable audit declaration trail. |
| Incident response | Compliance incident, lost wallet, or regulatory intervention raised. | freezeAddress / forceTransfer / recoveryAddress / restrictTransfer / pause | Controlled containment and recovery while preserving auditability. |
Deep Dive: FractalSecurityToken7518
State Model
- ERC-1155 partition model (default partition ID = 1).
- Per-partition supply tracking via internal
_totalSupply. - Array-based lock entries per account+partition with release timestamps.
- Address-level freeze flags and partition-level transfer restriction flags.
- Per-partition max balance and retail cap controls plus investor tier mapping.
Execution Paths
- Mint path:
batchMint(agent-only, whitelisted recipients). - Lock path:
lockTokens/batchLockTokens. - Transfer path: ERC-1155
_updatewith compliance checks. - Recovery path: freeze +
recoveryAddresslock-state migration. - Payout path: direct payout and distribution-linked pro-rata payout functions.
Transfer Compliance Execution Order
- Contract paused state
- Partition-level transfer restriction
- Sender and recipient freeze status
- Transferable (unlocked) balance sufficiency
- Sender and recipient whitelist status
- Max-balance cap for recipient (if configured)
- Retail-cap limit for tier-0 recipient (if configured)
- Voucher signature validation if compliance signer and voucher data are provided
Note on vouchers: voucher verification logic exists in _canTransfer when data is supplied. The default ERC-1155 transfer path calls _canTransfer(..., ""), so voucher-based checks are only active in flows that explicitly provide voucher payloads.
Current Wiring vs Optional Modules
Directly Wired Today
- Token contract authorization via
AgentRegistry.isAgent. - Token factory deployment pipeline and compliance cap initialization.
- On-token payout mechanics and distribution claim state.
- Identity stack (Identity + ClaimIssuer + Registry) for on-chain KYC state records.
Available but Not Auto-Enforced in Token Path
- TransferAgent daily-volume and explicit transfer approval checks.
- Rule144 holding-period and affiliate volume constraints.
- Automatic coupling between token payout execution and distributor declaration.
- Direct token call to IdentityRegistry during transfer checks (whitelist is the enforced gate today).
Audit and Reconciliation Event Trail
| Event | Emitted By | Why It Matters |
|---|---|---|
TokensMinted | FractalSecurityToken7518 | Allocation/issuance reconciliation with subscription IDs |
TokensLocked / TokensUnlocked | FractalSecurityToken7518 | Lockup evidence and release monitoring |
AddressFrozen / ForcedTransfer | FractalSecurityToken7518 | Compliance incident response and recovery tracking |
DistributionCreated / DistributionPayout | FractalSecurityToken7518 | Distribution execution and recipient payout trace |
DistributionDeclared | FractalYieldDistributor | Regulatory-friendly audit declaration of payout rounds |
AgentRoleGranted / AgentRoleRevoked | AgentRegistry | Operational authority changes over time |
KycClaimIssued / KycClaimRevoked | ClaimIssuer | Identity compliance state transitions |