Diff: services/service-wallet-settlement.es
From 21d8df6 to 21d8df6
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "Wallet settlement" | title: "Wallet settlement" |
| slug: service-wallet-settlement | slug: service-wallet-settlement |
| short_description: "A per-tenant internal accounting ledger that records and settles reverse-flow revenue from the data marketplace as signed JSONL entries, with non-custodial withdrawal options to blockchain or fiat and platform-fee deductions applied at credit time." | short_description: "A per-tenant internal accounting ledger that records and settles reverse-flow revenue from the data marketplace as signed JSONL entries, with non-custodial withdrawal options to blockchain or fiat and platform-fee deductions applied at credit time." |
| category: services | category: services |
| type: topic | type: topic |
| quality: complete | quality: complete |
| status: active | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| last_edited: 2026-05-25 | last_edited: 2026-05-25 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: service-wallet-settlement.es.md | paired_with: service-wallet-settlement.es.md |
| references: | references: |
| - id: 1 | - id: 1 |
| text: "PointSav platform specification: per-tenant accounting ledger design for reverse-flow settlement — structural properties of the service-wallet component." | text: "PointSav platform specification: per-tenant accounting ledger design for reverse-flow settlement — structural properties of the service-wallet component." |
| - id: 2 | - id: 2 |
| text: "PointSav platform specification: reverse-flow substrate — the revenue-routing mechanism through which data marketplace proceeds reach operator wallets." | text: "PointSav platform specification: reverse-flow substrate — the revenue-routing mechanism through which data marketplace proceeds reach operator wallets." |
| - id: 3 | - id: 3 |
| text: "PointSav platform specification: customer-owned graph intellectual property — the portability and ownership guarantees for operator-generated graph data." | text: "PointSav platform specification: customer-owned graph intellectual property — the portability and ownership guarantees for operator-generated graph data." |
| - id: 4 | - id: 4 |
| text: "PointSav platform specification: Write-Once-Read-Many (WORM) ledger design — the append-only storage substrate underpinning all platform accounting records." | text: "PointSav platform specification: Write-Once-Read-Many (WORM) ledger design — the append-only storage substrate underpinning all platform accounting records." |
| --- | --- |
| `service-wallet` is the per-tenant internal accounting ledger that records and settles all reverse-flow revenue from the platform's data marketplace and ad exchange. The service operates at [[three-ring-architecture|Ring 2]] — the knowledge-and-processing layer of the platform — and holds no funds: it tracks credits, debits, and fees as cryptographically signed entries, with withdrawal to the operator's own wallet or bank account handled outside the platform. | `service-wallet` is the per-tenant internal accounting ledger that records and settles all reverse-flow revenue from the platform's data marketplace and ad exchange. The service operates at [[three-ring-architecture|Ring 2]] — the knowledge-and-processing layer of the platform — and holds no funds: it tracks credits, debits, and fees as cryptographically signed entries, with withdrawal to the operator's own wallet or bank account handled outside the platform. |
| The structural design properties are specified in the platform accounting ledger design.[^1] | The structural design properties are specified in the platform accounting ledger design.[^1] |
| ## Structural Accounting Isolation | ## Structural Accounting Isolation |
| `service-wallet` is an **accounting ledger**, not a payment rail and not a custodial wallet. The distinction matters legally and structurally: | `service-wallet` is an **accounting ledger**, not a payment rail and not a custodial wallet. The distinction matters legally and structurally: |
| - **Accounting ledger**: records credits, debits, and fees as signed JSONL entries; denominated in the operator's chosen unit of account; no funds in transit; PointSav holds no float | - **Accounting ledger**: records credits, debits, and fees as signed JSONL entries; denominated in the operator's chosen unit of account; no funds in transit; PointSav holds no float |
| - **Not a payment rail**: The platform does not route money between parties; the buyer's transaction goes directly to the destination address or through the smart contract; the platform fee is an accounting deduction at the time the incoming credit is recorded | - **Not a payment rail**: The platform does not route money between parties; the buyer's transaction goes directly to the destination address or through the smart contract; the platform fee is an accounting deduction at the time the incoming credit is recorded |
| - **Not a custodial wallet**: The platform never holds the tenant's private keys; the tenant's balance in `service-wallet` is an accounting balance representing amounts owed, not a pool of funds under platform control | - **Not a custodial wallet**: The platform never holds the tenant's private keys; the tenant's balance in `service-wallet` is an accounting balance representing amounts owed, not a pool of funds under platform control |
| This architecture keeps the platform structurally outside regulated money-transmitter and custodial-wallet territory. Tenants should obtain local legal counsel on their own payment activities; this is directional, not legal advice. | This architecture keeps the platform structurally outside regulated money-transmitter and custodial-wallet territory. Tenants should obtain local legal counsel on their own payment activities; this is directional, not legal advice. |
| ## Cryptographic Ledger Records | ## Cryptographic Ledger Records |
| Every credit, debit, and fee entry is a signed JSONL record: | Every credit, debit, and fee entry is a signed JSONL record: |
| ```json | ```json |
| { | { |
| "schema": "foundry-wallet-entry-v1", | "schema": "foundry-wallet-entry-v1", |
| "entry_id": "<ulid>", | "entry_id": "<ulid>", |
| "tenant_id": "<module_id>", | "tenant_id": "<module_id>", |
| "type": "credit | debit | fee_deduction | withdrawal", | "type": "credit | debit | fee_deduction | withdrawal", |
| "amount": "<decimal string>", | "amount": "<decimal string>", |
| "currency": "USDC | USD | CAD | <operator-configured>", | "currency": "USDC | USD | CAD | <operator-configured>", |
| "chain": "polygon-pos | solana | fiat | null", | "chain": "polygon-pos | solana | fiat | null", |
| "tx_hash": "<on-chain tx hash if applicable>", | "tx_hash": "<on-chain tx hash if applicable>", |
| "source_service": "service-market | service-exchange", | "source_service": "service-market | service-exchange", |
| "platform_fee_pct": "<decimal string>", | "platform_fee_pct": "<decimal string>", |
| "platform_fee_amount": "<decimal string>", | "platform_fee_amount": "<decimal string>", |
| "net_tenant_amount": "<decimal string>", | "net_tenant_amount": "<decimal string>", |
| "signed_at": "<ISO 8601>", | "signed_at": "<ISO 8601>", |
| "ledger_seq": "<monotonic integer>" | "ledger_seq": "<monotonic integer>" |
| } | } |
| ``` | ``` |
| The `platform_fee_amount` is deducted at credit time. The tenant's balance is `net_tenant_amount` accumulated across credits minus debits. | The `platform_fee_amount` is deducted at credit time. The tenant's balance is `net_tenant_amount` accumulated across credits minus debits. |
| ## Settlement Flow Execution | ## Settlement Flow Execution |
| ``` | ``` |
| 1. Revenue event occurs (data purchase or ad impression/win) | 1. Revenue event occurs (data purchase or ad impression/win) |
| 2. Incoming credit recorded in service-wallet ledger | 2. Incoming credit recorded in service-wallet ledger |
| Platform fee deducted at this step (accounting deduction) | Platform fee deducted at this step (accounting deduction) |
| 3. Tenant's net balance increases | 3. Tenant's net balance increases |
| 4. Tenant initiates withdrawal (tenant-controlled; not automatic) | 4. Tenant initiates withdrawal (tenant-controlled; not automatic) |
| Options: | Options: |
| (a) Crypto withdrawal → tenant's pre-registered address (EVM or Solana) | (a) Crypto withdrawal → tenant's pre-registered address (EVM or Solana) |
| (b) Fiat withdrawal → tenant's bank account (via Stripe Connect or equivalent) | (b) Fiat withdrawal → tenant's bank account (via Stripe Connect or equivalent) |
| (c) Tier B credit → balance reinvested as Yo-Yo compute budget | (c) Tier B credit → balance reinvested as Yo-Yo compute budget |
| 5. Withdrawal event recorded in ledger | 5. Withdrawal event recorded in ledger |
| Receipt anchored to Sigstore Rekor | Receipt anchored to Sigstore Rekor |
| [[worm-ledger-design|WORM ledger]] entry in [[service-fs-architecture|service-fs]] closes the accounting cycle | [[worm-ledger-design|WORM ledger]] entry in [[service-fs-architecture|service-fs]] closes the accounting cycle |
| ``` | ``` |
| ## Settlement Payment Rails | ## Settlement Payment Rails |
| | Chain | Typical fee | Role | | | Chain | Typical fee | Role | |
| |---|---|---| | |---|---|---| |
| | Polygon PoS | approximately $0.002/tx | Primary — lowest fees, proven micropayment volume | | | Polygon PoS | approximately $0.002/tx | Primary — lowest fees, proven micropayment volume | |
| | Solana | approximately $0.0005/tx | Secondary — fastest settlement, sub-cent fees | | | Solana | approximately $0.0005/tx | Secondary — fastest settlement, sub-cent fees | |
| Non-custodial: platform stores destination addresses (public keys only). The withdrawal transaction is signed by the tenant's wallet, not by the platform. Platform cannot move funds without the tenant's signature. | Non-custodial: platform stores destination addresses (public keys only). The withdrawal transaction is signed by the tenant's wallet, not by the platform. Platform cannot move funds without the tenant's signature. |
| Circle Paymaster handles gas abstraction — tenants pay gas in USDC; no native Polygon/Solana token required for SMB operators. | Circle Paymaster handles gas abstraction — tenants pay gas in USDC; no native Polygon/Solana token required for SMB operators. |
| ## Fee Deduction Mechanism | ## Fee Deduction Mechanism |
| The platform fee percentage is an operator configuration at deployment time, applied uniformly across all reverse-flow transactions for that tenant. It is an accounting deduction, not a separate transaction. The specific percentage is an open operator decision. | The platform fee percentage is an operator configuration at deployment time, applied uniformly across all reverse-flow transactions for that tenant. It is an accounting deduction, not a separate transaction. The specific percentage is an open operator decision. |
| Industry reference: direct-payment-to-rights-holder models at scale validate that customers keeping a majority of revenue is a workable commercial structure. The platform's revenue split is an operator configuration; the intended default is "customer keeps majority." | Industry reference: direct-payment-to-rights-holder models at scale validate that customers keeping a majority of revenue is a workable commercial structure. The platform's revenue split is an operator configuration; the intended default is "customer keeps majority." |
| ## Audit and Public Anchoring | ## Audit and Public Anchoring |
| Every withdrawal receipt is anchored to Sigstore Rekor by [[fs-anchor-emitter]]. The anchor record includes: tenant ID, ledger sequence at withdrawal, amount, chain, and transaction hash. This provides a tamper-evident external timestamp suitable for accounting and legal purposes. | Every withdrawal receipt is anchored to Sigstore Rekor by [[fs-anchor-emitter]]. The anchor record includes: tenant ID, ledger sequence at withdrawal, amount, chain, and transaction hash. This provides a tamper-evident external timestamp suitable for accounting and legal purposes. |
| The full ledger history is queryable by the tenant at any time. The export format is JSONL — the same format as the ingestion record. Portability is unconditional; the ledger travels with the tenant on exit per the customer-owned data portability guarantee.[^3] | The full ledger history is queryable by the tenant at any time. The export format is JSONL — the same format as the ingestion record. Portability is unconditional; the ledger travels with the tenant on exit per the customer-owned data portability guarantee.[^3] |
| ## See also | ## See also |
| - [[reverse-flow-substrate]] — revenue sources; payment rail detail | - [[reverse-flow-substrate]] — revenue sources; payment rail detail |
| - [[customer-owned-graph-ip]] — ledger export is unconditional tenant property | - [[customer-owned-graph-ip]] — ledger export is unconditional tenant property |
| - [[worm-ledger-architecture]] — service-wallet appends to service-fs WORM ledger | - [[worm-ledger-architecture]] — service-wallet appends to service-fs WORM ledger |