# Blockchain

Blockchain synchronization operations for syncing entities to Solana blockchain

## Prepare blockchain sync transaction

> Prepares a blockchain transaction for syncing an entity (Zone, Pin, GCP, or File) to the Solana blockchain. Returns transaction metadata and data that the client will sign and send. Authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Blockchain","description":"Blockchain synchronization operations for syncing entities to Solana blockchain"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"DynamicAuth":[]}],"components":{"securitySchemes":{"DynamicAuth":{"type":"apiKey","in":"header","name":"X-Dynamic-User-Id","description":"Dynamic authentication header. Required for blockchain endpoints and other authenticated operations."}},"schemas":{"BlockchainSyncRequest":{"type":"object","required":["entityType","entityId"],"properties":{"entityType":{"type":"string","enum":["Zone","Pin","Gcp","File"],"description":"Type of entity to sync to blockchain"},"entityId":{"type":"integer","minimum":1,"description":"ID of the entity to sync"},"network":{"type":"string","enum":["devnet","mainnet","testnet"],"description":"Solana network to use (defaults to devnet if not specified)"}}},"BlockchainSyncResponse":{"oneOf":[{"type":"object","title":"Success Response","required":["success","metadata","network"],"properties":{"success":{"type":"boolean","const":true,"description":"Transaction was prepared successfully"},"metadata":{"type":"object","description":"Spatial metadata object containing entity information for blockchain","properties":{"entityType":{"type":"string","enum":["Zone","Pin","Gcp","File"]},"entityId":{"type":"integer"},"title":{"type":"string"},"geojson":{"type":"object","description":"GeoJSON object containing geographic data"},"geoPose":{"type":"object","description":"GeoPose object containing position and orientation data"}},"additionalProperties":true},"transactionData":{"type":"object","description":"Transaction data for client to sign and send","additionalProperties":true},"network":{"type":"string","enum":["devnet","mainnet","testnet"],"description":"Solana network used for the transaction"}}},{"type":"object","title":"Error Response","required":["error"],"properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"array","description":"Validation error details (only present on validation errors)","items":{"type":"object"}}}}]},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/blockchain/sync":{"post":{"summary":"Prepare blockchain sync transaction","description":"Prepares a blockchain transaction for syncing an entity (Zone, Pin, GCP, or File) to the Solana blockchain. Returns transaction metadata and data that the client will sign and send. Authentication required.","tags":["Blockchain"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockchainSyncRequest"}}}},"responses":{"200":{"description":"Transaction prepared successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockchainSyncResponse"}}}},"400":{"description":"Bad request - invalid input or wallet address not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error - failed to prepare sync","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Confirm blockchain transaction

> Records a confirmed blockchain transaction in the database after it has been signed and sent by the client. Verifies the transaction status and updates the entity's blockchain sync status. Authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Blockchain","description":"Blockchain synchronization operations for syncing entities to Solana blockchain"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"DynamicAuth":[]}],"components":{"securitySchemes":{"DynamicAuth":{"type":"apiKey","in":"header","name":"X-Dynamic-User-Id","description":"Dynamic authentication header. Required for blockchain endpoints and other authenticated operations."}},"schemas":{"BlockchainConfirmRequest":{"type":"object","required":["entityType","entityId","signature"],"properties":{"entityType":{"type":"string","enum":["Zone","Pin","Gcp","File"],"description":"Type of entity that was synced"},"entityId":{"type":"integer","minimum":1,"description":"ID of the entity that was synced"},"signature":{"type":"string","minLength":1,"description":"Transaction signature from Solana blockchain"},"network":{"type":"string","enum":["devnet","mainnet","testnet"],"description":"Solana network used for the transaction"},"blockHeight":{"type":"integer","minimum":1,"description":"Block height at which the transaction was confirmed (optional)"}}},"BlockchainConfirmResponse":{"oneOf":[{"type":"object","title":"Success Response","required":["success","signature","explorerUrl"],"properties":{"success":{"type":"boolean","const":true,"description":"Transaction was confirmed successfully"},"signature":{"type":"string","description":"Transaction signature"},"explorerUrl":{"type":"string","format":"uri","description":"URL to view the transaction on Solana Explorer"}}},{"type":"object","title":"Error Response","required":["error"],"properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"array","description":"Validation error details (only present on validation errors)","items":{"type":"object"}}}}]},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/blockchain/confirm":{"post":{"summary":"Confirm blockchain transaction","description":"Records a confirmed blockchain transaction in the database after it has been signed and sent by the client. Verifies the transaction status and updates the entity's blockchain sync status. Authentication required.","tags":["Blockchain"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockchainConfirmRequest"}}}},"responses":{"200":{"description":"Transaction confirmed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockchainConfirmResponse"}}}},"400":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error - failed to confirm transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Mark blockchain sync as failed

> Marks an entity's blockchain sync as failed (e.g., when transaction is cancelled or fails). Authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Blockchain","description":"Blockchain synchronization operations for syncing entities to Solana blockchain"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"DynamicAuth":[]}],"components":{"securitySchemes":{"DynamicAuth":{"type":"apiKey","in":"header","name":"X-Dynamic-User-Id","description":"Dynamic authentication header. Required for blockchain endpoints and other authenticated operations."}},"schemas":{"BlockchainSyncRequest":{"type":"object","required":["entityType","entityId"],"properties":{"entityType":{"type":"string","enum":["Zone","Pin","Gcp","File"],"description":"Type of entity to sync to blockchain"},"entityId":{"type":"integer","minimum":1,"description":"ID of the entity to sync"},"network":{"type":"string","enum":["devnet","mainnet","testnet"],"description":"Solana network to use (defaults to devnet if not specified)"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/blockchain/fail":{"post":{"summary":"Mark blockchain sync as failed","description":"Marks an entity's blockchain sync as failed (e.g., when transaction is cancelled or fails). Authentication required.","tags":["Blockchain"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockchainSyncRequest"}}}},"responses":{"200":{"description":"Sync marked as failed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error - failed to mark sync as failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```