> ## Documentation Index
> Fetch the complete documentation index at: https://visualsign.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# gRPC Server

> Run the gRPC parser service without TEE infrastructure

Run VisualSign as a standalone gRPC service without AWS Nitro Enclave infrastructure. This provides the same parsing functionality and API without attestation.

## When to use the gRPC server

The standalone gRPC server is appropriate for:

* Development and testing environments
* Internal services on trusted networks
* Environments where TEE isn't available or required
* Prototyping before moving to TEE

## Security considerations

> [!WARNING]
>
> Without TEE, there's no cryptographic proof of parsing integrity. Only use this deployment model when you trust the network and host.

The standalone server model assumes:

* The host running the parser is trusted
* Network communication is secured (TLS, VPC, etc.)
* You don't need to prove parsing integrity to external parties

## Running locally

The server binary is a single-process gRPC server that calls the parser directly, without the socket-based architecture used in TEE deployments.

```bash theme={null}
# Clone the repository
git clone https://github.com/anchorageoss/visualsign-parser
cd visualsign-parser/src

# Build and run the server
make grpc-server
```

The parser will be available at `localhost:44020`.

### Configuration

Set the `EPHEMERAL_FILE` environment variable to specify a custom signing key:

```bash theme={null}
EPHEMERAL_FILE=/path/to/key.secret cargo run --bin parser_grpc_server
```

For development, the binary defaults to `integration/fixtures/ephemeral.secret`.

#### ABI trust posture

Whether caller-supplied Ethereum `abi_mappings` are honoured when they carry no
signature is chosen at startup, not per request. We recommend passing exactly one
of these flags explicitly, rather than relying on the default described below:

```bash theme={null}
# Honour unsigned ABI mappings. A signature that IS present must still verify,
# but its signer is not checked against an allowlist.
parser_grpc_server --accept-unsigned-abis

# Only honour mappings signed by one of these secp256k1 keys. Repeatable.
# Unsigned and foreign-signed mappings are dropped.
parser_grpc_server --accept-signatures-from-pubkey <hex> [--accept-signatures-from-pubkey <hex>]
```

> [!WARNING]
>
> With no flag, this binary **defaults to `--accept-unsigned-abis`** and prints a
> notice at startup. That default exists because the standalone server has no
> attestation and no signed deployment manifest to audit the posture against, so
> there is nothing to be gained by refusing to start. It does mean a deployment that
> passes no flag honours unsigned ABI mappings from any caller. The enclave binary
> (`parser_app`) has no such default and refuses to start without an explicit
> posture. If you self-host, state the flag explicitly so the choice is recorded in
> your deployment config rather than inherited from a default.

A dropped mapping is not an error: the transaction still parses and the affected
call renders as raw calldata, and nothing in the response distinguishes it from a
request that supplied no mappings.

## Building a Docker image

The server binary can be containerized as a single static binary:

```dockerfile theme={null}
FROM rust:1.94 AS builder

WORKDIR /build
COPY . .

# Build the server binary
RUN cd src && cargo build --release --bin parser_grpc_server

# Runtime image
FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

COPY --from=builder /build/src/target/release/parser_grpc_server /usr/local/bin/
COPY --from=builder /build/src/integration/fixtures/ephemeral.secret /etc/visualsign/

ENV EPHEMERAL_FILE=/etc/visualsign/ephemeral.secret

EXPOSE 44020

# State the ABI trust posture explicitly rather than relying on the binary's
# accept-unsigned default. Swap in --accept-signatures-from-pubkey <hex> to only
# honour ABI mappings signed by keys you allowlist.
CMD ["parser_grpc_server", "--accept-unsigned-abis"]
```

Build and run:

```bash theme={null}
docker build -t visualsign-grpc-server .
docker run -p 44020:44020 visualsign-grpc-server
```

> [!NOTE]
>
> For production, generate your own ephemeral key file rather than using the test fixture.

## Kubernetes deployment

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: visualsign-parser
spec:
  replicas: 2
  selector:
    matchLabels:
      app: visualsign-parser
  template:
    metadata:
      labels:
        app: visualsign-parser
    spec:
      containers:
      - name: parser
        image: your-registry/visualsign-grpc-server:latest
        # ABI trust posture, stated explicitly rather than inherited from the
        # binary's accept-unsigned default.
        args: ["--accept-unsigned-abis"]
        ports:
        - containerPort: 44020
        env:
        - name: EPHEMERAL_FILE
          value: /etc/visualsign/ephemeral.secret
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: visualsign-parser
spec:
  selector:
    app: visualsign-parser
  ports:
  - port: 44020
    targetPort: 44020
```

## Using the gRPC API

The API is identical to TEE deployments, minus attestation:

```go theme={null}
import (
    pb "your-project/parser"
    "google.golang.org/grpc"
)

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

resp, err := client.Parse(context.Background(), &pb.ParseRequest{
    UnsignedPayload: "0xec80850...",
    Chain: pb.Chain_CHAIN_ETHEREUM,
})

// Note: Skip attestation verification when running without TEE
// The response still includes a signature, but it's not attestation-backed
visualSignJSON := resp.ParsedTransaction.Payload.SignablePayload
```

## Alternative: Multi-process mode

For development, you can also run the full multi-process setup that mirrors the TEE architecture:

```bash theme={null}
cd visualsign-parser/src
make parser
```

This starts three processes (`parser_host`, `simulator_enclave`, `parser_app`) communicating over Unix sockets. The single-process server binary is simpler for most use cases.

## Migrating to TEE

The gRPC server uses the same API as TEE deployments. To migrate:

1. Deploy TEE infrastructure (self-hosted or use Turnkey)
2. Update your client to point to the TEE endpoint
3. Add attestation verification to your client

No changes to request/response handling are required.

## Health checks

The server implements the standard [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md):

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

Response:

```json theme={null}
{
  "status": "SERVING"
}
```

You can also list all available services:

```bash theme={null}
grpcurl -plaintext localhost:44020 list
```

## Next steps

* [gRPC API Reference](https://visualsign.dev/api-reference.md) — Full API documentation
* [Self-Hosted TEE](https://visualsign.dev/wallet-integration/self-hosted-tee/getting-started.md) — Upgrade to TEE when ready
* [Chain Metadata](https://visualsign.dev/wallet-integration/core-concepts/chain-metadata.md) — Providing ABIs and IDLs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.