Oracle Setup
This guide covers the Neutron-specific setup for the Connect oracle service. For detailed configuration options and advanced setups, see Skip's Connect documentation.
Neutron uses Connect v1.x, not v2.x. All binaries must come from neutron-org/connect.
Prerequisites
- A running Neutron validator node (see Running a Node)
- Root or sudo access to your server
- gRPC enabled on your Neutron node (port 9090 by default)
- Outbound internet access for Connect to reach price providers
You must run Connect if you are operating a validator. Non-validator nodes do not need Connect.
Installation
Choose your preferred installation method:
Configure Neutron Node
Edit your node's app.toml to enable oracle functionality:
nano ~/.neutrond/config/app.toml
Add or update the [oracle] section:
###############################################################################
### Oracle ###
###############################################################################
[oracle]
# Enable oracle (required for validators)
enabled = "true"
# Connect sidecar address
oracle_address = "0.0.0.0:8080"
# Timeout for oracle responses
client_timeout = "2s"
# Enable metrics
metrics_enabled = "true"
# Update interval (should match block time)
interval = "1500ms"
# Maximum price age before considered stale
price_ttl = "10s"
# Prometheus metrics address
prometheus_server_address = "0.0.0.0:8001"
Configuration notes:
- Use lowercase
"true"for boolean values (not"True") - Ensure gRPC is enabled in the same file (typically port 9090)
- The
oracle_addressmust match where Connect will listen
Verify gRPC is enabled:
[grpc]
enable = true
address = "0.0.0.0:9090"
Restart your Neutron node:
sudo systemctl restart neutrond
Configure Connect Service
Create a systemd service file:
sudo nano /etc/systemd/system/connect.service
Add the following:
[Unit]
Description=Connect Price Oracle Service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=neutron
Group=neutron
ExecStart=/usr/local/bin/connect \
--market-map-endpoint="127.0.0.1:9090" \
--host="0.0.0.0" \
--port="8080" \
--log-std-out-level="info" \
--metrics-enabled="true" \
--metrics-prometheus-address="0.0.0.0:8002"
Restart=always
RestartSec=3
LimitNOFILE=65535
StandardOutput=journal
StandardError=journal
SyslogIdentifier=connect
[Install]
WantedBy=multi-user.target
Replace neutron:neutron with the user/group that runs your validator node.
Start Connect
Enable and start the service:
# Reload systemd
sudo systemctl daemon-reload
# Enable on boot
sudo systemctl enable connect
# Start service
sudo systemctl start connect
# Check status
sudo systemctl status connect
Verify Setup
1. Check Connect is Running
sudo journalctl -u connect -n 50 -f
Look for successful startup messages and price updates.
2. Query Connect API
curl -s http://localhost:8080/connect/oracle/v2/prices | jq -r '.timestamp'
Should show a recent timestamp (within last few seconds).
3. Verify Oracle Integration
curl -s http://localhost:26660/metrics | grep 'app_oracle_responses'
Expected output:
app_oracle_responses{chain_id="neutron-1",status="Failure"} 42
app_oracle_responses{chain_id="neutron-1",status="Success"} 15847
The Success count should be continuously increasing.
Common Issues
Connect can't connect to node
Error: failed to connect to market map endpoint
Solution: Verify gRPC is enabled and accessible:
grpcurl -plaintext localhost:9090 list
Ensure --market-map-endpoint matches your node's gRPC address.
Boolean configuration errors
Error: invalid boolean value "True"
Solution: Use lowercase in app.toml:
enabled = "true" # ✅ Correct
enabled = "True" # ❌ Wrong
Permission denied
Solution: Check service user has proper permissions:
# Verify user in service file matches actual user
ps aux | grep neutrond
Neutron-Specific Considerations
Version Compatibility
Always use v1.x releases from neutron-org/connect. Skip's upstream v2.x is not compatible with Neutron.
Performance Requirements
Maintain ≥95% oracle success rate for validator rewards:
# Quick success rate check
TOTAL=$(curl -s http://localhost:26660/metrics | grep 'app_oracle_responses{.*status="Success"}' | awk '{print $2}')
FAILURES=$(curl -s http://localhost:26660/metrics | grep 'app_oracle_responses{.*status="Failure"}' | awk '{print $2}')
SUCCESS_RATE=$(awk "BEGIN {print ($TOTAL / ($TOTAL + $FAILURES)) * 100}")
echo "Oracle success rate: ${SUCCESS_RATE}%"
See Validator Incentives for reward details.