agorix
AirdropMarketsCollectionsLeaderboardActivity
Agorix · Decentralized Marketplace
Independent · Resilient · Community-Run

A cross-chain marketplace, run by the community.

Discover, list, and trade across Bitcoin, Ethereum, and Solana on an open, community-run network.

Marketplace
CollectionsMarketsLeaderboardActivity
Network
GovernanceExplorerAirdropDocs
Account
ProfileSettings
Legal
Terms of ServicePrivacy PolicyYour Privacy Choices
agorix.io — Lasting Access
CID: 0xA60R1X · v0.1
AirdropMarketsCollections
D
Protocol Docs
Marketplace OverviewAtomic Buy LocksDatabase ArchitectureProfiles & AuthenticationCollections & RoyaltiesCreator Royalty SystemMedia Cache & OptimizationModeration & ReputationSearch & DiscoveryCollection Rarity AlgorithmsLive Activity & LeaderboardsCollection Preseed Queue
Docs/Marketplace/Database Architecture
Marketplace

Database Architecture

Complete database schema reference. Every table, its purpose, key columns, indexes, and relationships across marketplace, agent, governance, rewards, and realtime domains.

#Database Architecture

Every node runs its own isolated PostgreSQL 16 instance. There is no shared database anywhere in the system. Tables are organized into six domains.

#Marketplace Domain

listings -- Core asset records for sale

ColumnTypePurpose
idTEXT PKUnique listing identifier
chainENUM (BTC, ETH, SOL)Which blockchain the asset lives on
assetOutpointTEXT UNIQUEOn-chain asset identifier
sellerAddressTEXTSeller's wallet address
priceSatsBIGINTPrice in base units (satoshis for BTC, wei for ETH)
statusTEXTOPEN, FILLED, or CANCELLED
btcSale / evmSale / solanaSaleJSONBChain-specific sale parameters
collectionIdTEXT FKParent collection (optional)
royaltyBpsOverrideINT (0-10000)Override creator royalty percentage
revealNonceINTIncrementing counter for PSBT share reveals
expiresAtTIMESTAMPWhen listing automatically cancels

Indexed by: chain, status, assetOutpoint, expiresAt, updatedAt.

orderIntents -- Purchase initialization

ColumnTypePurpose
idTEXT PKOrder identifier
listingOutpointTEXT FKWhich listing is being purchased
buyerPubkeyTEXTBuyer's Ed25519 public key
chainENUMTarget chain
sessionIdTEXTBuyer's active session

btcActiveOrders -- Bitcoin-specific order state tracking

ColumnTypePurpose
listingOutpointTEXT PK/FKThe listing being purchased
orderIdTEXT UNIQUE FKLinks to orderIntents
statusTEXTSigning/confirmation progress
txidTEXTFinal transaction hash (once broadcast)
lockedAtTIMESTAMPWhen this order locked the listing
expiresAtTIMESTAMPOrder timeout

sessionQuotes -- Pricing snapshots bound to orders

ColumnTypePurpose
orderId + sessionIdComposite PKLinks quote to specific order and session
sessionCommitHashTEXTHash of quote commitment
bodyJSONBFull quote details (price, fees, witnesses)
signatureTEXTServing node's Ed25519 signature on the quote
expiresAtTIMESTAMPQuote validity window

txSummaries -- On-chain transaction records

ColumnTypePurpose
txidTEXT PKOn-chain transaction ID
orderIdTEXT FKWhich order this settles
chainENUMWhich blockchain
blockHeightINTBlock where transaction landed
decodedSummaryJSONBParsed outputs and fee breakdown

txAttestations -- Witness signatures on transactions

ColumnTypePurpose
txidTEXT FKWhich transaction
agentPubkeyTEXTWhich witness node signed
verdictENUM (VALID, INVALID)Attestation result
reasons / breakdownJSONBValidation details and fee verification
validatorVersionTEXTProtocol version used for validation

UNIQUE constraint on (txid, orderId, agentPubkey) -- one attestation per node per transaction.

#PSBT Custody Tables (Bitcoin-Specific)

listingPsbtShards -- Threshold encryption metadata per listing

ColumnTypePurpose
listingOutpointTEXT PK/FKLinks to listing
threshold / totalSharesINTM-of-N scheme (e.g. 3-of-4)
encryptedPsbtVaultBlobIdTEXT FKSecret-vault reference to threshold-encrypted PSBT data
participantsJSONBArray of shard-holder node pubkeys
shareCommitmentsJSONBVerification hashes for each share

listingPsbtShares -- Individual encrypted shares held by nodes

ColumnTypePurpose
listingOutpointTEXT FKWhich listing
holderAgentPubkeyTEXTWhich node holds this share
shareIndexINTPosition in threshold scheme
shareValueVaultBlobIdTEXT FKSecret-vault reference to encrypted share data

UNIQUE on (listingOutpoint, holderAgentPubkey) -- one share per node per listing.

listingPsbtRevealChallenges -- Authorized share reveal requests

ColumnTypePurpose
challengeIdTEXT PKUnique challenge identifier
listingOutpointTEXT FKWhich listing
orderIdTEXT FKWhich order is requesting
listingRevealNonceINTMust match listing's current revealNonce
nonce / signatureTEXTChallenge authentication
expiresAtTIMESTAMPChallenge timeout

#Collection Domain

collectionMetadata -- Collection identity and display info

ColumnTypePurpose
collectionIdTEXT PKUnique collection ID
chainENUMBTC, ETH, or SOL
collectionTypeENUMEVM_CONTRACT, PARENT_CHILD, GALLERY, CURATED
name / descriptionTEXTDisplay information
verifiedENUMUNVERIFIED, PENDING, VERIFIED, REJECTED
contractAddressTEXTEVM contract (if applicable)
parentInscriptionIdTEXTBTC parent inscription (if applicable)
creatorAddressTEXTCollection creator wallet

collectionRegistry -- Royalty recipient configuration

ColumnTypePurpose
collectionIdTEXT FKWhich collection
recipientAddressTEXTWhere royalties are sent
bpsINT (0-10000)Royalty percentage in basis points

Multiple recipients per collection are supported (e.g. co-creators splitting royalties).

collectionSubmissions -- Community proposal and voting system

ColumnTypePurpose
collectionIdTEXTProposed collection identifier
collectionTypeENUMType of collection being proposed
statusENUMUNVERIFIED, PENDING, VERIFIED, REJECTED
verifyVotes / rejectVotesINTCommunity vote tallies
softApprovedBOOLTrue if no conflicts were detected, so the collection is shown
hasConflictBOOLTrue if inscription range overlaps existing collection
votingDeadlineTIMESTAMP7-day deadline for conflicted proposals

#Asset Ownership & Activity

assetOwnershipCache -- Who owns what (lazy-loaded, cursor-paginated)

ColumnTypePurpose
assetKeyTEXT PKComposite identifier (chain:contract:tokenId)
chainENUMWhich blockchain
ownerAddressTEXTCurrent owner
verifiedAtBlockBIGINTLast on-chain verification block
inscriptionId / contractAddress / mintAddressTEXTDenormalized for fast queries

Indexed by (chain, ownerAddress, assetKey) for cursor pagination.

assetActivity -- Historical event log with keyset pagination

ColumnTypePurpose
idTEXT PKSortable "{epochMs}_{random}" format (IS the cursor)
activityTypeENUMMINT, TRANSFER, LIST, DELIST, BUY, SELL, BURN, INSCRIBE
priceRawTEXTSale price in base units
txHashTEXTOn-chain transaction
occurredAtTIMESTAMPWhen the activity happened on-chain

UNIQUE on (txHash, assetKey) -- prevents double-logging the same event. All queries use keyset pagination: WHERE id < ?cursor ORDER BY id DESC (no OFFSET).

#Rewards Domain

rewardClaims -- Token entitlements (claims, not transfers)

ColumnTypePurpose
idTEXT PKClaim identifier
reasonENUMNODE_FEE_REIMBURSEMENT, NODE_INCENTIVE, USER_PURCHASE_REWARD, MODERATION_REWARD, BURN_ALLOCATION, MEDIA_OPTIMIZATION
tokenAmountRawTEXTFull precision token amount
statusENUMPENDING, SIGNED, CLAIMED, EXPIRED
stateEpochINTWhich weekly epoch this belongs to
signatureTEXTMPC threshold signature for claiming

claimEpochs -- Weekly reward batching windows

ColumnTypePurpose
epochNumberINT UNIQUESequential epoch counter
statusENUMOPEN, CLOSING, FUNDING, SIGNING, BROADCASTING, CONFIRMED, FAILED
totalTokenAmountRawTEXTSum of all claims in this epoch
signingCeremonyIdTEXT FKMPC ceremony for batch payout
payoutTxHashTEXTFinal on-chain transaction

#Realtime Domain

chatThreads / chatMessages -- Sharded via rendezvous hashing. Each thread is assigned to specific nodes based on the shard ring. Messages include sender, content, and thread reference.

protocolEvents -- The complete signed event log. Every Ed25519-signed event gossiped through the network is stored here for full auditability. This is the canonical record of all protocol activity.

PreviousAtomic Buy LocksNext Profiles & Authentication

On this page

  • Database Architecture
  • Marketplace Domain
  • PSBT Custody Tables (Bitcoin-Specific)
  • Collection Domain
  • Asset Ownership & Activity
  • Rewards Domain
  • Realtime Domain