DApp Integration Reference Case

1. Scope

This appendix uses a transactional DApp to define the integration boundaries of POC V2. It does not prescribe one business state machine for every application. Games, content platforms, task systems, DeFi applications, and supply-chain applications may define domain-specific maturity conditions, provided that candidate activity, mature business fact, trusted issuance, and Activated Power remain distinct protocol stages.

2. Mature Contribution

Payment, interaction, order creation, or a successful frontend response constitutes candidate activity only. A contribution becomes mature only after the business state machine has excluded the principal revocation paths or has entered an explicit, governable correction stage.

Fact class	Transactional DApp example	POC treatment
Candidate activity	Order placement, payment, inventory lock	Does not create POC Power
Maturity condition	Fulfilment confirmation, service acceptance, lock-period expiry	Permits contribution-issuance evaluation
Mature contribution	Settlement executed and net value determined	May enter the trusted issuance path
Refund or dispute	Refund, arbitration, fraud, or chargeback	Cancels, freezes, offsets, or corrects contribution

3. Reference Journey

The reference sequence is:

1. The user signs a business transaction with a wallet.
2. The contract executes payment, asset lock, or a business-state transition.
3. Fulfilment, acceptance, lock-period, and settlement rules establish the mature business fact.
4. The DApp contribution manager validates maturity, idempotency, pause state, beneficiary, and custody.
5. The DApp issues its equity token through poc_contribution, producing a ContributionEvent.
6. After finality, the event enters the next Validator computation range.
7. POC V2 performs independent recomputation, Vote/QC formation, Candidate delivery, Batch, Seal, and Atomic Activate.
8. The DApp frontend and downstream modules read Activated Power from PowerReadModel.

4. Registry and Equity Token

Before integration, the DApp shall establish the following identities in the Registry:

• application administration and on-chain addresses;
• the DApp equity token;
• the custody address;
• POC admission and pause state;
• effective weight and its period semantics; and
• the Topo DEX base_token/quote_token price pair.

The equity token is the value carrier and price identity of the trusted contribution path. It is not Power. A user obtains protocol-readable Power only after the resulting ContributionEvent has entered deterministic period computation and the Candidate has been atomically activated.

5. Topo DEX Price Integration

The DApp shall configure an auditable Topo DEX price identity for its equity token. POC uses the latest stable price at the Context price_read_fence; it does not use a backend quotation, a provisional current-period observation, or a contribution-period-specific price.

Integration acceptance shall confirm that:

• the price source is registered and its reporters are authorized;
• at least one stable price and corresponding PriceUpdatedEvent exist;
• the Registry price-identity mapping is unambiguous;
• a task returns Abstain when no stable price exists and never substitutes a default value; and
• user and operational interfaces may display price staleness but may not replace the protocol price.

6. Business Transaction Entry

A backend accepting wallet-signed transactions shall perform the following validations:

Control	Requirement
Identity	The sender matches the authenticated wallet and the chain ID is correct
Target	Contract address, module, function, and generic parameters are allowlisted
Semantics	Order, asset, quantity, beneficiary, and business state match authoritative service facts
Idempotency	Transaction hash, business object, and retry operation have explicit unique identities
Result	RPC acceptance is not execution success; the finalized chain fact is authoritative

The backend shall not operate as a blind signedTx relay and shall not treat local database state as proof of on-chain execution.

7. Contract Responsibilities

The DApp Move contracts should separate:

• business state and authorization;
• assets, inventory, custody, and refunds;
• settlement and maturity conditions;
• the contribution manager; and
• public events and views.

A ContributionEvent shall originate from the trusted poc_contribution path. DApp business events remain valid audit evidence but shall not be substituted for POC input.

8. Separation of Business Settlement and POC

Failure of contribution issuance or later POC settlement shall not block a valid merchant-funds settlement. The business state machine shall complete the lawful asset and entitlement transition before submitting the mature fact for contribution issuance.

Scenario	Business result	POC result
Settlement and contribution issuance succeed	Merchant settlement completes	A ContributionEvent is produced
Settlement succeeds; contribution issuance is temporarily unavailable	Merchant settlement remains complete	A retryable or held state is recorded; no event is fabricated
Refund or dispute precedes settlement	Refund, arbitration, or cancellation proceeds	No contribution is issued
Dispute follows issuance	Business state is corrected under governance rules	Future offset, reverse contribution, or governance correction applies
Application is paused	Existing business operations follow safe-completion rules	New contribution issuance stops

9. Event Projection and User Interface

An event consumer shall project finalized chain facts only and shall support idempotency, replay, gap detection, and reconciliation. User interfaces shall distinguish:

• business transaction submitted;
• on-chain business fact finalized;
• contribution matured;
• ContributionEvent produced;
• contribution included in a POC computation range;
• Candidate not yet activated; and
• Activated Power available for reading.

Representing these states as a single “reward successful” status obscures finality, NoQuorum, and automatic catch-up semantics.

10. Integration Stages

Stage	Primary deliverable	Exit criterion
I0 Business semantics	State machine, maturity condition, refund, and dispute rules	Product, contract, backend, and test definitions are consistent
I1 On-chain facts	Move contracts, events, views, permissions, and initialization	Critical paths and negative tests pass
I2 POC identity	Registry, equity token, custody, weight, and price identity	All state is queryable and auditable
I3 Trusted issuance	Contribution manager and poc_contribution integration	Maturity, duplicate, pause, and balance tests pass
I4 Projection and reconciliation	Consumer, read model, and reconciliation	State can be replayed and repaired from chain facts
I5 Shadow integration	Observation of Contribution, Context, and Validator results	Inputs remain consistent across multiple periods without production Power writes
I6 Controlled enablement	Enforced testnet operation and limited production pilot	Security gates, monitoring, and failure exercises pass

11. Integration Acceptance

• Candidate activity and mature contribution use distinct on-chain states.
• Payment success does not directly create Power.
• ContributionEvent can originate only from the trusted POC path.
• Registry application, token, custody, state, weight, and price identity are consistent.
• A POC failure cannot block a valid business-funds settlement.
• Refund, dispute, pause, and post-issuance correction have explicit states and audit events.
• Consumers can replay finalized chain facts without relying on unverifiable local logs.
• The frontend distinguishes contribution issuance, Candidate processing, and Power activation.