RWA-PROXY Service

RWA-PROXY is a backend service providing RESTful endpoints for account management, asset registration, token distribution, and transaction status tracking on the Kadena blockchain. The service is documented via OpenAPI and supports secure configuration through environment variables.

Features

• Account creation and retrieval
• Asset identity registration
• Token distribution and transfer
• Transaction status querying
• Health check endpoint
• Webhook integration
• Secure mTLS support

API Endpoints

Endpoint	Method	Summary	Parameters / Body	Response Description
/health	GET	Health check	None	200: OK
/account	GET	Get account info	Query: accountName (string, required)	200: Account info
/account	POST	Create or return account	None	200: Account response
/asset/register	POST	Register identity for asset	JSON: { accountName: string } (required)	200: Transaction result
/asset/distribute	POST	Distribute tokens to investor account	JSON: { amount: number, accountName: string } (required)	200: Transaction result
/asset/transfer	POST	Transfer tokens between investor accounts	JSON: { amount: number, fromAccountName: string, toAccountName: string }	200: Transaction result
/status	GET	Get transaction status	Query: requestKey (string, required), chainId (string, optional), networkId (string, optional)	200: Transaction status result
/doc	GET	OpenAPI JSON documentation	None	200: OpenAPI spec
/ui	GET	Swagger UI	None	200: Swagger UI

Environment Variables

Name	Description	Default Value
PORT	Port for HTTP server	8090
LOG_LEVEL	Logging level (info, debug, etc.)	info
NODE_ENV	Node environment (production, development, test)	production
CHAINWEB_HOST	Chainweb node host URL	http://localhost:8080
CHAINWEB_CHAIN_ID	Chainweb chain ID	0
CHAINWEB_NETWORK_ID	Chainweb network ID	mainnet01
RWA_CONTRACT_NAME	RWA contract name (required)
RWA_NAMESPACE	RWA contract namespace (required)
RWA_AUTO_REGISTER	New accounts are automatically registered on the RWA	true
WEBHOOK_URL	Webhook endpoint URL
WEBHOOK_RETRIES	Number of webhook retries	5
WEBHOOK_RETRY_BASE_DELAY_MS	Webhook retry base delay in ms	1000
SQLITE_PATH	SQLite database path	:memory:
REJECT_UNAUTHORIZED	Reject unauthorized TLS connections (true/false)	true
CERT / CERT_FILE	TLS certificate (value or file path)
KEY / KEY_FILE	TLS private key (value or file path)
CA / CA_FILE	TLS CA certificate (value or file path)
OPERATOR_ACCOUNT_NAME / OPERATOR_ACCOUNT_NAME_FILE	Operator account name (value or file path, required)
OPERATOR_PUBLIC_KEY / OPERATOR_PUBLIC_KEY_FILE	Operator public key (value or file path, required)
OPERATOR_SECRET_KEY / OPERATOR_SECRET_KEY_FILE	Operator secret key (value or file path, required)

Webhook

when WEBHOOK_URL environment variable is configured the service will send POST requests to that URL with information about a completed transaction. it will be submitted with content-type: application/json header and a JSON-formatted body with the following information:

{
  "requestKey": "123",
  "chainId": "0",
  "networkId": "mainnet01",
  "event": "account-created | account-registered | token-distributed | token-transferred",
  "payload": { "accountName": "example" },
  "timestamp": "123", // When the transaction was finished
  "retries": 0, // How many attempts the service made at reaching the webhook endpoint (non-200 status will cause retry)
  "status": "success | failure",
  "error": "if failure, error message" // `null` if success
}

Payload will be different depending on the event.

SQLite

The services makes use of a SQLite database to wait for transactions to complete and for the webhooks. By default this is an in-memory store so if the service stops any pending transactions or webhooks will not finish, this can impact automatically registering accounts after creation and guaranteed delivery of webhook messages. To improve reliability you can persist the SQLite database with the SQLITE_PATH environment variable. in the case of a docker container that would include mounting a volume with the same path

Usage

1. Set required environment variables (see table above).

2. Start the service:

   bun start

3. Access API documentation at /ui.

License

BSD-3-Clause