oriS-casino / andromeda-bep20-payment-gateway-document

tài liệu về Deployment và API của cổng thanh toán tiền ảo Andromeda.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ANDROMEDA Bep20 Payment Gateway

Cung cấp kênh thanh toán trên mạng Binance Smart Chain ứng với các loại token Bep20.

Contact Me: https://t.me/DontBeSad_Cuz_MinhFatIsHere

Mục lục

email: dangnguyendota@gmail.com

Library

Client viết bằng Golang: https://github.com/dangnguyendota-casino/go-andromeda-client

Config

Trong thư mục configs/ chứa file config.example.yaml là mẫu config, chứa các trường cần có. Copy file config.example.yaml sang file config.yaml và sửa lại các trường này.

config.example.yaml

log: ./logs
debug: false
maxWallets: 10000
amqpURI: "amqp://guest:guest@andromeda-rabbitmq:5672/"
mongoDNS: "mongodb://andromeda:andromeda@andromeda-mongodb:27017"
hotWalletMnemonic: ""
numberOfConfirmationsToApproveDepositTx: 15
tokens:
  - name: type-token-name
    decimals: 18
    address: type-token-address
    minToCollect: 1
  - name: type-token-name
    decimals: 18
    address: type-token-address
    minToCollect: 1
chainID: 56
chainRPCEndpoint: https://bsc-dataseed.binance.org/
APIPostDepositTransactionURL: https://example.com/user-deposited
APIPostTokensTransferredURL: https://example.com/transferred-tokens
ipWhiteList:
  - localhost
  - 192.168.1.0
APIKey: example-key
password: example-password

Giải thích các trường:

  • log string đường dẫn tới thư mực lưu log. (default: ./logs)
  • debug bool true nếu ở chế độ debug, ở chế độ này sẽ ghi log chi tiết hơn để dễ dàng cho việc debug.
  • maxWallets int số lượng ví tối đa có thể tạo, ví dụ hệ thống chỉ cần tạo 1000 ví cho các user id từ 1 tới 1000 thì đặt maxWallets = 1000.
  • amqpURI string uri connect với rabbitmq, default là amqp://guest:guest@andromeda-rabbitmq:5672/ là uri của rabbitmq chạy trong andromeda service, nếu muốn dùng rabbitmq khác chạy bên ngoài thì đặt lại trường này.
  • mongoDNS string uri tới mongodb, default là mongodb://andromeda:andromeda@andromeda-mongodb:27017 là uri tới mongodb chạy trong andromeda service, nếu muốn móc sang mongo db khác chạy bên ngoài thì sửa lại trường này.
  • hotWalletMnemonic string chuỗi mnemonic (hay trên metamask gọi là Cụm mật khẩu khôi phục bí mật) của ví tổng, ví dụ 1 mnemonic: mistake wet reward valid gesture drop delay soft say same energy upon
  • numberOfConfirmationsToApproveDepositTx int số lượng tối thiểu xác nhận để giao dich có thể coi là hợp lệ, số này càng nhỏ thì khả năng cheat của user càng cao, thường sẽ từ 15 trở lên, tuy nhiên nếu để quá cao có thể thời gian của người chơi để chờ xác nhận giao dịch sẽ lâu hơn nhiều.
  • tokens array là mảng các loại token được hỗ trợ
    • name string tên duy nhất của token (do mình tự đặt) (ví dụ: usdt, usdc, bnb, busd,...)
    • decimals int decimal của token.
    • address string địa chỉ của token.
    • minToCollect int số lượng token tối thiểu có trong ví con để andromeda thực hiện rút tiền về ví tổng, bởi vì mỗi lần rút sẽ mất khoảng 0.2$ phí giao dịch, nên phải giới hạn rút đối với số lượng tiền tối thiểu, tránh số tiền quá nhỏ vẫn thực hiện rút dẫn đến tình trạng tiền không đủ bù phí giao dịch. Một user có thể nạp nhiều lần số nhỏ, khi đạt đủ số lượng hệ thống mới thực hiện rút tiền về ví tổng nhằm tiết kiệm chi phí.
  • chainID id của mạng (56 với mainnet và 97 với mạng testnet)
  • chainRPCEndpoint string rpc endpoint của mạng (mainnet: https://bsc-dataseed.binance.org/ , testnet https://data-seed-prebsc-1-s1.binance.org:8545/)
  • APIPostDepositTransactionURL string đường dẫn tới API Complete Deposit Transaction Redirect URL
  • APIPostTokensTransferredURL string đường dẫn tới API API Complete Transferred Tokens Redirect URL
  • ipWhiteList array các địa chỉ IP hợp lệ có thể gửi request lên, nếu mảng này rỗng thì sẽ accept request của mọi địa chỉ IP.
  • APIKey string API Key của hệ thống, phải khớp ở cả 2 đầu Andromeda ServiceGame Service, đây sẽ là mã khóa bí mật không được để tiết lộ ra ngoài.
  • password string là mật khẩu dùng để xác thực đơn giản trong API, nếu password được gán thì mỗi request đều phải gửi lên kèm password trong Header.

Deployment

Andromeda gồm 3 thành phần chính: Cash In, Cash Out và API. Để khởi chạy toàn hệ thống:

sudo docker compose up -d 

Hoặc chạy từng phần như sau:

Bước 1: Tạo file config.yaml trong thư mục configs/ theo hướng dẫn ở phần trên. Bước 2: Chạy API Service

sh  deploy-API-service.sh

Bước 3: Chạy Cash In

sh deploy-CI-services.sh

Bước 4: Chạy Cash Out

sh deploy-CO-services.sh

Bước 5: Tạo ví cho người dùng

sh create-user-wallet.sh

Nếu không dùng hệ điều hành Linux thì dùng lệnh sau:

sudo docker exec -it andromeda-api ./andromeda migrate --create-user-wallet --mongo-dns="mongodb://andromeda:andromeda@andromeda-mongodb:27017"

Bước 6: Kiểm tra các service đã chạy lên đầy đủ chưa:

sudo docker compose ps 

Kết quả sẽ hiện lên như sau

NAME                   COMMAND                  SERVICE             STATUS              PORTS
andromeda-api          "/usr/bin/supervisor…"   api                 running (healthy)   0.0.0.0:9711->9711/tcp, :::9711->9711/tcp
andromeda-approver     "/usr/bin/supervisor…"   approver            running (healthy)   
andromeda-collector    "/usr/bin/supervisor…"   collector           running (healthy)   
andromeda-dispatcher   "/usr/bin/supervisor…"   dispatcher          running (healthy)   
andromeda-mongodb      "docker-entrypoint.s…"   mongo               running (healthy)   0.0.0.0:9707->27017/tcp, :::9707->27017/tcp
andromeda-rabbitmq     "docker-entrypoint.s…"   rabbitmq            running (healthy)   25672/tcp
andromeda-transactor   "/usr/bin/supervisor…"   transactor          running (healthy)   
andromeda-validator    "/usr/bin/supervisor…"   validator           running (healthy)   
andromeda-watcher      "/usr/bin/supervisor…"   watcher             running (healthy)  

Tình trạng các service đều ở trạng thái healthy là ok.

Port của API sẽ là port 9711 và port của mongo db là 9707 username và password là andromeda.

Hệ thống gồm các thành phần sau đây:

  • Cở sở dữ liệu: mongo db, mở port 9707 ra ngoài, username: andromeda, password: andromeda.
    • docker compose service: mongo
    • image: mongo
    • container: andromeda-mongo
    • run: sh restart-mongodb.sh
  • Message Broker: rabbitmq
    • docker compose service: rabbitmq
    • image: rabbitmq:3.8.25-management-alpine
    • container: andromeda-rabbitmq
    • run: sh restart-rabbitmq.sh
  • Cash In: thực hiện ghi nhận các giao dịch nạp tiền vào hệ thống và bắn thông báo sang Game Service.
    • module watcher thực hiện lắng nghe các giao dịch trên mạng.
      • docker compose service: watcher
      • image: andromeda/watcher:v1.0.0
      • container: andromeda-watcher
      • run: sh restart-watcher.sh
    • module validator thực hiện xác thực giao dịch có đúng thuộc user của hệ thống hay không
      • docker compose service: validator
      • image: andromeda/validator:v1.0.0
      • container: andromeda-validator
      • run: sh restart-validator.sh
    • module approver thực hiện kiểm tra giao dịch đã đạt đủ số lượng xác nhận từ các node trên mạng chưa, để tránh hack.
      • docker compose service: approver
      • image: andromeda/approver:v1.0.0
      • container: andromeda-approver
      • run: sh restart-approver.sh
    • module dispatcher nhận các yêu cầu vào gửi thông báo qua API sang bên Game Service.
      • docker compose service: dispatcher
      • image: andromeda/dispatcher:v1.0.0
      • container: andromeda-dispatcher
      • run: sh restart-dispatcher.sh
    • module collector thực hiện thu hồi token tự động từ các ví con về ví tổng.
      • docker compose service: collector
      • image: andromeda/collector:v1.0.0
      • container: andromeda-collector
      • run: sh restart-collector.sh
  • Cash Out: thực hiện lấy các yêu cầu rút tiền về tài khoản người dùng và chuyển tiền vào ví của người dùng.
    • module transactor nhận yêu cầu rút tiền từ hệ thống và thực hiện chuyển tiền sang ví của user.
      • docker compose service: transactor
      • image: andromeda/transactor:v1.0.0
      • container: andromeda-transactor
      • run: sh restart-transactor.sh
  • API Server: cung cấp các API để Game Service có thể làm việc với Andromeda, port 9711.
    • docker compose service: api
    • image: andromeda/api:v1.0.0
    • container: andromeda-api
    • run: sh restart-api.sh
  • Data: thư mục data/ chứa dữ liệu của database và rabbitmq, không được thay đổi quyền của thư mục và không được xóa thư mục nếu không dữ liệu sẽ bị mất.
  • Log: thư mục logs/chứa log của hệ thống, log sẽ ghi theo ngày và sẽ có tên của module ứng với file log đó. Ví dụ file 2022-07-19.api.log chứa log của API vào ngày 19 tháng 7 năm 2022. File stdout.log ghi log std.
  • Tạo ví: Sau khi khởi động hệ thống lần đầu tiên, cơ sở dữ liệu sẽ chưa có thông tin ví của người dùng, mà ta phải tạo ví bằng tay. Lệnh sẽ sử dụng Mnemonic trong file config làm ví tổng để tạo ví con và MaxWallets trong config để xác định số lượng tối đa ví sẽ tạo.
    • Run: sh create-user-wallet.sh hoặc sudo docker exec -it andromeda-api ./andromeda migrate --create-user-wallet --mongo-dns="mongodb://andromeda:andromeda@andromeda-mongodb:27017"
  • Dọn dẹp Watched Block: Nếu hệ thống chạy sai hoặc thay đổi Chain thì phải Clean lại bảng watched_block trong DB vì bảng này lưu vị trí block gần nhất crawl được từ Chain, mà mỗi chain thì số block khác nhau nên phải clean để tự cập nhật lại, thao tác này có thể dẫn đến mất mát dữ liệu trong khoảng thời gian ngắn.
    • Run: sh clean-watched-block.sh

Run Test

sudo docker exec -it andromeda-api ./andromeda test --amount-per-transaction=0.001 --number-of-transactions=10 --private-key=bde426c3c03bf9254c629c3a1407c0278fa7ddd9e13b6ffdec7f5fa4e8f69069 --token=usdt

Flags:

  • amount-per-transaction float số tiền gửi trên 1 giao dịch.
  • number-of-transactions int số lượng giao dịch.
  • private-key string private key của tài khoản dùng để gửi tiền.
  • token string loại tiền gửi.

Database

deposit_transactions

Bảng lưu thông tin các giao dịch.

withdraw_transactions

users

last_watched_block

failed_request

API

Lưu ý: Nếu Password được set thì khi call API bắt buộc phải đặt trường Authorization trong header theo cú pháp "Password " + password. Ví dụ nếu password là "example" thì trường Authorization sẽ là "Password example".

Đối với tất cả các API bên dưới thì sẽ trả về các Status Code chung sau:

  • 406 Not Acceptable đối với địa chỉ IP không nằm trong white list.
  • 401 Unauthorized đối với password không được gắn trong Header hoặc không trùng với password hệ thống.

Complete Player Deposit Transaction Redirect URL

Sau khi phát hiện giao dịch nạp tiền và xác thực giao dịch, Andromeda sẽ gửi thông báo sang Game Service để thông báo giao dịch nạp tiền đã hoàn tất.

Game Service phải cung cấp API để Andromeda gửi thông báo sang, Andromeda sẽ thực hiện tôi đa 3 lần gọi với mỗi giao dịch ghi nhận được, nếu vượt quá số lượng trên, gói tin sẽ được lưu trữ vào trong cơ sở dữ liệu.

Thông tin API:

  • API URL: tự khai báo ở trong Config, ứng với API viết bên Game Service. (ví dụ: https://game.service.com/api/v1/user-deposited)
  • Method: POST
  • Status Code: 202 nếu thành công hoặc khác nếu thất bại, nếu trả về status code khác 202 Adromeda sẽ cố gắng gửi lại thêm 2 lần nữa, không thành công sẽ lưu vào bảng failed_request.
  • Body:
    • user_id int ID của người chơi
    • tx_hash string mã giao dịch
    • tokens float số lượng tokens nạp.
    • token_name string tên token.
    • token_address string địa chỉ token.
    • decimals int decimals của token (thường là 18)
    • chain_id int id của chain nạp (56 với mạng mainnet, 97 với mạng testnet)
    • check_sum string bằng MD5(API_KEY + TxHash) dùng để xác thực request này có thật sự tới từ Andromeda Service không, vì nếu tới từ bên ngoài thì sẽ không thể dò ra được check_sum tương ứng với tx_hash do không thể biết được API_KEY.

Lưu ý:

  • Game Service phải lưu lại tx_hash vào database để kiểm tra xem giao dịch này đã được cập nhật trước đó chưa, tránh trường hợp bên thứ 3 tấn công dùng lại gói tin này gửi lên nhằm trục lợi nạp nhiều lần từ 1 giao dịch.
  • API URL để là host.docker.internal thay cho localhost nếu Andromeda ServiceGame Service chạy trong cùng 1 máy chủ.
  • API URL nên để HTTPS để tránh kẻ tấn công có thể lấy được thông tin của gói tin.
  • Bắt buộc phải kiểm tra check_sum để xác thực gói tin này có thật sự tới từ Andromeda Service hay không.
  • Ví dụ API KeyabcTx Hash0x2d157578aee3908b41192bad9af19432eb683ea872152fa3c72a2ba7a4095abb thì check_sum sẽ là hàm băm MD5 của chuỗi abc0x2d157578aee3908b41192bad9af19432eb683ea872152fa3c72a2ba7a4095abb và là ea16990b87483afaab3a4740a47a2c98
  • Có thể thực hiện kiểm tra địa chỉ IP gửi gói tin này đến Game Service để tăng thêm tính bảo mật cho hệ thống.

!Lưu ý: Mỗi khi nhận được request này từ andromeda, lưu giao dịch vào database và kiểm tra lại mỗi lần nhận được request xem tx_hash này đã được insert trước đó chưa để tránh trường hơp hacker có thể tận dụng lại request để gửi nhiều lần để chuộc lợi từ 1 giao dịch.

Complete Transferred Tokens Redirect URL

Sau khi chuyển tiền thành công vào ví người nhận, andromeda sẽ gửi thông báo sang 1 API Complete Transferred Tokens Redirect.

Game Service cung cấp API này để andromeda thông báo sang, nếu trong config để trường _ APIPostTokensTransferredURL_ là rỗng thì andromeda sẽ không thông báo nữa.

Cấu trúc:

  • URL: định nghĩa trong file config
  • Method: POST
  • Status Code: 202 nếu thành công hoặc khác nếu thất bại, nếu trả về status code khác 202 Adromeda sẽ cố gắng gửi lại thêm 2 lần nữa, không thành công sẽ lưu vào bảng failed_request.
  • Body:
    • request_id string request id mà game service gửi lên trong API Withdraw
    • user_id int ID của người chơi
    • tx_hash string mã giao dịch trên blockchain.
    • tokens float số tiền đã gửi.
    • token_name string tên tiền.
    • checksum string = MD5(API-Key + Request ID) để kiểm tra độ tin cậy của request.

!Lưu ý: Mỗi khi nhận được request này từ andromeda, lưu giao dịch vào database và kiểm tra lại mỗi lần nhận được request xem request_id này đã được complete trước đó chưa để tránh trường hơp hacker có thể tận dụng lại request để gửi nhiều lần để chuộc lợi từ 1 giao dịch.

Get User Address

Lấy địa chỉ ví của user.

GET /api/v1/user/:userID/address

Request:

  • userID int là id của user cần lấy địa chỉ ví, sẽ trả về lỗi nếu userID <= 0.

Ví dụ lấy địa chỉ ví user có id 10.

GET /api/v1/user/10/address

Response:

  • user_id int ID của user
  • address string địa chỉ ví

Status Code:

  • 400 Bad Request user id truyền lên không phải dạng số hoặc không nằm trong khoảng cho phép từ 1 tới 4294967295.
  • 404 Not Found lỗi xảy ra khi mnemonic trong config bị sai dẫn đến thuật toán không thể tìm ra địa chỉ ví.
  • 200 OK success

User Count

Trả về số lượng ví đã tạo

GET /api/v1/user/count

Response:

  • count int số lượng ví đã tạo.

Status Code:

  • 404 Not Found truy vấn cơ sở dữ liệu thất bại.
  • 200 OK success

Get User ID

Trả về User ID ứng với địa chỉ ví

GET /api/v1/user/:address/id

Ví dụ: đối với địa chỉ ví 0xB6330d4350cb2b3b8A4776eEFFA4D67299915F84

GET /api/v1/user/0xB6330d4350cb2b3b8A4776eEFFA4D67299915F84/id

Request:

  • address string địa chỉ ví, trả về lỗi nếu địa chỉ không hợp lệ.

Response:

  • user_id int id của user.
  • address string địa chỉ ví.

Status Code:

  • 400 Bad Request address không phải là địa chỉ ví.
  • 404 Not Found không tìm thấy địa chỉ ví này trong cơ sở dữ liệu.
  • 200 OK success.

Get User Deposit Transactions Count

Trả về số lượng tổng giao dịch nạp tiền đã thành công của user

GET /api/v1/:userID/deposit-transactions/count

Request:

  • userID int ID của người chơi

Response:

  • user_id int id của người chơi
  • count int số lượng giao dịch

Get User Completed Deposit Transactions

Lấy các giao dịch nạp tiền đã hoàn thành của người chơi.

GET /api/v1/user/:userID/deposit-transactions/:pageSize/:page

Request:

  • userID int id của người chơi.
  • pageSize int số lượng giao dịch tối đa lấy.
  • page int vị trí của page lấy, ví dụ page = 2, pageSize = 10 thì lấy giao dịch thứ 10 tới thứ 20.

Response:

Status Code:

  • 400 Bad Request user ID, page size, page không phải là số hoặc không hợp lệ.
  • 500 Internal Server Error không thể thực hiện truy vấn cơ sở dữ liệu.
  • 200 OK success

Get User Pending Deposit Transactions

Lấy tất cả các giao dịch nạp tiền đang chờ xác thực.

GET /api/v1/user/:userID/pending-deposit-transactions

Request:

  • userID int id của người chơi.

Response:

Status Code:

  • 400 Bad Request user ID không phải là số hoặc không hợp lệ.
  • 500 Internal Server Error không thể thực hiện truy vấn cơ sở dữ liệu.
  • 200 OK success

Get User Withdraw Transactions Count

Trả về số lượng tổng giao dịch rút tiền đã thành công của user

GET /api/v1/:userID/withdraw-transactions/count

Request:

  • userID int ID của người chơi

Response:

  • user_id int id của người chơi
  • count int số lượng giao dịch

Get User Completed Withdraw Transactions

Lấy các giao dịch rút tiền đã hoàn thành của người chơi.

GET /api/v1/user/:userID/withdraw-transactions/:pageSize/:page

Request:

  • userID int id của người chơi.
  • pageSize int số lượng giao dịch tối đa lấy.
  • page int vị trí của page lấy, ví dụ page = 2, pageSize = 10 thì lấy giao dịch thứ 10 tới thứ 20.

Response:

Status Code:

  • 400 Bad Request user ID, page size, page không phải là số hoặc không hợp lệ.
  • 500 Internal Server Error không thể thực hiện truy vấn cơ sở dữ liệu.
  • 200 OK success

Get User Pending Withdraw Transactions

Lấy tất cả các giao dịch rút tiền đang chờ thực hiện.

GET /api/v1/user/:userID/withdraw-deposit-transactions

Request:

  • userID int id của người chơi.

Response:

Status Code:

  • 400 Bad Request user ID không phải là số hoặc không hợp lệ.
  • 500 Internal Server Error không thể thực hiện truy vấn cơ sở dữ liệu.
  • 200 OK success

Withdraw

Yêu cầu hệ thống thực hiện yêu cầu rút tiền của người chơi và chuyển token sang ví của người chơi.

POST /api/v1/withdraw 

Request Body:

  • user_id int id của người chơi
  • address string địa chỉ ví
  • token_name string tên token
  • amount float số lượng token cần rút.
  • request_id string ID của giao dịch bên game service, ví dụ như ID của giao dịch lưu trong DB bên game service hoặc gì đó tương tự để hệ thống không thực hiện 1 giao dịch quá 1 lần, trong trường hợp game service gửi nhầm 2 lần 1 gói tin.
  • checksum string MD5(API-Key + request_id) mã checksum dùng để phát hiện gian lận nếu người gửi request này không phải Game Service.

Status Code:

  • 400 Bad Request dữ liệu gửi lên không hợp lệ.
  • 500 Internal Server Error không thể khởi tạo giao dịch.
  • 201 Created đã khởi tạo thành công giao dịch rút tiền.

Check Deposit Transaction

API kiểm tra giao dịch thủ công và cập nhật vào database nếu giao dịch hoàn thành

POST /api/v1/check-deposit-tx

Request:

  • user_id int id người chơi
  • transaction_hash string mã giao dịch

Response Status Code:

  • 202 success
  • 400 user id hoặc transaction hash không hợp lệ.
  • 406 giao dịch không tồn tại hoặc ở trạng thái thất bại.
  • 404 không hỗ trợ loại token này.
  • 409 giao dịch đã được hệ thống ghi nhận rồi.
  • 500 không thể khởi tạo giao dịch vào cơ sở dư liệu.
  • 422 giao dịch không hợp lệ (không phải giao dịch chuyển tiền loại này hoặc chuyển tới địa chỉ không chính xác)

Model

DepositTransaction

  • id string ID của record.
  • tx_hash string mã giao dịch.
  • user_id int ID của user.
  • contract_address string địa chỉ contract.
  • from_address string địa chỉ ví gửi.
  • to_address string địa chỉ ví con nhận tiền.
  • block_number int số thứ tự block.
  • block_hash string mã block.
  • value string tiền khi chưa chia cho decimal.
  • token_name string tên của token khai báo trong file config.
  • token_address string địa chỉ của token.
  • tokens float số tiền gửi.
  • chain_id int id của mạng.
  • decimals int
  • is_approved bool trường này bằng true nếu giao dịch đã được xác thực thành công, còn false nếu giao dịch đang đợi hoàn thành.
  • is_collected bool nếu tiền đã được chuyển về ví tổng thì = true.
  • updated_at int unix timestamp .
  • created_at int unix timestamp.
  • max_confirmations int số lượng tối đa xác nhận cần cho giao dịch này (chỉ dùng trong trường hợp pending transaction)
  • confirmations int số lượng xác nhận hiện tại (nếu = max_confirmations thì giao dịch đã thành công), trong giao diện lịch sử giao dịch sẽ hiển thị số (confirmations / max confirmations) đối với các giao dịch đang thực hiện, để người dùng có thể biết là giao dịch này tiến độ hoàn thành đang là bao nhiêu %.

WithdrawTransaction

  • id string ID của record.
  • request_id string id của request này ứng với bên game server, để map 2 transaction với nhau.
  • user_id int id của user.
  • tokens float số tiền yêu cầu rút.
  • token_name string tên token.
  • token_address string địa chỉ token.
  • to_address string địa chỉ ví nhận tiền.
  • is_transferred bool true nếu tiền đã được gửi sang ví người dùng.
  • tx_hash string mã giao dịch (nếu is_transferred = true).
  • created_at int unix timestamp
  • updated_at int unix timestamp

About

tài liệu về Deployment và API của cổng thanh toán tiền ảo Andromeda.