gRPC API Reference

Complete API documentation for the VisualSign parser service.

Service Definition

service ParserService {
  rpc Parse(ParseRequest) returns (ParseResponse);
}

Messages

ParseRequest

The main request for parsing transactions.

message ParseRequest {
  string unsigned_payload = 1;    // Raw transaction (base64 or hex)
  Chain chain = 2;                // Blockchain network
  ChainMetadata chain_metadata = 3; // Optional chain-specific data
}

Fields:

Field	Type	Description
unsigned_payload	string	Raw unsigned transaction bytes, base64 or hex encoded
chain	Chain enum	The blockchain network (CHAIN_ETHEREUM, CHAIN_SOLANA, etc.)
chain_metadata	ChainMetadata	Optional metadata like ABI or IDL

Chain Enum

Supported blockchain networks:

enum Chain {
  CHAIN_UNSPECIFIED = 0;
  CHAIN_BITCOIN = 1;
  CHAIN_ETHEREUM = 2;
  CHAIN_SOLANA = 3;
  CHAIN_SUI = 4;
  CHAIN_TRON = 5;
  CHAIN_CUSTOM = 999;  // For extensibility
}

ChainMetadata

Chain-specific metadata for enhanced parsing:

message ChainMetadata {
  oneof metadata {
    EthereumMetadata ethereum = 1;
    SolanaMetadata solana = 2;
  }
}

message EthereumMetadata {
  optional Abi abi = 1;  // Contract ABI for decoding
}

message SolanaMetadata {
  optional Idl idl = 1;  // Anchor IDL for decoding
}

ParseResponse

The parsed transaction response:

message ParseResponse {
  ParsedTransaction parsed_transaction = 1;
}

message ParsedTransaction {
  ParsedTransactionPayload payload = 1;
  Signature signature = 2;
}

message ParsedTransactionPayload {
  string signable_payload = 4;  // VisualSign JSON string
}

Signature

Cryptographic signature for attestation:

message Signature {
  SignatureScheme scheme = 1;  // Signature algorithm
  string public_key = 2;       // Public key (hex)
  string message = 3;          // Message that was signed
  string signature = 4;        // Signature bytes (hex)
}

enum SignatureScheme {
  SIGNATURE_SCHEME_UNSPECIFIED = 0;
  SIGNATURE_SCHEME_TURNKEY_P256_EPHEMERAL_KEY = 1;
}

Usage Examples

Basic Transaction Parsing

# Ethereum transaction
grpcurl -plaintext -d '{
  "unsigned_payload": "0xf86c808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a028ef61340bd939bc2195fe537567866003e1a15d3c71ff63e1590620aa636276a067cbe9d8997f761aecb703304b3800ccf555c9f3dc64214b297fb1966a3b6d83",
  "chain": "CHAIN_ETHEREUM"
}' localhost:44020 parser.ParserService/Parse

With Contract ABI

# Ethereum with ABI for smart contract decoding
grpcurl -plaintext -d '{
  "unsigned_payload": "0x...",
  "chain": "CHAIN_ETHEREUM",
  "chain_metadata": {
    "ethereum": {
      "abi": {
        "value": "[{\"inputs\":[],\"name\":\"transfer\",\"type\":\"function\"}]"
      }
    }
  }
}' localhost:44020 parser.ParserService/Parse

Solana with Anchor IDL

# Solana with IDL for program decoding
grpcurl -plaintext -d '{
  "unsigned_payload": "AgAAAAAAAA...",
  "chain": "CHAIN_SOLANA",
  "chain_metadata": {
    "solana": {
      "idl": {
        "value": "{\"version\":\"0.30.0\",\"name\":\"my_program\",...}",
        "idl_type": "SOLANA_IDL_TYPE_ANCHOR",
        "idl_version": "0.30.0"
      }
    }
  }
}' localhost:44020 parser.ParserService/Parse

Response Format

Successful Response

{
  "parsedTransaction": {
    "payload": {
      "signablePayload": "{\"Version\":\"0\",\"Title\":\"Ethereum Transfer\",\"Fields\":[{\"Type\":\"text_v2\",\"Label\":\"To\",\"TextV2\":{\"Text\":\"0x3535...\"}}]}"
    },
    "signature": {
      "scheme": "SIGNATURE_SCHEME_TURNKEY_P256_EPHEMERAL_KEY",
      "publicKey": "04abc123...",
      "message": "sha256_hash_of_payload",
      "signature": "304502..."
    }
  }
}

Error Response

Errors follow the standard gRPC status codes:

{
  "code": 3,
  "message": "Invalid transaction format",
  "details": []
}

Common error codes:

• 3 (INVALID_ARGUMENT) - Invalid transaction or chain
• 5 (NOT_FOUND) - Chain not supported
• 13 (INTERNAL) - Parser error
• 14 (UNAVAILABLE) - Service unavailable

Health Check API

The service also implements the standard gRPC health check:

service Health {
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
}

Check service health:

grpcurl -plaintext -d '{"service":"parser.ParserService"}' \
    localhost:44020 grpc.health.v1.Health/Check

Response:

{
  "status": "SERVING"
}

Client Libraries

Go

import pb "github.com/anchorageoss/visualsign-parser/proto"

conn, _ := grpc.Dial("localhost:44020", grpc.WithInsecure())
client := pb.NewParserServiceClient(conn)

Python

import grpc
import parser_pb2
import parser_pb2_grpc

channel = grpc.insecure_channel('localhost:44020')
stub = parser_pb2_grpc.ParserServiceStub(channel)

JavaScript/TypeScript

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDefinition = protoLoader.loadSync('parser.proto');
const parser = grpc.loadPackageDefinition(packageDefinition).parser;

const client = new parser.ParserService(
    'localhost:44020',
    grpc.credentials.createInsecure()
);

Rate Limits

The parser service enforces the following limits:

• Request size: Max 1MB per transaction
• Timeout: 30 seconds per request
• Concurrent requests: 100 per client

Security

TLS Configuration

In production, always use TLS:

creds := credentials.NewTLS(&tls.Config{
    ServerName: "parser.example.com",
})
conn, _ := grpc.Dial("parser.example.com:44020", grpc.WithTransportCredentials(creds))

Authentication

The service supports mTLS for authentication:

cert, _ := tls.LoadX509KeyPair("client.crt", "client.key")
creds := credentials.NewTLS(&tls.Config{
    Certificates: []tls.Certificate{cert},
})