sc-templates/README.md

# Dragonchain Smart Contract Templates

This repository contains templates for creating smart contract clients that connect to Dragonchain Prime via gRPC.

## Available Templates

| Template | Language | Directory |
|----------|----------|-----------|
| Go | Go 1.21+ | [go/](./go/) |
| Python | Python 3.10+ | [python/](./python/) |
| TypeScript | Node.js 18+ | [typescript/](./typescript/) |

## How It Works

Smart contracts connect to the Dragonchain Prime server using a bi-directional gRPC stream. The server sends transaction requests to your smart contract, which processes them and sends back responses.

```
┌─────────────────┐                    ┌─────────────────────┐
│                 │  SmartContractRequest │                     │
│   Dragonchain   │ ──────────────────────► │   Smart Contract    │
│   Prime Server  │                    │      Client          │
│                 │ ◄────────────────────── │                     │
│                 │  SmartContractResponse │                     │
└─────────────────┘                    └─────────────────────┘
```

### Request Flow

1. Your client connects to the server with API key and smart contract ID
2. The server sends `SmartContractRequest` messages containing:
   - `transaction_id` - Unique identifier for correlation
   - `transaction_json` - The transaction data to process
   - `env_vars` - Environment variables
   - `secrets` - Secret values (API keys, credentials)
3. Your client processes the transaction and sends back `SmartContractResponse`:
   - `transaction_id` - Same ID from the request
   - `result_json` - Your processing result as JSON
   - `logs` - Any logs captured during execution
   - `output_to_chain` - Whether to persist the result
   - `error` - Error message if processing failed

## Quick Start

### 1. Choose a Template

Pick the template for your preferred language:

```bash
# For Go
cp -r go /path/to/my-smart-contract

# For Python
cp -r python /path/to/my-smart-contract

# For TypeScript/JavaScript
cp -r typescript /path/to/my-smart-contract
```

### 2. Configure

Edit `config.yaml` with your credentials:

```yaml
server_address: "your-server:50051"
smart_contract_id: "your-smart-contract-id"
api_key: "your-api-key"
```

### 3. Implement Your Logic

Each template has a `Process` (Go), `process` (Python/TypeScript) function. Implement your business logic there:

**Go** (`cmd/main.go`):
```go
func Process(ctx context.Context, txJSON string, envVars, secrets map[string]string) ProcessResult {
    // Your logic here
    return ProcessResult{Data: result, OutputToChain: true}
}
```

**Python** (`main.py`):
```python
def process(tx_json: str, env_vars: dict, secrets: dict) -> ProcessResult:
    # Your logic here
    return ProcessResult(data=result, output_to_chain=True)
```

**TypeScript** (`src/main.ts`):
```typescript
async function process(txJson: string, envVars: Record<string, string>, secrets: Record<string, string>): Promise<ProcessResult> {
    // Your logic here
    return { data: result, outputToChain: true };
}
```

### 4. Build and Run

Each template includes a Makefile:

```bash
# Install dependencies
make setup

# Generate proto code (Go and Python only)
make proto

# Build
make build

# Run
make run
```

## Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `server_address` | gRPC server address (host:port) | Required |
| `smart_contract_id` | Your smart contract ID | Required |
| `api_key` | API key for authentication | Required |
| `use_tls` | Enable TLS encryption | `false` |
| `tls_cert_path` | Path to TLS certificate | - |
| `num_workers` | Concurrent transaction processors | `10` |
| `reconnect_delay_seconds` | Reconnection delay | `5` |
| `max_reconnect_attempts` | Max retries (0 = infinite) | `0` |

## Environment Variables

Your smart contract receives these environment variables:

| Variable | Description |
|----------|-------------|
| `TZ` | Timezone |
| `ENVIRONMENT` | Deployment environment |
| `INTERNAL_ID` | Internal identifier |
| `DRAGONCHAIN_ID` | Dragonchain ID |
| `DRAGONCHAIN_ENDPOINT` | Dragonchain API endpoint |
| `SMART_CONTRACT_ID` | This smart contract's ID |
| `SMART_CONTRACT_NAME` | This smart contract's name |
| `SC_ENV_*` | Custom environment variables |

## Secrets

Secrets are passed separately from environment variables and are prefixed with `SC_SECRET_`. Access them via the `secrets` parameter in your process function.

## Concurrent Processing

All templates support concurrent transaction processing. Configure the number of workers with `num_workers` in your config file. Each incoming request is processed in parallel up to the worker limit.

## Reconnection

All templates include automatic reconnection logic. If the connection is lost, the client will attempt to reconnect with exponential backoff based on `reconnect_delay_seconds`. Set `max_reconnect_attempts` to limit retry attempts (0 = infinite).

## Docker Examples

Each template README includes a Docker example. General pattern:

```dockerfile
# Build stage
FROM <base-image> AS builder
COPY . .
RUN <build-commands>

# Runtime stage
FROM <runtime-image>
COPY --from=builder <artifacts> .
CMD [<run-command>]
```

## Development

### Prerequisites

**Go:**
- Go 1.21+
- protoc
- protoc-gen-go, protoc-gen-go-grpc

**Python:**
- Python 3.10+
- pip

**TypeScript:**
- Node.js 18+
- npm

### Testing

Each template supports testing. Add tests and run:

```bash
make test
```

## License

[Your License Here]