swagger2

apps/api/swagger.json

@@ -476,19 +476,60 @@
     },
     "/wallets/SOL/sign-and-broadcast-tx": {
       "post": {
-        "summary": "Custodial sign + broadcast arbitrary Solana VersionedTransaction",
-        "description": "Подписывает unsigned serialized Solana tx (от Relay /execute SOL-side, или любого aggregator'а). Server verify feePayer === user's pubkey, partial-sign keypair'ом, broadcast, confirm.",
+        "summary": "Custodial sign + broadcast Solana tx (2 формата body)",
+        "description": "Custodial sign + broadcast Solana tx. **Два формата body:**\n\n(a) `{ transaction: '<base64>' }` — pre-built VersionedTransaction (Jupiter swap, Relay serialized).\n\n(b) `{ instructions[], addressLookupTableAddresses[]? }` — Relay SOL bridge instructions. Server compile'ит `TransactionMessage` → `VersionedTransaction` с `feePayer = user`.\n\n**Security:** валидирует что каждый `isSigner=true` key равен derived user SOL pubkey, resolve LUTs через RPC, partial-sign keypair'ом, broadcast, confirm.",
         "tags": ["Wallet Ops"],
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "type": "object",
-                "required": ["transaction"],
-                "properties": {
-                  "transaction": { "type": "string", "description": "Base64-encoded VersionedTransaction (max ~1500 bytes raw)" }
-                }
+                "oneOf": [
+                  {
+                    "title": "Pre-built VersionedTransaction (Jupiter / Relay serialized)",
+                    "type": "object",
+                    "required": ["transaction"],
+                    "properties": {
+                      "transaction": { "type": "string", "description": "Base64-encoded VersionedTransaction (max ~8KB)" }
+                    }
+                  },
+                  {
+                    "title": "Relay-style instructions (для SOL bridge)",
+                    "type": "object",
+                    "required": ["instructions"],
+                    "properties": {
+                      "instructions": {
+                        "type": "array",
+                        "description": "Array из {programId, keys, data}. Server compile'ит TransactionMessage → VersionedTransaction с feePayer=user.",
+                        "items": {
+                          "type": "object",
+                          "required": ["programId", "keys", "data"],
+                          "properties": {
+                            "programId": { "type": "string", "description": "SPL program pubkey (base58)" },
+                            "keys": {
+                              "type": "array",
+                              "items": {
+                                "type": "object",
+                                "required": ["pubkey", "isSigner", "isWritable"],
+                                "properties": {
+                                  "pubkey": { "type": "string", "description": "Account pubkey (base58)" },
+                                  "isSigner": { "type": "boolean", "description": "Если true — pubkey ДОЛЖЕН равняться user'у (anti-drain)" },
+                                  "isWritable": { "type": "boolean" }
+                                }
+                              }
+                            },
+                            "data": { "type": "string", "description": "Instruction data: hex (без префикса) или base64 — autodetect" }
+                          }
+                        }
+                      },
+                      "addressLookupTableAddresses": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "description": "Опционально. SPL Address Lookup Table accounts которые server разрезолвит через SOL RPC (getAddressLookupTable)."
+                      }
+                    }
+                  }
+                ]
               }
             }
           }
@@ -498,9 +539,9 @@
             "description": "Signed and broadcast",
             "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "signature": { "type": "string" }, "chain": { "type": "string" } } } } } } }
           },
-          "400": { "description": "Invalid base64 / tx size / feePayer mismatch" },
+          "400": { "description": "Invalid body / feePayer mismatch / signer-key mismatch / malformed instruction" },
           "404": { "description": "SOL wallet/mnemonic not found" },
-          "502": { "description": "Sign or broadcast failed" }
+          "502": { "description": "Sign or broadcast failed (включая RPC ошибки / blockhash expired / on-chain revert)" }
         }
       }
     },