AaaS Oracle Documentation

The PODBUM® Attribution-as-a-Service (AaaS) Oracle is a novel system designed to automate the distribution of royalty payments to holders of specific Non-Fungible Tokens (NFTs). The core innovation lies in its ability to programmatically attribute and distribute community-based rewards (in the form of PCC tokens) to a dynamic list of asset owners at a specific point in time.

This solves a critical problem in the digital asset space: how to reward a decentralized community of owners based on ongoing participation and ownership, without manual intervention or complex smart contract logic for every payout.

The system operates through a series of defined data structures and processes, primarily managed within a Firestore database. The flow is as follows:

1. Oracle Execution: An "Oracle Run" is initiated, either manually or on a schedule. This action creates a master record, `OracleRun`, which acts as an atomic container for a single distribution event. It records the timestamp, the total amount to be distributed, and the relevant contract addresses.
2. Holder Snapshot & Payout Calculation: At the moment of the run, the system identifies all current owners of the relevant NFTs. For each owner, it calculates their share of the royalty payout.
3. Payout Record Creation: For each eligible owner, an `NftHolder` document is created as a child of the `OracleRun` document. This record contains the owner's wallet address, the royalty amount they are entitled to, and a status indicating whether the royalty has been claimed. This creates an immutable, auditable trail of every individual payout for every distribution run.
4. Marketplace Integration: The marketplace reads from the `nftAssets` collection to display which assets are for sale. When a "buy" transaction occurs, the `ownerAddress` field on the corresponding `NftAsset` document is updated. This ensures that the next Oracle Run will attribute the royalty to the new owner, seamlessly linking market activity to future payouts.

• Atomic Payout Events: The use of an `OracleRun` as a root document for each distribution event ensures that every payout batch is atomic, auditable, and isolated. This is a significant improvement over simple, direct token transfers which lack context and grouping.
• Decoupled Data Structure: The data structure is designed for "Authorization Independence." By denormalizing key information like contract addresses into the child `NftHolder` documents, the system's security rules can authorize actions on individual payout records without needing to perform costly and complex reads on the parent `OracleRun` document. This is a highly efficient and secure design for a NoSQL database.
• Just-in-Time Attribution: The system attributes royalties at the "just-in-time" moment of the oracle run. Ownership is not tracked continuously but rather captured in a snapshot, which is a highly scalable method for handling assets with potentially high-frequency trading.
• Extensibility: The architecture allows for any number of different NFT contracts to be the basis for royalty distributions, simply by referencing a different `nftContractAddress` during the oracle run.