Smart Contracts API

REST API for contract management, deployment, monitoring, and disaster recovery.

Base URL

1https://api.yourdomain.com/v1/contracts

Authentication

All requests require API key:

1curl https://api.yourdomain.com/v1/contracts/contracts \
2  -H "Authorization: Bearer YOUR_API_KEY"

Contracts

Create Contract

Endpoint: POST /contracts

Request:

1{
2  "name": "TokenSale",
3  "description": "ERC20 token sale contract",
4  "abi": [...],
5  "bytecode": "0x606060...",
6  "source_code": "contract TokenSale { ... }",
7  "network": "ethereum_mainnet",
8  "template_id": "template_erc20"
9}

Response:

1{
2  "id": "contract_abc123",
3  "name": "TokenSale",
4  "version": "1.0.0",
5  "status": "created",
6  "created_at": "2024-01-15T10:30:00Z"
7}

Deploy Contract

Deploy contract to blockchain network.

Endpoint: POST /contracts/:id/deploy

Request:

1{
2  "network": "ethereum_mainnet",
3  "constructor_args": [
4    "1000000",
5    "0x742d35Cc6634C0532925a3b844Bc9e7595f0DeE4"
6  ],
7  "gas_limit": 3000000,
8  "gas_price": "50",
9  "confirmations_required": 3
10}

Response:

1{
2  "deployment_id": "deploy_xyz789",
3  "status": "pending",
4  "transaction_hash": "0x8a3f...",
5  "estimated_cost": {
6    "gas_limit": 3000000,
7    "gas_price_gwei": 50,
8    "total_eth": 0.15,
9    "total_usd": 245.50
10  }
11}

Get Contract Status

Endpoint: GET /contracts/:id

Response:

1{
2  "id": "contract_abc123",
3  "name": "TokenSale",
4  "version": "1.0.0",
5  "status": "deployed",
6  "deployments": [
7    {
8      "network": "ethereum_mainnet",
9      "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
10      "transaction_hash": "0x8a3f...",
11      "block_number": 18542340,
12      "deployed_at": "2024-01-15T10:35:22Z",
13      "status": "active"
14    }
15  ],
16  "health": {
17    "status": "healthy",
18    "last_execution": "2024-01-15T14:20:15Z",
19    "execution_count": 142,
20    "failure_rate": 0.014
21  }
22}

List Contracts

Endpoint: GET /contracts

Query Parameters:

network - Filter by network
status - Filter by status
template_id - Filter by template
limit - Results per page

Versions

Create Version

Create new contract version.

Endpoint: POST /contracts/:id/versions

Request:

1{
2  "version": "1.1.0",
3  "changes": "Added pausable functionality",
4  "abi": [...],
5  "bytecode": "0x606060...",
6  "source_code": "contract TokenSale { ... }"
7}

Rollback Version

Rollback to previous version.

Endpoint: POST /contracts/:id/rollback

Request:

1{
2  "target_version": "1.0.0",
3  "reason": "Critical bug in v1.1.0"
4}

Execution

Execute Contract Function

Call contract function.

Endpoint: POST /contracts/:id/execute

Request:

1{
2  "network": "ethereum_mainnet",
3  "function": "transfer",
4  "args": [
5    "0x742d35Cc6634C0532925a3b844Bc9e7595f0DeE4",
6    "1000000"
7  ],
8  "gas_limit": 100000,
9  "value": "0",
10  "idempotency_key": "tx_unique_123"
11}

Response:

1{
2  "execution_id": "exec_abc",
3  "status": "pending",
4  "transaction_hash": "0x5b2f...",
5  "estimated_confirmation": "2024-01-15T10:32:00Z",
6  "idempotency_key": "tx_unique_123"
7}

Get Execution Status

Endpoint: GET /executions/:id

Response:

1{
2  "execution_id": "exec_abc",
3  "status": "confirmed",
4  "transaction_hash": "0x5b2f...",
5  "block_number": 18542355,
6  "gas_used": 82450,
7  "gas_price_gwei": 50,
8  "cost_eth": 0.0041225,
9  "cost_usd": 6.75,
10  "confirmed_at": "2024-01-15T10:31:45Z",
11  "confirmations": 12
12}

Monitoring

Get Health Metrics

Endpoint: GET /contracts/:id/health

Response:

1{
2  "contract_id": "contract_abc123",
3  "status": "healthy",
4  "metrics": {
5    "execution_count": 1420,
6    "success_count": 1398,
7    "failure_count": 22,
8    "success_rate": 0.9845,
9    "avg_gas_used": 85420,
10    "avg_execution_time_ms": 1250
11  },
12  "alerts": []
13}

Configure Alert Rules

Endpoint: POST /contracts/:id/alerts

Request:

1{
2  "rule_name": "High Gas Usage",
3  "condition": {
4    "metric": "gas_used",
5    "operator": "greater_than",
6    "threshold": 500000
7  },
8  "actions": [
9    {
10      "type": "webhook",
11      "url": "https://your-app.com/alerts"
12    },
13    {
14      "type": "email",
15      "recipients": ["ops@example.com"]
16    }
17  ]
18}

Get Transaction History

Endpoint: GET /contracts/:id/transactions

Query Parameters:

from - Start timestamp
to - End timestamp
status - Filter by status
limit - Results per page

Response:

1{
2  "transactions": [
3    {
4      "transaction_hash": "0x8a3f...",
5      "function": "transfer",
6      "from": "0x742d...",
7      "to": "0x1f98...",
8      "value": "0.5",
9      "gas_used": 82450,
10      "status": "confirmed",
11      "timestamp": "2024-01-15T10:31:45Z"
12    }
13  ],
14  "total": 1420,
15  "has_more": true
16}

Data Ingestion

Create Ingestion Job

Submit data for processing and contract execution.

Endpoint: POST /ingestion/jobs

Request:

1{
2  "source_id": "source_oracle",
3  "data": {
4    "price": 45.23,
5    "timestamp": "2024-01-15T10:30:00Z"
6  },
7  "transformation_rules": ["rule_normalize", "rule_validate"],
8  "trigger_contract": "contract_abc123",
9  "priority": "high"
10}

Response:

1{
2  "job_id": "job_xyz789",
3  "status": "queued",
4  "position": 3,
5  "estimated_start": "2024-01-15T10:30:15Z"
6}

Get Job Status

Endpoint: GET /ingestion/jobs/:id

Response:

1{
2  "job_id": "job_xyz789",
3  "status": "completed",
4  "started_at": "2024-01-15T10:30:15Z",
5  "completed_at": "2024-01-15T10:30:18Z",
6  "result": {
7    "transformed_data": {...},
8    "contract_triggered": true,
9    "execution_id": "exec_abc"
10  }
11}

Disaster Recovery

Create Backup

Endpoint: POST /backups

Request:

1{
2  "backup_type": "full",
3  "encryption": true,
4  "compression": true,
5  "retention_days": 90
6}

Response:

1{
2  "backup_id": "backup_abc123",
3  "status": "in_progress",
4  "backup_type": "full",
5  "started_at": "2024-01-15T10:30:00Z",
6  "estimated_size_mb": 450
7}

List Backups

Endpoint: GET /backups

Response:

1{
2  "backups": [
3    {
4      "backup_id": "backup_abc123",
5      "backup_type": "full",
6      "status": "completed",
7      "size_mb": 423,
8      "created_at": "2024-01-15T10:30:00Z",
9      "expires_at": "2024-04-15T10:30:00Z",
10      "checksum": "sha256:a3f2..."
11    }
12  ]
13}

Restore from Backup

Endpoint: POST /backups/:id/restore

Request:

1{
2  "target_environment": "staging",
3  "point_in_time": "2024-01-14T12:00:00Z",
4  "verify_integrity": true
5}

Response:

1{
2  "restore_id": "restore_xyz",
3  "status": "in_progress",
4  "estimated_duration_minutes": 15
5}

Horizontal Scaling

Get Cluster Status

Endpoint: GET /scaling/cluster

Response:

1{
2  "nodes": [
3    {
4      "node_id": "node_1",
5      "status": "active",
6      "health": "healthy",
7      "metrics": {
8        "cpu_utilization": 45,
9        "memory_utilization": 62,
10        "active_connections": 142,
11        "queue_size": 12
12      },
13      "last_heartbeat": "2024-01-15T10:35:00Z"
14    }
15  ],
16  "total_nodes": 4,
17  "active_nodes": 4,
18  "load_distribution": "balanced"
19}

Configure Auto-Scaling

Endpoint: POST /scaling/policies

Request:

1{
2  "min_nodes": 2,
3  "max_nodes": 10,
4  "target_cpu": 70,
5  "target_memory": 80,
6  "scale_up_threshold": 75,
7  "scale_down_threshold": 30,
8  "cooldown_minutes": 5
9}

Manual Scale Operation

Endpoint: POST /scaling/scale

Request:

1{
2  "action": "scale_up",
3  "node_count": 2
4}

Rate Limits

Contract Operations: 100/hour
Deployments: 10/hour
Executions: 1000/hour
API Queries: 10000/hour

Error Codes

| Code | Status | Description | |------|--------|-------------| | invalid_abi | 400 | ABI format invalid | | invalid_bytecode | 400 | Bytecode validation failed | | insufficient_gas | 400 | Gas limit too low | | deployment_failed | 500 | Contract deployment failed | | execution_failed | 500 | Contract execution failed | | network_unavailable | 503 | Blockchain network unreachable |

Webhooks

Webhook Events

contract.created - Contract registered
contract.deployed - Deployment completed
execution.started - Function execution started
execution.completed - Execution finished
execution.failed - Execution failed
alert.triggered - Alert rule triggered
backup.completed - Backup finished
scaling.event - Scaling operation occurred

Webhook Payload

1{
2  "event": "execution.completed",
3  "timestamp": "2024-01-15T10:31:45Z",
4  "data": {
5    "execution_id": "exec_abc",
6    "contract_id": "contract_abc123",
7    "transaction_hash": "0x5b2f...",
8    "status": "confirmed",
9    "gas_used": 82450
10  },
11  "signature": "sha256=..."
12}

SDK

1npm install @mesh-software/contracts-sdk

1import { SmartContracts } from '@mesh-software/contracts-sdk';
2
3const client = new SmartContracts({ apiKey: 'YOUR_API_KEY' });
4
5// Create and deploy contract
6const contract = await client.contracts.create({
7  name: 'TokenSale',
8  abi: [...],
9  bytecode: '0x606060...'
10});
11
12const deployment = await client.contracts.deploy(contract.id, {
13  network: 'ethereum_mainnet',
14  constructor_args: ['1000000']
15});
16
17// Execute function
18const execution = await client.contracts.execute(contract.id, {
19  function: 'transfer',
20  args: ['0x742d...', '1000000']
21});