feat: Add documentation and examples for Community tables and PublicPermissionless Tables

README.md

@@ -4,9 +4,16 @@ This repository contains examples and guides for how to interact with the Space
 
 ## Tutorials
 
-- [Hello World Tutorial](./hello_world_tutorial/HELLO_WORLD_TUTORIAL.md)
+- [Hello World Tutorial](./tutorials/hello_world_tutorial/HELLO_WORLD_TUTORIAL.md)
+- [Community Tables Tutorial](./tutorials/community_tutorial/COMMUNITY_TABLE_TUTORIAL.md)
+- [Public Tables Tutorial](./tutorials/public_tutorial/PUBLIC_PERMISSIONLESS_TUTORIAL.md)
 
 ## How-To Guides
 
 - [How to convert between address formats](./how_to/HOW_TO_CONVERT_BETWEEN_ADDRESS_FORMATS.md)
 - [How To fund a wallet with Dreamspace Pay](./how_to/HOW_TO_FUND_A_WALLET_WITH_DSPAY.md)
+
+## Documentation
+- [Tables Overview](./tables/OVERVIEW.md)
+- [PublicPermissionless Tables](./tables/PUBLIC_TABLES.md)
+- [Community Tables](./tables/COMMUNITY_TABLES.md)

tables/COMMUNITY_TABLES.md

@@ -0,0 +1,50 @@
+# Community Tables
+
+Community tables are user-owned tables with **controlled access**. Only the table creator and users who have been granted explicit permission can insert data into these tables, making them ideal for private data storage and scenarios where you need to control who can write to your tables.
+
+## When to use Community Tables
+
+- Private application data
+- User management systems
+- Controlled datasets
+- Internal business data
+- Scenarios where you need permission-based access control
+- Multi-user applications with role-based data submission
+
+# Example Use Case - User Management System
+
+In this example we'll discuss a generic user management system built on Community tables that stores basic membership information. Only authorized submitters can insert or modify the user data. To create the system, we will create a namespace and a table, then we'll show how authorized submitters would add user records.
+
+In this example we'll create the statements as if we are using the wallet address `0xABC8d709C80262965344f5240Ad123f5cBE51123`
+
+So our namespace will be
+
+`MYAPP_ABC8d709C80262965344f5240Ad123f5cBE51123`
+
+And we'll use the following statements:
+
+```sql
+CREATE SCHEMA IF NOT EXISTS MYAPP_ABC8d709C80262965344f5240Ad123f5cBE51123;
+CREATE TABLE IF NOT EXISTS MYAPP_ABC8d709C80262965344f5240Ad123f5cBE51123.USERS (
+    USER_ID BIGINT NOT NULL,
+    USERNAME VARCHAR NOT NULL,
+    EMAIL VARCHAR NOT NULL,
+    CREATED_AT BIGINT NOT NULL,
+    PRIMARY_KEY(USER_ID)
+);
+```
+Which will result in a table like this:
+
+| `USER_ID` (`BIGINT`) | `USERNAME` (`VARCHAR`) | `EMAIL` (`VARCHAR`) | `CREATED_AT` (`BIGINT`) |
+| -------------------- | ---------------------- | ------------------- | ----------------------- |
+| 1                    | alice                  | alice@example.com   | 1700000000              |
+| 2                    | bob                    | bob@example.com     | 1700000100              |
+| 3                    | charlie                | charlie@example.com | 1700000200              |
+
+It's worth noting here that the table schema only includes the columns you define. **Unlike PublicPermissionless tables, Community tables do NOT automatically add a `META_SUBMITTER` column.**
+
+## Granting Insert Permissions
+
+By default, only the table creator can insert data. To allow other addresses to insert data, you must explicitly grant them permission using the `permissions.addProxyPermission()` transaction with the `IndexingPallet.SubmitDataForPrivilegedQuorum` permission.
+
+Scripts, examples, and a walkthrough for creating namespaces, tables, and permissioning users can be found in the [Community Tables Tutorial](../tutorials/community_tutorial/COMMUNITY_TABLE_TUTORIAL.md)

tables/OVERVIEW.md

@@ -0,0 +1,47 @@
+# Tables on Space and Time
+
+## Overview
+
+Space and Time (SXT Chain) is the first trustless database for the EVM, enabling smart contracts to interact with historical, cross-chain, or offchain data as if it were natively accessible onchain. Space and Time (SXT Chain) is optimized for:
+
+* High-throughput data ingestion from blockchains, consumer apps, and enterprise sources
+* Verifiable query execution over large datasets (millions of rows)
+* Fast ZK proof generation and EVM-compatible proof verification with minimal gas
+
+## Using Tables
+
+SXT Chain is a permissionless L1 blockchain that acts as a decentralized database and enables developers to define, own, and maintain tamperproof tables using standard SQL DDL. These tables form the foundation of Space and Time’s verifiable data model, allowing structured data to be inserted, queried, and cryptographically proven at scale.
+
+Creating a table on SXT Chain is similar to defining a schema in any relational database, but with added guarantees of verifiability and decentralized consensus. Developers submit to SXT Chain an ECDSA or ED25519-signed Substrate transaction containing CREATE TABLE SQL syntax to define table structure, including column types, and constraints.
+
+Once created, the table is:
+
+    Assigned a unique table ID
+    Associated with an initial table owner (the signer of the DDL transaction)
+    Registered in the SXT Chain under consensus
+    Bound to a cryptographic commitment representing the table’s state (initially empty)
+
+All inserts, updates, and deletions from that point forward are tracked by cryptographic commitments stored onchain, allowing for ZK-proven query execution and verifiable data integrity.
+
+When creating a SXT Chain table, there are several types to choose from depending on the application and access required:
+
+    Public/Permissionless Tables: Any user can submit data (e.g., public content feeds or game leaderboards).
+    Community Tables: Only the table owner (or a whitelisted set of public keys) can insert data. Useful for oracle publishers or protocol-owned datasets.
+
+Ownership is defined at table creation via the wallet signature that initiates the DDL transaction.
+
+## Paying for Tables and Inserts
+
+Table creation is paid for using compute credits. Compute credits can be acquired through a few different means, mentioned in other parts of this documentation.
+
+| Action             | Cost              |
+|--------------------|-------------------|
+| Table Creation     | 20 SXT per Table  |
+| Namespace Creation | 20 SXT per Schema |
+| Row Inserts        | ~0.02 SXT per row | 
+
+## More Reading
+
+* [PublicPermissionless Tables](./PUBLIC_TABLES.MD)
+* [Community Tables](./COMMUNITY_TABLES.MD)
+

tables/PUBLIC_TABLES.md

@@ -0,0 +1,43 @@
+# Public/Permissionless Tables
+
+PublicPermissionless tables allow anyone to insert data without requiring explicit permissions. The system automatically tracks who submitted each row using a `META_SUBMITTER` column, allowing for analytics.
+
+## When to use PublicPermissionless Tables
+
+- Open data collection (surveys, feedback, reports)
+- Crowdsourced datasets
+- Public registries and directories
+- Community-driven data contributions
+- Scenarios where you want open participation with accountability
+
+# Example Use Case - Poll System
+
+In this example we'll discuss a Poll System built on PublicPermissionless tables that allows users to vote on which movie will be the leader in box office earnings each week. To create the system, we will create a namespace and a table, then we'll show how users would 'vote' on the poll by inserting data into the table.
+
+In this example we'll create the statements as if we are using the wallet address `0xABC8d709C80262965344f5240Ad123f5cBE51123`
+
+So our namespace will be 
+
+`MOVIES_ABC8d709C80262965344f5240Ad123f5cBE51123`
+
+And we'll use the following statements:
+
+```sql
+CREATE SCHEMA IF NOT EXISTS MOVIES_ABC8d709C80262965344f5240Ad123f5cBE51123;
+CREATE TABLE IF NOT EXISTS MOVIES_ABC8d709C80262965344f5240Ad123f5cBE51123.VOTES (
+    MOVIE VARCHAR NOT NULL,
+    WEEK BIGINT NOT NULL,
+    PRIMARY_KEY(MOVIE, WEEK)
+);
+```
+Which will, after being modified by the chain, result in a table like this;
+
+| `MOVIE` (`VARCHAR`) | `WEEK` (`BIGINT`) | `META_SUBMITTER` (`BINARY`) |
+|---------------------|-------------------| --------------------------- |
+| Movie A             | 2                 | 0x000...user1address       |
+| Movie A             | 2                 | 0x000...user2address       |
+| Movie B             | 2                 | 0x000...user3address       |
+
+It's worth noting here that the table schema and the data submitted **should not include** the `META_SUBMITTER` column.
+
+You can follow along in the [PublicPermission Tables Tutorial](../tutorials/public_tutorial/PUBLIC_PERMISSIONLESS_TUTORIAL.md)