Contract Automation Service

Key Features

• Trigger smart contract executions based on various conditions
• Schedule recurring blockchain transactions
• Listen for specific blockchain events
• Connect external events to on-chain actions
• Conditional execution with custom logic
• Gas management through the Gas Bank service
• Detailed logs and execution history

Trigger Types

The Automation Service supports several types of triggers:

Time-Based Triggers

Execute smart contract functions on a schedule:

• One-time: Execute a contract method at a specific date and time
• Recurring: Execute on a recurring schedule (e.g., hourly, daily, weekly)
• Cron-style: Use cron expressions for complex scheduling patterns

1{
2  "trigger_type": "cron",
3  "trigger_config": {
4    "schedule": "0 0 * * *",  // Daily at midnight
5    "timezone": "UTC"
6  }
7}

Blockchain Event Triggers

Execute smart contract functions in response to blockchain events:

• Transaction Events: Trigger when specific transactions occur
• Contract Notifications: Listen for notifications from specific contracts
• Block Events: Execute based on new blocks or block height

1{
2  "trigger_type": "blockchain",
3  "trigger_config": {
4    "contract_hash": "0x1234567890abcdef1234567890abcdef12345678",
5    "event_name": "Transfer"
6  }
7}

Price Triggers

Execute contract functions when token prices cross specified thresholds:

• Price Threshold: Trigger when a token price goes above or below a threshold
• Price Change: Trigger on a percentage price change
• Price Stability: Trigger when a price remains stable for a set period

1{
2  "trigger_type": "price",
3  "trigger_config": {
4    "asset_pair": "NEO/USD",
5    "condition": "above",
6    "threshold": 50.0,
7    "duration": 300  // Must be above threshold for 5 minutes
8  }
9}

Action Types

When a trigger condition is met, the Automation Service can perform several types of actions:

Smart Contract Invocation

Call a method on a Neo N3 smart contract. You can specify:

• Contract script hash
• Method name
• Method parameters
• Gas fee
• Signer information

1{
2  "action_type": "contract_invocation",
3  "action_config": {
4    "contract_hash": "0x1234567890abcdef1234567890abcdef12345678",
5    "method": "transfer",
6    "params": [
7      {
8        "type": "Hash160",
9        "value": "NbnjKGMBJzJ6j5PHeYhjJDaQ5Vy5UYu4Fv"
10      },
11      {
12        "type": "Hash160",
13        "value": "NhGomBpYnKXArr55nHRQ5rzy79TwKVXZbr"
14      },
15      {
16        "type": "Integer",
17        "value": "1000"
18      }
19    ],
20    "gas_fee": 1.5,
21    "use_gas_bank": true
22  }
23}

Function Execution

Execute a JavaScript function in the TEE. You can specify:

• Function name (must be created in the Functions Service)
• Function parameters
• Callback information for further processing

1{
2  "action_type": "function_execution",
3  "action_config": {
4    "function_name": "processTransfer",
5    "params": {
6      "contract": "0x1234567890abcdef1234567890abcdef12345678",
7      "event": "Transfer",
8      "debug_mode": true
9    }
10  }
11}

HTTP Webhook

Send an HTTP request to an external service. You can specify:

• URL endpoint
• HTTP method
• Headers
• Request body
• Authentication information

1{
2  "action_type": "webhook",
3  "action_config": {
4    "url": "https://api.example.com/notify",
5    "method": "POST",
6    "headers": {
7      "Content-Type": "application/json",
8      "Authorization": "Bearer {SECRET_API_KEY}"
9    },
10    "body": {
11      "event": "price_alert",
12      "asset": "NEO",
13      "price": 50.0,
14      "timestamp": "{TIMESTAMP}"
15    }
16  }
17}

Creating Automation Rules

To create an automation rule, you need to provide both trigger and action configurations. Here's a complete example:

1{
2  "name": "Daily Token Distribution",
3  "description": "Distribute tokens to stakeholders every day at midnight",
4  "active": true,
5  
6  "trigger": {
7    "type": "cron",
8    "config": {
9      "schedule": "0 0 * * *",
10      "timezone": "UTC"
11    }
12  },
13  
14  "action": {
15    "type": "contract_invocation",
16    "config": {
17      "contract_hash": "0x1234567890abcdef1234567890abcdef12345678",
18      "method": "distributeRewards",
19      "params": [],
20      "gas_fee": 2.0,
21      "use_gas_bank": true
22    }
23  },
24  
25  "failure_handling": {
26    "retry_count": 3,
27    "retry_interval": 300,
28    "notification_endpoint": "https://api.example.com/notify-failure"
29  }
30}

Example: React to Token Transfers

This example sets up an automation that listens for token transfers on a specific contract and executes a function when it detects a transfer:

1{
2  "name": "Token Transfer Processor",
3  "description": "Process large token transfers and take action",
4  "active": true,
5  
6  "trigger": {
7    "type": "blockchain",
8    "config": {
9      "contract_hash": "0x7a16a1f5c40e69790333f3bfe7e4325a08cc2f79", // Token contract
10      "event_name": "Transfer",
11      "filters": {
12        "amount": {
13          "condition": ">=",
14          "value": 1000
15        }
16      }
17    }
18  },
19  
20  "action": {
21    "type": "function_execution",
22    "config": {
23      "function_name": "processLargeTransfer",
24      "params": {
25        "includeSenderDetails": true,
26        "includeRecipientHistory": true
27      }
28    }
29  }
30}

Smart Contract Integration

To make your smart contracts work with the Automation Service, you need to ensure they emit the appropriate events that the service can listen for:

1using Neo.SmartContract.Framework;
2using Neo.SmartContract.Framework.Services;
3using System;
4using System.ComponentModel;
5
6namespace SampleToken 
7{
8    [DisplayName("SampleToken")]
9    public class SampleToken : Nep17Token
10    {
11        // Token transfer event that Automation Service can listen for
12        [DisplayName("Transfer")]
13        public static event Action<UInt160, UInt160, BigInteger> OnTransfer;
14        
15        // Implement transfer method that emits the event
16        public bool Transfer(UInt160 from, UInt160 to, BigInteger amount)
17        {
18            // Implementation logic here
19            
20            // Emit event that Automation Service will detect
21            OnTransfer(from, to, amount);
22            return true;
23        }
24    }
25}

Security Considerations

Authentication and Authorization

All automation rules are tied to your account and can only be managed with proper authentication. Contract invocations use your stored credentials and are executed securely from the TEE.

Gas Management

Automation actions that invoke contracts require GAS for transaction fees. You can:

• Set a maximum GAS fee per transaction
• Use the Gas Bank service to manage GAS efficiently
• Receive notifications when your GAS balance is low

Error Handling

The service provides robust error handling for automation:

• Configurable retry mechanism for failed actions
• Error notifications via webhooks or email
• Detailed failure logs for debugging
• Ability to pause automations when persistent failures occur

Monitoring and Metrics

The Automation Service provides comprehensive monitoring of your automations:

• Execution history including success/failure status
• Resource usage metrics (GAS spent, execution time)
• Trigger frequency and patterns
• Failure analytics and common error patterns

You can access these metrics through the dashboard or via the API.

API Reference

Automation API Endpoints

• GET /api/v1/automations - List all automation rules
• GET /api/v1/automations/:id - Get details of a specific automation rule
• POST /api/v1/automations - Create a new automation rule
• PUT /api/v1/automations/:id - Update an automation rule
• DELETE /api/v1/automations/:id - Delete an automation rule
• POST /api/v1/automations/:id/enable - Enable an automation rule
• POST /api/v1/automations/:id/disable - Disable an automation rule
• GET /api/v1/automations/:id/executions - Get execution history

For a complete API reference, see the Automation API documentation.

Integration with Other Services

The Automation Service works seamlessly with other Service Layer components:

• Functions Service: Execute functions as actions or use functions to process trigger data
• Oracle Service: Automate oracle data updates based on schedules
• Gas Bank: Optimize GAS usage for automated contract invocations
• Price Feed: Trigger actions based on token price changes
• Secrets Service: Securely store API keys and credentials for webhook actions

Use Cases

Next Steps

• Automation Developer Guide
• Functions Service Documentation
• Gas Bank Service Documentation
• Try the Playground