Authorization
DALP authorizes asset operations through platform RBAC, organisation context, wallet verification for browser-session writes, and on-chain roles for the contract action being requested.
DALP authorization answers two questions before an asset operation can continue:
- Can this caller use the protected console or API route for the active organisation?
- Does the submitting wallet or service have the on-chain role required for the contract action?
The page helps platform owners, compliance teams, and auditors separate console access from blockchain authority. Organisation-owner access is not enough to mint, burn, pause, recover, or change token policy.
Related security references:
System context
Authorization architecture
DALP separates platform access from blockchain authority.
Platform RBAC is organisation-scoped. It decides whether a signed-in user, API credential, or service can reach a protected console or API route for the active organisation.
On-chain authorization is role-scoped. It decides whether the submitting wallet or contract address can perform the requested token, identity, compliance, or system operation.
How the authority chain works:
- The caller authenticates through a platform session or API credential.
- DALP resolves the active organisation and resource scope for the request.
- The protected route checks the required platform permission before it prepares a write operation.
- For browser-session blockchain writes, DALP also requires wallet verification through PIN, secret code, or OTP before signing can proceed.
- The contract action still needs the matching on-chain role. DALP indexes role events such as
RoleGrantedandRoleRevokedso the console can render the current permission state.
Key invariant: platform access does not grant blockchain authority by itself. Organisation owner or admin access can let a user administer the platform, but minting, burning, pausing, recovering wallets, changing token policy, or managing compliance still requires the relevant on-chain role and the applicable signing gate.
Dual-layer permissions
Every blockchain operation requires both off-chain and on-chain authorization. Missing either layer results in denial.
Key invariant: Read operations require a valid session and any route-specific read permission. Write operations require the platform permission for the route and the on-chain role for the contract action.
How platform RBAC maps to system actions
Platform RBAC is organisation-scoped. The platform permission check controls who can use DALP's protected console and API routes before an on-chain transaction is built. Platform RBAC does not grant blockchain authority by itself.
| Platform role | DALP permissions | Typical use |
|---|---|---|
| admin | Organisation management; settings read, list, upsert, remove, and global theme; system read, list, create, and operate; exchange-rate read/list; webhook management and compliance recall | Platform administration and sensitive system operations |
| owner | Organisation-owner permissions; user list/get/update; settings read, list, upsert, and remove; system read, list, and create; exchange-rate read/list; webhook management and compliance recall | Organisation ownership, user administration, and configuration |
| member | Organisation-member permissions; settings read/list; system read/list; exchange-rate read/list | Standard operator access with narrower permissions |
For protected routes, DALP checks the required platform permission against the signed-in account or active organisation. If the platform permission is missing, the request stops before any contract call is prepared. If the platform check passes, the requested blockchain action still needs the matching on-chain role.
Role taxonomy
DALP uses three platform roles and 28 current on-chain access-control roles. The on-chain role map has three operating groups: system operating roles, asset operating roles, and module roles.
| Layer | Scope | Count | Roles |
|---|---|---|---|
| 1. Platform access | Off-chain organisation access | 3 | owner, admin, member |
| 2. System operations | On-chain system-wide authority | 11 | admin, auditor, systemManager, tokenManager, complianceManager, claimPolicyManager, organisationIdentityManager, claimIssuer, identityManager, feedsManager, gasManager |
| 3. Asset operations | On-chain per-token authority | 7 | admin, governance, supplyManagement, custodian, emergency, saleAdmin, fundsManager |
| 4. Module authority | On-chain contract-module access | 10 | systemModule, identityRegistryModule, tokenFactoryRegistryModule, tokenFactoryModule, addonRegistryModule, addonModule, trustedIssuersMetaRegistryModule, complianceEngineModule, tokenComplianceFactoryModule, tokenIdentityRegistryFactoryModule |
Default administration exists at both system and asset scope. Grant the admin role only where the person or service needs authority.
Layer 1: Platform access
Platform roles are organisation-scoped and managed by DALP platform access controls.
| Role | Capabilities |
|---|---|
| owner | Full administrative access, role assignment, organisation configuration |
| admin | User management and platform configuration |
| member | Standard operations based on assigned permissions |
Layer 2: System operations
System operating roles apply across the system. Assign them to people or services that administer shared system capabilities, identity setup, token deployment, compliance policy, feeds, gas, or audit review.
| Role | Responsibilities |
|---|---|
| admin | Grant and revoke system-scoped roles |
| auditor | View permissions, identities, audit logs, and system state |
| systemManager | Bootstrap systems, manage upgrades, and register factories or modules |
| tokenManager | Deploy and configure tokens |
| complianceManager | Register compliance modules, configure global settings, manage bypass |
| claimPolicyManager | Manage trusted issuers and claim topics |
| organisationIdentityManager | Manage organisation identity claims and keys |
| claimIssuer | Create and attach claims to identity contracts |
| identityManager | Register and recover identities, manage user onboarding |
| feedsManager | Register, replace, and remove feeds in the feeds directory |
| gasManager | Manage paymaster deposits and paymaster configuration |
Layer 3: Asset operations
Asset roles are scoped to a specific token contract. A wallet can hold a role on one asset without receiving authority over another asset.
| Role | Responsibilities |
|---|---|
| admin (DEFAULT_ADMIN_ROLE) | Grant and revoke all other roles for that asset |
| governance | Configure identity registry, compliance modules, features, metadata |
| supplyManagement | Mint, burn, batch operations, set supply cap |
| custodian | Freeze/unfreeze, forced transfers, forced wallet recovery |
| emergency | Pause/unpause operations, trigger emergency-only early maturity, recover ERC20 held by the asset |
| saleAdmin | Manage token sale configuration and lifecycle |
| fundsManager | Withdraw funds from token sales |
Custodian and emergency controls
Custodian and emergency roles both protect an asset after issuance, but they answer different operating problems.
| Control family | Required authority | What changes on-chain | Typical operator decision |
|---|---|---|---|
| Address freeze or unfreeze | custodian | Marks a holder address as frozen or active for the asset | Whether a holder should be blocked or released under the asset's operating policy |
| Partial balance freeze | custodian | Freezes or unfreezes a specific amount of a holder's balance | Whether only part of a holding should be locked while the remaining balance stays usable |
| Forced transfer | custodian | Moves tokens from one registered holder address to another | Whether a legal, recovery, or compliance exception justifies a custodian-only transfer |
| Forced wallet recovery | custodian; registered replacement-wallet link | Reassigns a holder's asset access through a custodian-only recovery path | Whether the holder recovery evidence and replacement-wallet link are complete |
| Forced conversion | custodian | Converts a holder's convertible position through the custodian-only conversion path | Whether the conversion terms justify custodian execution for a specific holder |
| Standard wallet recovery | API route: emergency; contract: registered replacement wallet | Recovers tokens from a lost wallet to the caller's registered replacement wallet | Whether the lost-wallet recovery should proceed through the standard recovery path |
| Asset pause or unpause | emergency | Stops or resumes token operations through the asset pause state | Whether the asset should be stopped during an incident or released after the incident ends |
| Emergency early maturity | emergency | Marks a bond-style asset mature before its configured maturity date | Whether an incident or lifecycle override justifies emergency-only early maturity |
| ERC20 asset-contract recovery | emergency | Transfers ERC20 held by the asset contract to the selected recipient | Whether asset-held ERC20 should be released under the asset's recovery policy |
Use the Custodian role for holder-specific exceptions such as forced transfers, forced recoveries, and forced conversions. Use the Emergency role for asset-level stop actions, lifecycle overrides, ERC20 recovery from the asset contract, and the standard lost-wallet recovery API route. Standard lost-wallet recovery also depends on the registered replacement wallet at contract execution. Neither role is a substitute for the platform permission, wallet verification, custody-signing policy, or external approval record required by your deployment.
For the operator workflow, see Forced transfer and Pause or unpause an asset. For the custody and compliance policy split, see Compliance and custody split.
Layer 4: Module authority
Module roles are assigned to contract addresses that DALP uses to operate shared registries, factories, and trusted issuer infrastructure. Treat these as system wiring roles, not ordinary human operating roles.
| Role | Responsibilities |
|---|---|
| systemModule | Manage system modules |
| identityRegistryModule | Modify identity registry storage |
| tokenFactoryRegistryModule | Administer token factory module access |
| tokenFactoryModule | Register token contracts in the compliance allowlist |
| addonRegistryModule | Administer add-on module access |
| addonModule | Register add-on instance contracts |
| trustedIssuersMetaRegistryModule | Add trusted issuers to the registry |
| complianceEngineModule | Deploy compliance module instances for token compliance |
| tokenComplianceFactoryModule | Create per-token compliance proxies and assign engine access |
| tokenIdentityRegistryFactoryModule | Deploy per-token identity registries |
Role scopes for common operator personas
DALP separates platform membership from on-chain operating authority. A user can sign in to the platform without having every on-chain role, and a wallet can hold one role without inheriting unrelated asset or system powers.
| Persona or responsibility | Typical scope | Roles to assign |
|---|---|---|
| Platform administrator | Organisation setup and user access | Platform owner or admin, plus on-chain roles only for the administrator's system or asset responsibilities |
| System operator | System configuration, upgrades, factories, shared modules, and paymaster operations | systemManager, with narrower roles such as tokenManager, complianceManager, identityManager, feedsManager, or gasManager when the operator only owns one domain |
| Compliance operator | Trusted issuers, claim topics, compliance modules, and user eligibility controls | complianceManager, claimPolicyManager, organisationIdentityManager, claimIssuer, or identityManager, depending on whether the user configures policy, manages organisation identity claims and keys, issues claims, or manages identities |
| Asset operations team | Day-to-day actions for one tokenized asset | Per-asset roles such as governance, supplyManagement, custodian, emergency, saleAdmin, or fundsManager on that asset |
| Auditor or regulator view | Review permissions, identities, audit logs, and system state without operating the asset | Platform access plus the system-level auditor role; do not grant write roles unless the same person also performs operations |
Use the narrowest role set that matches the person's responsibility. System people roles apply across the system. Per-asset roles apply only to the specific token contract.
Segregation of duties for administration
DALP supports segregation of duties by splitting account access, platform permissions, system roles, and per-asset roles. A policy administrator, contract administrator, compliance operator, and issuance operator can be assigned different role sets so one persona does not automatically inherit the others.
| Control area | DALP mechanism | Practical separation |
|---|---|---|
| Account and session access | Sign-in session, active organisation context, optional account 2FA, and fresh-session checks for sensitive account operations | Proves who is using the console before authorization starts |
| Console and API access | Organisation-scoped platform permissions checked before protected routes continue | Lets platform owners and admins grant console capabilities without granting every on-chain role |
| Policy and compliance administration | complianceManager, claimPolicyManager, organisationIdentityManager, claimIssuer, and identityManager system roles | Separates compliance module configuration, claim-topic policy, organisation identity operations, claim issuance, and identity operations |
| Contract and asset administration | Per-asset governance, supplyManagement, custodian, emergency, saleAdmin, and fundsManager roles | Separates asset configuration, mint and burn authority, custody actions, emergency controls, sale administration, and fund withdrawal |
| Audit and review | auditor role and indexed role events | Gives reviewers visibility without granting write authority |
A deployment can enforce independent control by assigning these roles to separate accounts, wallets, custody policies, or approval groups. DALP does not treat organisation owner or admin as automatic permission to mint, burn, recover wallets, or change token policy. Those actions still need the matching on-chain role and, for browser-initiated blockchain writes, wallet verification before signing.
DALP does not impose a universal rule that one human can never hold two roles. If your operating model forbids the same person from changing policy and executing issuance, encode that rule in role assignment, custody approval policy, and operational review. The platform gives the separate permissions and failure gates; the deployment policy decides who may hold them together.
Per-asset permission matrix (summary)
| Action | Required role | Asset-specific notes |
|---|---|---|
| Set OnchainID / identity registry / compliance | governance | All asset types |
| Set features / metadata | governance | DALPAsset only (Configurable extension) |
| Set yield schedule / mature bond | governance | Bond only |
| Mint / burn / batch operations | supplyManagement | RealEstate and PreciousMetal: no burn |
| Set supply cap | supplyManagement | Bond and RealEstate only |
| Freeze / forced transfer / recovery | custodian | All asset types |
| Pause / unpause / recover ERC20 | emergency | All asset types |
| Configure / manage token sale | saleAdmin | Assets with sale addon |
| Withdraw sale funds | fundsManager | Assets with sale addon |
See Legacy-Equivalent Presets for per-instrument feature and compliance configuration across all seven asset types.
Multi-tenant architecture
The platform supports configurable multi-tenancy through organisation-scoped membership and permissions.
- Single tenant: all users operate inside one organisation, and organisation creation is blocked after the first organisation exists.
- Multi tenant: separate organizations have isolated membership, roles, assets, compliance records, and audit trails.
Tenant boundary: every API request resolves organisation context before protected data or actions continue. That organisation context is separate from on-chain role checks, so a user needs both the right tenant-scoped platform permission and the relevant on-chain role for write operations.
Authentication
DALP authenticates browser operators and API integrations before authorization and wallet verification decide what each request may do.
Identity and compliance
How DALP links participants, wallets, and OnchainID identities, keeps evidence off chain, trusts claim issuers by topic, and evaluates claims before regulated token operations execute.