Entity Relationships

Core Insight: API mode and ChainSecured mode aren’t a toggle in the code — they’re an emergent property of how you configure the same system. The only things that vary are who owns the account (a Lit-managed credential vs a SAFE or EOA you control) and what scopes the API keys have. The contracts don’t know or care.

Entity Boundaries

The system spans four distinct trust boundaries. Understanding what lives where is essential to reasoning about security.

User / External

Entity	Description
Account Owner	Top-level identity. An address on Base that can do everything. A SAFE or EOA you control (ChainSecured mode), or a Lit-managed credential (API mode). Ultimate authority.
API Key (Private Key)	User holds the key locally. Sent to TEE over HTTPS per-request. TEE hashes it (keccak256) and checks that hash’s scopes on-chain.
SAFE / Governance	Optional. Multisig, timelocks, voting. Submits txs directly to chain for structural changes — TEE not involved.

TEE Enclave (Phala / dstack)

Entity	Description
Root Key	Master secret managed by Phala’s KMS. Only approved TEE build images can derive from it. Never leaves the enclave.
Key Derivation	Signing key + symmetric encryption key derived transiently from root key using derivation path ID. Never persisted.
Auth Verification	Hashes the API key → reads on-chain scopes → checks group membership of action CID + PKP → allows or rejects.
Sandbox Execution	Runs the Lit Action code sent with the request in a sandboxed JS environment with access to derived key material. Returns result to caller. The TEE doesn’t fetch code from IPFS.
TX Relay	Convenience relay for management operations on API-mode accounts. TEE checks scopes, then signs and submits tx to Base on user’s behalf. The contract rejects relayed writes to a ChainSecured account.

On-Chain (Base)

Entity	Description
Account Contract	Registers the owner address and the account’s `managed` flag. All permissions flow from this. Writes need `msg.sender == owner`, or the TEE relay when the account is in API mode.
API Key Registry	On-chain mapping of key hashes → scopes. Includes per-group scope bindings. Owner-managed.
PKP Registry	List of PKP derivation path IDs owned by the account. PKPs are created here, then referenced by Groups.
Groups	Permission policies binding `{PKP IDs, Action CIDs}`. “Who can execute” is on the API key, not the group.

IPFS (Content-addressed)

Entity	Description
Lit Actions	Immutable JS, referenced by its IPFS CID. You can pin it to IPFS so others can audit it; the TEE runs the copy sent with the request. Not owned by anyone — public, reusable, content-addressed. Like npm packages.

USER / EXTERNAL                ON-CHAIN (BASE)             TEE ENCLAVE
─────────────────────────────  ──────────────────────────  ──────────────────────────────
Account Owner                  Account Contract             Root Key
 EOA / SAFE / Lit-managed   ──▶  owner address registered    master secret, never exported
      │ owns                                                      │ derives
      │                        API Key Registry             Auth + Key Derivation
API Key (private key)       ──▶  key hash → scopes mapping ◀──   verify scopes, derive keys
 Held by user, sent/request                                       │ provides keys
      │ sent over HTTPS            │ reads                        │
      └──────────────────────────▶ TEE                    Sandbox Execution
                                   │                        runs Lit Actions w/ key material
                                  PKP Registry                    │ code sent with request
                                   derivation path IDs            ▼
                                      │ referenced         Lit Actions (by CID)
                                  Groups               ◀──   Immutable JS, public CIDs
                                   {PKP refs, ACIDs}
                                      │ CID ref
                                  TX Relay (API mode only)
                                   signs + submits mgmt txs

Execution Flow (Inside the TEE)

Step	Action	Who
1	User sends API key + the action code + `"run it with pkp_001"` over HTTPS. The TEE hashes the code to get its CID, `QmABC`	`user → tee`
2	TEE hashes the API key (keccak256 of the key string)	`inside tee`
3	TEE reads the API Key Registry on Base — does this key hash have `execute` scope? On which groups?	`tee → chain read`
4	TEE checks: is there a group this key can execute on where QmABC is a listed action AND pkp_001 is a listed PKP?	`tee → chain read`
5	If authorized → run the QmABC code from the request in the sandbox → derive pkp_001 key material from root key when the action asks for it → return result	`inside tee`
✕ Reject	If any check fails → reject the request. No key material is derived.	—

Management Paths

There are two paths for making structural changes (creating groups, adding PKPs, updating scopes):

Path A: Via TEE Relay (convenience)

TEE checks scopes and submits the transaction on the user’s behalf. API-mode accounts only.

User + API Key  →  TEE (verify scopes)  →  Permissions Contract

Path B: Direct to Chain (ChainSecured mode)

Owner submits transactions directly — TEE is not involved. The only write path for a ChainSecured account.

SAFE / EOA  →  Permissions Contract

API Key Scopes

Scope	Allows	Type
`execute`	Invoke Lit Actions with PKPs	per-group
`pkp:create`	Create new PKPs in the account’s registry	account-wide
`group:create`	Create new groups	account-wide
`group:delete`	Delete groups	account-wide
`group:manageActions`	Add / remove action CIDs in a group	per-group
`group:addPkp`	Add PKP references to a group	per-group
`group:removePkp`	Remove PKP references from a group	per-group

Permission Matrix

The API Key column applies to API-mode accounts, where the TEE relays the call. On a ChainSecured account an API key can only invoke actions; every other row is an owner transaction.

Operation	Owner	API Key	Scope Required
Invoke action + PKP	✓	✓	`execute(group_id)`
Create PKP	✓	✓	`pkp:create`
Create group	✓	✓	`group:create`
Delete group	✓	✓	`group:delete`
Add/remove actions	✓	✓	`group:manageActions(group_id)`
Add PKPs to group	✓	✓	`group:addPkp(group_id)`
Remove PKPs from group	✓	✓	`group:removePkp(group_id)`
Add / revoke API key	✓	✕	owner only
Update API key scopes	✓	✕	owner only
Transfer ownership	✓	✕	owner only

Configuration Comparison

The same system, two very different security postures — determined by who the owner is, whether the account is managed (API mode) or not (ChainSecured mode), and what scopes the keys carry.

API Mode

Fast iteration, broad scopes, managed recovery


Owner	A Lit-managed credential
API Key	`dev_key` with execution and group 1 management: `execute(*)`, `pkp:create`, `group:create`, `group:delete`, `group:manageActions(group_1)`, `group:addPkp(group_1)`, `group:removePkp(group_1)`
Effect	Developer executes actions and manages group 1 via HTTP. The owner grants explicit management permissions for additional groups. Recovery = re-authenticating to the dashboard.

ChainSecured Mode

Auditable governance, restricted scopes, SAFE multisig


Owner	3-of-5 SAFE multisig on Base
API Keys	`server_key` → `execute(group_1)` only. Management scopes would have no effect, because the contract rejects writes from the TEE to a ChainSecured account.
Effect	Day-to-day execution via `server_key`. Every change (PKPs, groups, actions, keys) is a SAFE transaction. Leaked key blast radius is minimal.

Guides

Management

Lit Actions

Lit Triggers