Orchestrators
Overview
Orchestrators are the core security and execution components of the Genius Protocol's decentralized orchestration system. They are programmable keys that execute sensitive operations on behalf of the protocol, ensuring secure and decentralized management of cross-chain bridge operations.
What are Orchestrators?
Orchestrators are Lit programmable keys that are created with specific Lit actions as their only authorized scopes. They have permissions to perform critical operations on the protocol such as:
Filling orders across different blockchain networks
Reverting orders when necessary
Rebalancing liquidity between supported chains
Managing native token refunds for orchestrator rotation
Key Characteristics
Single Responsibility Principle
Each orchestrator is bound to only one specific responsibility (e.g., rebalancing, order filling, etc.). This design ensures:
Security isolation: Compromise of one orchestrator doesn't affect others
Operational clarity: Clear separation of concerns
Risk mitigation: Limited scope of potential damage
Refund Capability
Every orchestrator includes an additional refund orchestrator Lit action that allows the protocol to:
Recover native tokens (ETH, SOL) left on the orchestrator
Enable safe orchestrator rotation and updates
Prevent fund loss when retiring orchestrators
Security Model
EVM Chains: Lit PKPs (Programmable Key Pairs)
For EVM chains, orchestrators use Lit PKPs which leverage Multi-Party Computation (MPC):
// Example: Creating an EVM orchestrator PKP
const pkpMintCost = await litContracts.pkpNftContract.read.mintCost();
const tx = await litContracts.pkpHelperContract.write.mintNextAndAddAuthMethods(
AUTH_METHOD_TYPE.LitAction, // keyType
actionHashes.map(() => AUTH_METHOD_TYPE.LitAction),
actionHashes.map((actionHash) => `0x${Buffer.from(bs58.decode(actionHash)).toString('hex')}`),
actionHashes.map(() => '0x'),
actionHashes.map(() => [[AUTH_METHOD_SCOPE.SignAnything]]),
true, // addPkpEthAddressAsPermittedAddress
true, // sendPkpToItself
{ value: pkpMintCost }
);Security Benefits:
No single node ever has access to the complete private key
Threshold cryptography ensures key security
Decentralized key management across the Lit network
Solana: Lit Encryption
For Solana, PKPs are not available, so orchestrators use Lit encryption:
// Example: Creating a Solana orchestrator
const orchestrator = Keypair.generate();
const orchestratorSecretKey = bs58.encode(orchestrator.secretKey);
// Encrypt with access control conditions
const encryptedPk = await encryptor.encrypt(
orchestratorSecretKey,
accessControlPkOnlyAuthorizedAction
);Security Benefits:
TEE (Trusted Execution Environment) protection
Encrypted keys are only decrypted within secure enclaves
No node has access to the complete Solana private key
Orchestrator Types and Responsibilities
1. Rebalancing Orchestrator
Purpose: Manages liquidity distribution across supported chains
Responsibilities:
Execute rebalancing instructions
Transfer liquidity between chains via bridges
Maintain optimal liquidity ratios
Handle cross-chain transactions
Example Usage:
// Rebalancing orchestrator execution
const res = await rebalancingExecutionImpl(
env,
orchestratorSolanaPubKey,
new LitHelpers(),
RPC_URLS(envVars),
instructionsResponse,
actionsBatch
);2. Solver Orchestrator
Purpose: Fills orders across different blockchain networks
Responsibilities:
Execute order fills on EVM chains
Execute order fills on Solana
Handle cross-chain order processing
Manage transaction execution
3. Refund Orchestrator
Purpose: Recovers native tokens from orchestrators
Responsibilities:
Withdraw ETH from EVM orchestrators
Withdraw SOL from Solana orchestrators
Enable safe orchestrator rotation
Prevent fund loss during updates
Example Implementation:
// EVM refund orchestrator
const message = `REFUND_ORCHESTRATOR_${orchestratorAddress}`;
if (!validateEthSignature(message, ownerSignature, OWNER_ADR_EVM(env))) {
throw new Error('Invalid signature');
}
// Calculate safe transfer amount
const gasCost = BigInt(gasLimit) * BigInt(gasPrice);
const buffer = BigInt(1000000000000);
const safeTransferAmount = BigInt(balance) - gasCost - buffer;
const transferEthTxn = {
to: OWNER_ADR_EVM(env),
value: safeTransferAmount.toString(),
data: '',
gasLimit,
gasPrice,
};Access Control and Permissions
Lit Action Scopes
Orchestrators are restricted to specific Lit action IPFS hashes:
// Access control conditions for orchestrator
const accessControlPkOnlyAuthorizedAction: AccessControlConditions = [
{
contractAddress: '',
standardContractType: '',
chain: 'ethereum',
method: '',
parameters: [':currentActionIpfsId'],
returnValueTest: {
comparator: '=',
value: 'QmerWcM4m4jWyo62LoQJEwjKrjG7c8q7vQB9wc2iA18ptk', // rebalancing action
},
},
{ operator: 'or' },
{
contractAddress: '',
standardContractType: '',
chain: 'ethereum',
method: '',
parameters: [':currentActionIpfsId'],
returnValueTest: {
comparator: '=',
value: 'QmYejeXiM1fhmZmrP3neWt7vW7HkFt75bHHVGkBJw5BYJF', // refund action
},
}
];Authorization Checks
All orchestrator actions include authorization validation:
// Example: Authorization check in Lit actions
if (!isCallerAuthorizedLit(EXECUTOR_ADR_EVM(env))) {
throw new Error(`Caller is not authorized. Expected: ${EXECUTOR_ADR_EVM(env)}`);
}Orchestrator Lifecycle
1. Creation
// Create orchestrator with specific action scopes
const res = await createOrchestratorBase(new EncryptorLit(), ipfsHashs);2. Deployment
Orchestrator keys are encrypted and stored securely
Access control conditions are configured
Lit actions are deployed to IPFS
3. Operation
Orchestrators execute their designated functions
All operations are logged and monitored
Failures trigger appropriate error handling
4. Rotation/Retirement
Refund orchestrator recovers native tokens
New orchestrators can be deployed
Old orchestrators are safely decommissioned
Security Considerations
Key Management
EVM PKPs: Never expose complete private keys
Solana Keys: Always encrypted and TEE-protected
Access Control: Strict IPFS hash-based permissions
Rotation: Regular key rotation for enhanced security
Operational Security
Authorization: All actions require proper authorization
Validation: Comprehensive input validation
Error Handling: Graceful failure handling
Monitoring: Continuous operation monitoring
Attack Prevention
Replay Protection: Timestamp-based signature validation
Access Control: IPFS hash-based action restrictions
Isolation: Single responsibility per orchestrator
Recovery: Refund mechanisms for safe rotation
Best Practices
Orchestrator Design
Single Responsibility: Each orchestrator handles one specific function
Minimal Permissions: Grant only necessary permissions
Refund Capability: Always include refund functionality
Error Handling: Implement comprehensive error handling
Security Implementation
Key Encryption: Always encrypt sensitive keys
Access Control: Use strict access control conditions
Authorization: Validate all incoming requests
Monitoring: Monitor all orchestrator activities
Operational Management
Regular Rotation: Rotate orchestrators periodically
Backup Recovery: Maintain backup recovery procedures
Documentation: Keep detailed operational documentation
Testing: Regular security testing and validation
Orchestrators are the backbone of the Genius Protocol's decentralized orchestration system. They provide secure, isolated, and efficient execution of critical protocol operations while maintaining the highest security standards through Lit Network's advanced cryptographic techniques.
The combination of Lit PKPs for EVM chains and Lit encryption for Solana ensures that no single entity ever has access to complete private keys, making the system truly decentralized and secure.
Last updated