API Reference

DXA Blockchain API

Hạ tầng chứng thực Layer-3 — niêm phong, xác minh & thu hồi on-chain

DXA Blockchain là sổ cái chứng thực (Layer-3 Attestation Hub): niêm phong dấu vân tay (fingerprint) dữ liệu lên sổ cái, xác minh tính toàn vẹn về sau, và thu hồi khi cần. Dữ liệu được chuẩn hóa (canonical JSON, chuẩn NFC) rồi băm keccak256; chỉ dấu vân tay được lưu, không lưu dữ liệu gốc. Bản ghi gắn với issuer qua chữ ký EIP-191 và được phân quyền bởi hợp đồng governance.

Base URL

https://blockchain.dxa.io.vn

Xác thực

Sandbox công khai chạy chế độ `mock` (mô phỏng tx/hash, không cần ví). Bản on-chain (Base Sepolia) ký bằng khóa relayer lưu trong Cloudflare secret — không có khóa nào ở phía client; chỉ issuer được phân quyền mới ghi/thu hồi được. Khuyến nghị rate limit ~5 req/phút/IP.

Sổ cái chứng thực

POST /api/anchor

Niêm phong dấu vân tay dữ liệu lên sổ cái

Xác thực: Không (sandbox công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`scenario`*	`'e_invoice' \| 'fund_disbursal' \| 'kyc_profile' \| 'academic_credential'`	Loại kịch bản nghiệp vụ
`payloadId`*	`string`	Mã định danh nghiệp vụ (≤200 ký tự), vd `INV-2026-001`
`dataFields`*	`object`	Cặp khóa-giá trị dữ liệu cần niêm phong (≤50 khóa)
`nonce`	`number`	Nonce chống phát lại (mặc định thời điểm hiện tại)

Ví dụ yêu cầu

curl -X POST 'https://blockchain.dxa.io.vn/api/anchor' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenario": "e_invoice",
    "payloadId": "INV-2026-001",
    "dataFields": { "taxId": "0312345678", "amount": 500000000, "issuedAt": "2026-05-30" }
  }'

const res = await fetch('https://blockchain.dxa.io.vn/api/anchor', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    scenario: 'e_invoice',
    payloadId: 'INV-2026-001',
    dataFields: { taxId: '0312345678', amount: 500_000_000, issuedAt: '2026-05-30' },
  }),
});
const { dataHash, explorerUrl } = await res.json();

Phản hồi mẫu

{
  "success": true,
  "mode": "onchain",
  "dataHash": "0x9af1…c20b",
  "payloadType": "e_invoice",
  "payloadId": "INV-2026-001",
  "nonce": 1769990400000,
  "transactionHash": "0x4e8d…7a31",
  "blockNumber": 14523456,
  "timestamp": 1769990400,
  "issuerId": "0x71C…e3F2",
  "status": 1,
  "explorerUrl": "https://sepolia.basescan.org/tx/0x4e8d…7a31"
}

Mã lỗi

`400`	Dữ liệu không hợp lệ / kịch bản không hỗ trợ / payload quá lớn
`409 already_anchored`	Dấu vân tay đã được niêm phong trước đó

POST /api/verify

Xác minh dữ liệu có khớp bản đã niêm phong (hỗ trợ sealCode từ QR)

Xác thực: Không (sandbox công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`dataFields`*	`object`	Dữ liệu cần kiểm chứng (băm lại & so khớp)
`sealCode`	`string`	Mã niêm phong bytes32 (0x…) từ QR — kiểm tra riêng nếu khác dataHash

Ví dụ yêu cầu

curl -X POST 'https://blockchain.dxa.io.vn/api/verify' \
  -H 'Content-Type: application/json' \
  -d '{ "dataFields": { "taxId": "0312345678", "amount": 500000000, "issuedAt": "2026-05-30" } }'

Phản hồi mẫu

{
  "success": true,
  "mode": "onchain",
  "dataHash": "0x9af1…c20b",
  "onChain": true,
  "sealCodeOnChain": null,
  "status": 1,
  "payloadType": "e_invoice",
  "issuerId": "0x71C…e3F2",
  "timestamp": 1769990400
}

POST /api/revoke

Thu hồi (vô hiệu hóa) một bản ghi chứng thực

Xác thực: Issuer gốc (ký on-chain mode)

Tham số (body)

Trường	Kiểu	Mô tả
`sealCode`	`string`	Mã niêm phong bytes32 cần thu hồi (hoặc dùng `dataFields`)
`dataFields`	`object`	Dữ liệu để băm ra sealCode (nếu không gửi `sealCode`)

Phản hồi mẫu

{
  "success": true,
  "mode": "onchain",
  "dataHash": "0x9af1…c20b",
  "status": 2,
  "transactionHash": "0x77a…b91",
  "explorerUrl": "https://sepolia.basescan.org/tx/0x77a…b91"
}

Mã lỗi

`403 forbidden`	Chỉ issuer gốc mới được thu hồi
`404 not_found`	Không tìm thấy bản ghi
`409 already_revoked`	Bản ghi đã bị thu hồi

POST /api/trustway

Cổng Trustway — ký kết quả AI (EIP-191) rồi neo lên sổ cái

Xác thực: Không (ví dụ tích hợp; ký bằng khóa relayer)

Tham số (body)

Trường	Kiểu	Mô tả
`score`	`number`	Điểm/kết quả AI (mặc định 785)
`payloadId`	`string`	Mã chứng từ/yêu cầu
`source`	`string`	Hệ thống nguồn (mặc định `DXA_TRUSTWAY_GATEWAY`)
`anchor`	`boolean`	Có neo kết quả lên sổ cái không (mặc định true)

Phản hồi mẫu

{
  "success": true,
  "mode": "onchain",
  "payloadType": "TRUSTWAY_AI_SCORE",
  "securePayload": { "source": "DXA_TRUSTWAY_GATEWAY", "timestamp": 1769990400, "score": 785, "payloadId": "DOC-001" },
  "dataHash": "0x…",
  "nonce": 1769990400000,
  "sig": { "v": 27, "r": "0x…", "s": "0x…" },
  "anchored": { "transactionHash": "0x…", "explorerUrl": "https://sepolia.basescan.org/tx/0x…" }
}

Smart contract (Base Sepolia)

DXAAttestationRegistry.sol

Sổ cái chứng thực — ký EIP-191, neo & thu hồi, chống phát lại bằng nonce

Xác thực: Chữ ký issuer được phân quyền

Giao diện

// Solidity — DXAAttestationRegistry
function verifyAndAnchor(
  bytes32 _dataHash, string _payloadType, uint256 _nonce,
  uint8 _v, bytes32 _r, bytes32 _s) external;             // xác thực chữ ký & ghi
function revokeAttestation(bytes32 _dataHash) external;    // thu hồi (chỉ issuer gốc)
function getRecord(bytes32 _dataHash) external view
  returns (bytes32, string, uint256, address, uint8);      // đọc bản ghi (status 1=Active, 2=Revoked)
function isAnchored(bytes32 _dataHash) external view returns (bool);
// event DataAnchored(bytes32 indexed dataHash, string payloadType, address indexed issuerId, uint256 timestamp)
// event DataRevoked(bytes32 indexed dataHash, address indexed revokerId)

DXAGovernanceSigners.sol

Phân quyền issuer theo loại payload (admin quản lý)

Xác thực: Admin của hợp đồng

Giao diện

// Solidity — DXAGovernanceSigners
function setSignerStatus(address _signer, string _payloadType, bool _status) external; // onlyAdmin
function isSignerAuthorized(address _signer, string _payloadType) external view returns (bool);
function transferAdmin(address _newAdmin) external;        // onlyAdmin