# ProlificEx TRON Signer Service

This service is the private-key boundary for the gateway. Laravel must never receive raw private keys.

## What It Does

- Generates TRON deposit addresses for invoices.
- Stores private keys encrypted in `data/keystore.json` for local MVP testing.
- Validates TRON addresses.
- Signs and broadcasts USDT-TRC20 transfers through TronGrid.
- Exposes the endpoints Laravel already expects.

## Endpoints

All protected endpoints require:

```http
Authorization: Bearer TRON_SIGNER_TOKEN
```

Health:

```http
GET /health
```

Create or get the default hot wallet:

```http
POST /v1/hot-wallet
GET  /v1/hot-wallet
```

Create invoice deposit address:

```http
POST /v1/addresses
```

Body:

```json
{
  "network": "tron",
  "environment": "sandbox",
  "reference": "pay_01..."
}
```

Validate address:

```http
POST /wallet/validateaddress
```

Body:

```json
{
  "address": "T..."
}
```

Create signed transfer:

```http
POST /v1/transfers
```

Body:

```json
{
  "network": "tron",
  "asset_code": "USDTTRC20",
  "to_address": "T...",
  "amount_atomic": "1000000",
  "idempotency_key": "payout-po_..."
}
```

Get transfer:

```http
GET /v1/transfers/{id}
```

## Local Run

From `signer/`:

```bash
npm install
npm start
```

Current Laravel `.env` should point to:

```env
BLOCKCHAIN_DRIVER=self_hosted_tron
TRON_NODE_URL=https://api.trongrid.io
TRON_SIGNER_URL=http://127.0.0.1:8787
TRON_USDT_CONTRACT_ADDRESS=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
```

## Hot Wallet Requirement

Payouts are sent from the default hot wallet. Create it once:

```http
POST /v1/hot-wallet
```

Then fund that public address with:

- TRX for gas/bandwidth/energy fees
- USDT-TRC20 for payouts

Without TRX, USDT transfers will fail.

## Security Warning

The local MVP keystore encrypts private keys with `TRON_KEYSTORE_SECRET`. This is acceptable for local testing only.

Before real merchant funds:

- Move key custody to AWS KMS, Google Cloud KMS, Vault, or HSM.
- Restrict signer access by private network, firewall, and ideally mTLS.
- Rotate `TRON_SIGNER_TOKEN` and `TRON_WEBHOOK_SECRET`.
- Add audit logging for every address and transfer.
- Add withdrawal limits and manual approval policies inside signer too.
- Run external security review.

If private keys leak, funds are permanently lost.
