---
description: Protocol Buffer File Rules
globs: ["**/*.proto"]
alwaysApply: false
---


# Protocol Buffer File Rules

> **⚠️ XRP Protocol Buffers DEPRECATED**
>
> **Status**: `proto/rippleapi/` is **DEPRECATED** and no longer used.
>
> **Reason**: XRP functionality migrated to native Go implementation. gRPC server (`apps/xrpl-grpc-server/`) has been replaced with native xrpl-go libraries.

## Overview

Rules for modifying Protocol Buffer files (`*.proto`) in go-crypto-wallet.

## Applicable Directories

| Directory | Description | Status |
|-----------|-------------|--------|
| `proto/rippleapi/` | Ripple API definitions | ❌ DEPRECATED |

## Verification Commands

| Command | Purpose | Required |
|---------|---------|----------|
| `make proto-lint` | Lint proto files (buf only, requires PROTO_TOOL=buf) | When buf supports Edition 2024 |
| `make proto-breaking` | Check for breaking changes | Recommended |

## Prohibited Actions

**NEVER use `protoc` command directly.** Always use Make targets for code generation.

```bash
# ❌ PROHIBITED - Never run protoc directly
protoc --go_out=... proto/*.proto

# ✅ CORRECT - Always use Make targets
make proto      # Go only
make proto-ts   # TypeScript only
make proto-all  # Both
```

## Code Generation [DEPRECATED for XRP]

> **⚠️ Note**: Proto generation commands no longer needed for XRP.

| Command | Purpose | XRP Status |
|---------|---------|------------|
| `make proto` | Generate Go code from proto files | ⚠️ No longer generates XRP |
| `make proto-ts` | Generate TypeScript code from proto files | ❌ XRP TypeScript deprecated |
| `make proto-all` | Generate all proto files (Go + TypeScript) | ⚠️ XRP not included |
| `make proto-fmt` | Format proto files | ⚠️ XRP protos deprecated |
| `make clean-pb` | Clean all generated protobuf files | ⚠️ XRP files no longer generated |

### Generation Workflow

```bash
# 1. Edit proto files
# proto/rippleapi/*.proto

# 2. Format
make proto-fmt

# 3. Check breaking changes (optional)
make proto-breaking

# 4. Generate code
make proto      # Go only
make proto-ts   # TypeScript only
make proto-all  # Both Go and TypeScript

# 5. Verify build
make check-build
```

## Buf Configuration

This project uses [Buf](https://buf.build/) for proto management.

### Configuration Files

| File | Description |
|------|-------------|
| `buf.yaml` | Module configuration and lint rules |
| `buf.gen.yaml` | Code generation configuration |

### Lint Rules

Using BASIC ruleset with exceptions for backward compatibility:

```yaml
lint:
  use:
    - BASIC
  except:
    - ENUM_VALUE_PREFIX
    - ENUM_ZERO_VALUE_SUFFIX
    - FIELD_LOWER_SNAKE_CASE
    - PACKAGE_DIRECTORY_MATCH
    - PACKAGE_SAME_DIRECTORY
    - DIRECTORY_SAME_PACKAGE
```

## Proto File Structure

```protobuf
syntax = "proto3";

package rippleapi;

option go_package = "github.com/hiromaily/go-crypto-wallet/internal/infrastructure/api/xrp/xrp";

// Service definitions
service AccountService {
  rpc GetAccountInfo(GetAccountInfoRequest) returns (GetAccountInfoResponse);
}

// Message definitions
message GetAccountInfoRequest {
  string address = 1;
}
```

## Auto-Generated Files

**DO NOT EDIT** generated files:

- `internal/infrastructure/api/xrp/xrp/*.pb.go`

These are regenerated by `make proto`.

## Best Practices

### Naming

- Use lowercase snake_case for field names
- Use PascalCase for message and service names
- Use UPPER_SNAKE_CASE for enum values

### Versioning

- Maintain backward compatibility
- Use `make breaking-proto` to detect breaking changes
- Consider field deprecation before removal

### Field Numbers

- Never reuse field numbers
- Reserve removed field numbers

```protobuf
message Example {
  reserved 1, 2;  // Previously used field numbers
  reserved "old_field";  // Previously used field names
}
```

## Quick Checklist

- [ ] `make proto-fmt` passes
- [ ] `make proto-breaking` passes (no unintended breaking changes)
- [ ] Field numbers are not reused
- [ ] Backward compatibility maintained
- [ ] Code regenerated after changes (`make proto` or `make proto-all`)
- [ ] `make check-build` passes after generation

## Related Documentation

- @buf.yaml - Buf configuration
- @buf.gen.yaml - Code generation configuration
- @proto/rippleapi/ - Proto source files

## Related Skills

- `go-development` - Go verification after generation