proxmox/token-lists/chainlists/SUBMISSION_GUIDE.md

# Chainlists Submission Guide

This directory contains files needed to submit DBIS Chain 138 to Chainlists.org.

---

## Files

- `chain-138.json` - Chain configuration in Chainlists format
- `SUBMISSION_GUIDE.md` - This file

## Token List

The token list is available at:
- `../lists/dbis-138.tokenlist.json`
- Public URL (when hosted): `https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json`

---

## Submission Process

### Option 1: GitHub Pull Request (Recommended)

1. **Fork the Chainlists repository**
   - Go to: https://github.com/ethereum-lists/chains
   - Click "Fork" to create your fork

2. **Clone your fork**
   ```bash
   git clone https://github.com/{your-username}/chains.git
   cd chains
   ```

3. **Add chain configuration**
   - Copy `chain-138.json` to `_data/chains/eip155-138/chain.json`
   - The directory structure should be: `_data/chains/eip155-{chainId}/chain.json`
   ```bash
   mkdir -p _data/chains/eip155-138
   cp /path/to/token-lists/chainlists/chain-138.json _data/chains/eip155-138/chain.json
   ```

4. **Validate the configuration**
   - Review the JSON structure
   - Ensure all URLs are accessible
   - Verify RPC endpoints are working

5. **Create pull request**
   ```bash
   git checkout -b add-dbis-chain-138
   git add _data/chains/eip155-138/chain.json
   git commit -m "Add DBIS Chain (ChainID 138)"
   git push origin add-dbis-chain-138
   ```
   - Then create a pull request on GitHub

6. **PR Requirements**
   - Provide brief description of the chain
   - Include links to documentation/website
   - Ensure all URLs in the config are publicly accessible
   - Mention any special features or use cases

### Option 2: Direct Submission

If Chainlists provides a submission form on their website, use it with the information from `chain-138.json`.

---

## Required Information

- **Chain ID**: 138 (0x8a)
- **Network Name**: DBIS Chain / SMOM-DBIS-138
- **RPC URLs**: 
  - Primary: `https://rpc-core.d-bis.org`
  - Secondary: `https://rpc-http-pub.d-bis.org`
- **Block Explorer**: `https://explorer.d-bis.org`
- **Native Currency**: ETH (18 decimals)
- **Website**: `https://d-bis.org` (if available)
- **Short Name**: `dbis`

---

## Token List Submission

Token lists can be submitted separately:

1. **Host token list at public URL**
   - Use GitHub Pages or GitHub Raw URL
   - Ensure proper CORS headers
   - Verify accessibility

2. **Submit to Token List Registry**
   - Ensure token list follows Uniswap Token Lists specification
   - Validate using: `node ../scripts/validate-token-list.js ../lists/dbis-138.tokenlist.json`
   - Submit URL to Chainlists token list registry (if available)

3. **Link to Chain Configuration**
   - Token list should reference ChainID 138
   - Ensure consistency between chain config and token list

---

## Validation

Before submitting, validate the chain configuration:

```bash
# Validate JSON structure
cat chain-138.json | jq .

# Verify required fields
jq -e '.chainId == 138' chain-138.json
jq -e '.rpc | length > 0' chain-138.json
jq -e '.nativeCurrency.symbol == "ETH"' chain-138.json

# Use validation script
node ../scripts/validate-chainlists.js chain-138.json
```

### Test RPC Endpoints

```bash
# Test primary RPC
curl -X POST https://rpc-core.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

# Should return: {"jsonrpc":"2.0","id":1,"result":"0x8a"}

# Test secondary RPC
curl -X POST https://rpc-http-pub.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
```

### Test Block Explorer

```bash
# Test explorer accessibility
curl -I https://explorer.d-bis.org

# Should return HTTP 200 or 301/302 redirect
```

---

## Chainlists Format Reference

The chain configuration follows the Chainlists format:

```json
{
  "name": "Display name",
  "chain": "Chain identifier",
  "rpc": ["RPC URL array"],
  "faucets": ["Faucet URLs if available"],
  "nativeCurrency": {
    "name": "Currency name",
    "symbol": "Currency symbol",
    "decimals": 18
  },
  "infoURL": "Information website URL",
  "shortName": "Short identifier",
  "chainId": 138,
  "networkId": 138,
  "explorers": [{
    "name": "Explorer name",
    "url": "Explorer URL",
    "standard": "EIP3091"
  }],
  "icon": "Icon URL (optional)"
}
```

---

## Post-Submission

After your chain is added to Chainlists:

1. **Verify on Chainlists.org**
   - Search for "DBIS" or ChainID 138
   - Verify all information displays correctly
   - Test "Add to MetaMask" functionality

2. **Update Documentation**
   - Reference Chainlists in your documentation
   - Link to Chainlists entry
   - Update integration guides

3. **Monitor**
   - Check for user feedback
   - Update if RPC URLs or explorer URLs change
   - Keep chain information current

---

## References

- [Chainlists Repository](https://github.com/ethereum-lists/chains)
- [Chainlists Website](https://chainlist.org)
- [Uniswap Token Lists](https://github.com/Uniswap/token-lists)
- [EIP-155: Simple replay attack protection](https://eips.ethereum.org/EIPS/eip-155)
- [EIP-3091: Block Explorer API](https://eips.ethereum.org/EIPS/eip-3091)

---

**Last Updated**: 2025-12-22