Initial commit: smart contract templates for bash, go, python, and typescript
This commit is contained in:
197
README.md
Executable file
197
README.md
Executable file
@@ -0,0 +1,197 @@
|
||||
# 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]
|
||||
Reference in New Issue
Block a user