Vaultia Protocol — Agent SKILL

What Vaultia is

Vaultia is a constrained execution layer for AI-driven finance, built on LUKSO Universal Profiles.

The protocol is designed around a clear ownership boundary:

• Humans create root vaults, configure budget policies, set spending limits, and decide which agents to authorize.
• Agents operate inside those vaults — executing transactions, managing workflows, and optionally coordinating sub-vaults — but only within the permissions and budget caps the human owner committed on-chain ahead of time.

An agent can never exceed the permissions or budget limits of the vault that authorized it. If an owner delegates vault management to an agent, any sub-vaults that agent creates or manages must stay within the root vault's overall constraints. There is no privilege escalation path.

Current deployment state (beta)

The protocol is live on LUKSO testnet. The following capabilities are operational today:

Capability	Status
Root vault deployment via the app	✅ Live
Budget, merchant, and expiration policies	✅ Live
Assigning a curated agent to a vault	✅ Live
Assigning a custom agent address to a vault	✅ Live
LSP6 KeyManager + PolicyEngine execution path	✅ Live
AgentCoordinator registration and roles	✅ Live
TaskScheduler (keeper-driven automation)	✅ Live
VaultDirectory and SharedBudgetPool contracts	✅ Deployed
Agent creating sub-vaults autonomously via UI	🔜 Next release
Agent-to-agent delegation via the app	🔜 Next release

Curated agents are the recommended starting point during this phase. These are vetted agents with known execution paths and tested permission profiles. You can evaluate and test them without configuring your own agent infrastructure.

Custom agent addresses can be assigned from the vault creation success screen or the vault management panel at any time.

If a capability is not marked as live above, do not assume it is available.

Mental model

Agents do not own vault funds.
They act through permissions that a human owner configures ahead of time.

In the current LUKSO flow, a payment is only successful when all of these layers agree:

1. the LSP6 KeyManager accepts the caller and payload
2. the AgentSafe forwards the action through the safe execution path
3. the PolicyEngine validates every active policy

If any of those checks fails, execution reverts.

What is true today (technical)

• The canonical live execution path is LSP6KeyManager.execute(...) -> AgentSafe.execute(...) -> PolicyEngine.validate(...).
• AgentCoordinator exists and supports registerAgent, assignRole, grantCapability, delegation depth, and delegated deployment metadata.
• AgentCoordinator roles and capabilities do not replace LSP6 permissions. Live execution still depends on KeyManager permissions and AllowedCalls configuration.
• PolicyEngine has a vault-wide pause switch via setPaused(bool).
• TaskScheduler is passive. It never self-executes; an off-chain keeper must poll and call executeTask(taskId).
• New TaskScheduler deployments start with keeper whitelist enforcement enabled and the deployer whitelisted by default.
• VaultDirectory exists as a metadata/discovery layer for vault hierarchies, but it is not part of the default root deployment path in scripts/deploy.ts.

ROLE A: Agent operating inside a configured vault

Preconditions

Before you try to execute anything, verify all of the following:

• You have a controller address that the vault KeyManager recognizes.
• That controller has the required LSP6 permissions for the intended action.
• If the vault uses strict payment permissions, AllowedCalls includes the destination you need.
• The vault is funded.
• The vault has an AgentSafe, a KeyManager, and a linked PolicyEngine.
• The PolicyEngine is not paused.
• If the workflow relies on coordinator metadata, your agent is registered in AgentCoordinator and has the expected role or capabilities.

Canonical payment flow on LUKSO

Use this path as the default mental model for real integrations:

1. Build calldata for AgentSafe.execute(...).
2. Call LSP6KeyManager.execute(payload) from the authorized controller or agent address.
3. The KeyManager checks permissions and AllowedCalls.
4. The KeyManager forwards to AgentSafe.execute(...).
5. AgentSafe calls PolicyEngine.validate(...) before execution.
6. Every active policy must pass or the transaction reverts.

For native LYX transfers, the payload is typically a safe.execute(CALL, to, amount, 0x) call.

For token transfers, the same guarded path applies, but the PolicyEngine validates the actual token contract and transfer parameters.

Important note about tests vs production

Some unit tests call agentExecute(...) or agentTransferToken(...) directly for simplicity.

Do not treat that shortcut as the default production integration path.
For live vault operation, assume the KeyManager path is the canonical one unless you know the vault was intentionally configured for a different controller flow.

Why your transaction can be blocked

• Your controller lacks the required LSP6 permission.
• AllowedCalls does not permit the destination or call pattern.
• The vault-wide pause is active in PolicyEngine.
• BudgetPolicy blocks the spend.
• MerchantPolicy blocks the recipient.
• ExpirationPolicy blocks the action because the vault or permission expired.
• SharedBudgetPolicy or SharedBudgetPool blocks the spend because an ancestor pool is exhausted.
• The vault balance is insufficient.

What you cannot do

• You cannot bypass the KeyManager or policy validation path in the standard flow.
• You cannot grant yourself new LSP6 permissions.
• You cannot grant yourself new coordinator roles or capabilities.
• You cannot move funds outside the destinations and budgets the owner configured.
• You cannot ignore a vault-wide pause.
• You cannot create sub-vaults whose budget or permission scope exceeds the root vault's limits.

ROLE B: Orchestrator agent assisting setup

Default root deployment flow today

The current root deployment script is scripts/deploy.ts.

Its default order is:

1. deploy MerchantRegistry
2. deploy AgentVaultDeployerCore
3. deploy AgentVaultDeployer
4. deploy AgentKMDeployer
5. deploy TaskScheduler
6. deploy AgentCoordinator
7. deploy SharedBudgetPool
8. deploy AgentVaultRegistry
9. authorize the registry in AgentCoordinator and SharedBudgetPool
10. deploy vaults through AgentVaultRegistry

Delegated deployment flow

AgentVaultRegistry.deployForAgent(...) is the delegated deployment path.

That flow currently depends on:

• the registry being authorized in AgentCoordinator
• the registry being authorized in SharedBudgetPool
• the deploying agent respecting delegation depth limits
• propagated capabilities being a strict subset of the deployer's capabilities

The UI flow for an agent to trigger this path autonomously is not yet live. A human owner must pre-deploy sub-vaults and explicitly authorize the agent to manage their associated pool and directory entries.

Ownership and post-deploy steps

After vault deployment, make sure the human owner completes the remaining operational steps:

• accept LSP14 ownership on AgentSafe
• fund the vault
• verify LSP6 controller permissions and AllowedCalls
• confirm policy configuration
• configure automation only after the vault and keeper model are ready

Budget hierarchy facts

• SharedBudgetPool supports nested parent-pointer pools with max depth 4.
• A vault can belong to exactly one pool.
• Spending is charged against the vault's pool and all ancestor pools.
• A sub-vault's budget limit can never exceed its parent pool's remaining balance.
• VaultDirectory is useful for discovery and labeling, but it is metadata only. It does not enforce budgets or permissions.

Automation

Current model

Automation in Vaultia is best-effort and keeper-driven.

The on-chain contract stores schedules, but an off-chain service must execute them:

1. call getEligibleTasks() periodically
2. call executeTask(taskId) for each eligible task

Keeper trust and safety model

• TaskScheduler does not hold vault funds.
• The keeper triggers an already configured on-chain path; it does not get spending authority by itself.
• A keeper can still fail on liveness. If it is offline, tasks are delayed or missed.
• New scheduler deployments enforce a keeper whitelist by default.
• If whitelist enforcement is enabled, each keeper must be added explicitly on-chain.

Roadmap

These are the next planned capabilities, not assumptions to act on today:

• Agent-managed sub-vaults via UI — the agent will be able to call VaultDirectory.registerVault() and SharedBudgetPool.createPool() once the UI flow is enabled. The contracts are already deployed.
• Agent-to-agent delegation — an authorized agent will be able to create and authorize sub-agents, with capabilities strictly bounded by its own delegation depth and permission scope.
• Broader agent publishing flows — self-serve registration for third-party agents with verified execution paths.

If you are acting autonomously, prefer the current on-chain facts over UI copy or roadmap assumptions.

Glossary

• Vault: an AgentSafe instance that holds funds and executes validated actions
• KeyManager: the LSP6 contract that checks controller permissions before forwarding execution
• PolicyEngine: the contract that validates every active policy before the safe executes
• Policy: an on-chain rule such as budget, merchant, expiry, or shared-budget enforcement
• AgentCoordinator: agent registry plus role, capability, and delegation metadata layer
• SharedBudgetPool: hierarchical pool accounting for multi-vault budgets, with inherited spending limits
• VaultDirectory: metadata registry for vault labels and graph relationships
• TaskScheduler: on-chain schedule store for recurring or delayed executions
• Keeper: off-chain process that polls and triggers eligible tasks
• Curated agent: a vetted agent with a known execution path, available for evaluation in the current beta phase