@vocdoni/davinci-sdk 0.1.0 → 0.1.1

package/README.md

@@ -256,6 +256,55 @@ const process = await sdk.createProcess({
 });
 ```
 
+#### OnchainCensus - Token-Based Voting
+
+Use existing on-chain token contracts (ERC20, ERC721) for voting eligibility. Perfect for DAO governance where voting power comes from token holdings.
+
+```typescript
+import { OnchainCensus } from '@vocdoni/davinci-sdk';
+
+// Create census from token contract address with subgraph URI
+const census = new OnchainCensus(
+  "0x1234567890123456789012345678901234567890", // Token contract address
+  "https://api.studio.thegraph.com/query/12345/token-holders/v1.0.0" // Subgraph endpoint
+);
+
+const process = await sdk.createProcess({
+  census: census,
+  maxVoters: 10000, // Required for onchain census
+  // ... rest of config
+});
+```
+
+**Key Features:**
+- **No Publishing Required**: Uses existing on-chain data, no need to publish
+- **Automatic Validation**: Contract address and URI validated on construction
+- **Token Agnostic**: Works with any ERC20 or ERC721 contract
+- **DAO Ready**: Perfect for token-based governance systems
+- **Subgraph Integration**: URI should point to a subgraph or API endpoint for census data
+
+**Technical Details:**
+- `censusRoot` automatically set to 32-byte zero value (`0x0000...000`)
+- `contractAddress` properly passed to smart contracts
+- `uri` parameter is **required** and should point to a data source (e.g., subgraph)
+- Census is immediately ready for process creation
+
+**Example with different subgraph providers:**
+
+```typescript
+// The Graph Studio
+const census = new OnchainCensus(
+  "0xTokenAddress...",
+  "https://api.studio.thegraph.com/query/12345/my-token/v1.0.0"
+);
+
+// Custom subgraph deployment
+const census = new OnchainCensus(
+  "0xTokenAddress...",
+  "https://subgraph.example.com/api/token-holders"
+);
+```
+
 ### Auto-Publishing Feature
 
 The SDK automatically publishes unpublished censuses when creating a process:

package/dist/contracts.d.ts

@@ -390,7 +390,19 @@ interface BallotMode {
 interface CensusData {
     censusOrigin: CensusOrigin;
     censusRoot: string;
+    /**
+     * Contract address for onchain censuses (ERC20/ERC721 token contract).
+     * For offchain censuses, defaults to zero address.
+     * @default "0x0000000000000000000000000000000000000000"
+     */
+    contractAddress?: string;
     censusURI: string;
+    /**
+     * For onchain censuses, allows any valid Merkle root from the onchain source.
+     * For other census types, set to false to require the specific censusRoot.
+     * @default false
+     */
+    onchainAllowAnyValidRoot?: boolean;
 }
 interface EncryptionKey {
     x: string;

package/dist/index.d.ts

@@ -402,9 +402,9 @@ declare class OnchainCensus extends Census {
     /**
      * Creates an OnchainCensus
      * @param contractAddress - The address of the smart contract (e.g., ERC20, ERC721)
-     * @param uri - Optional URI with census information
+     * @param uri - The URI pointing to census data source (e.g., subgraph endpoint)
      */
-    constructor(contractAddress: string, uri?: string);
+    constructor(contractAddress: string, uri: string);
     get contractAddress(): string;
 }
 
@@ -453,6 +453,7 @@ declare class CensusOrchestrator {
         type: CensusOrigin;
         root: string;
         uri: string;
+        contractAddress?: string;
     };
 }
 
@@ -469,7 +470,19 @@ interface BallotMode {
 interface CensusData {
     censusOrigin: CensusOrigin;
     censusRoot: string;
+    /**
+     * Contract address for onchain censuses (ERC20/ERC721 token contract).
+     * For offchain censuses, defaults to zero address.
+     * @default "0x0000000000000000000000000000000000000000"
+     */
+    contractAddress?: string;
     censusURI: string;
+    /**
+     * For onchain censuses, allows any valid Merkle root from the onchain source.
+     * For other census types, set to false to require the specific censusRoot.
+     * @default false
+     */
+    onchainAllowAnyValidRoot?: boolean;
 }
 interface EncryptionKey {
     x: string;

package/dist/index.js

@@ -386,16 +386,19 @@ class OnchainCensus extends Census {
   /**
    * Creates an OnchainCensus
    * @param contractAddress - The address of the smart contract (e.g., ERC20, ERC721)
-   * @param uri - Optional URI with census information
+   * @param uri - The URI pointing to census data source (e.g., subgraph endpoint)
    */
   constructor(contractAddress, uri) {
     super(CensusOrigin.Onchain);
     if (!/^(0x)?[0-9a-fA-F]{40}$/i.test(contractAddress)) {
       throw new Error("Contract address is missing or invalid");
     }
+    if (!uri || uri.trim() === "") {
+      throw new Error("URI is required for onchain census");
+    }
     this._contractAddress = contractAddress;
-    this._censusRoot = contractAddress;
-    this._censusURI = uri || `contract://${contractAddress}`;
+    this._censusRoot = "0x0000000000000000000000000000000000000000000000000000000000000000";
+    this._censusURI = uri;
   }
   get contractAddress() {
     return this._contractAddress;
@@ -475,10 +478,12 @@ class CensusOrchestrator {
     if (!census.censusRoot || !census.censusURI) {
       throw new Error("Census data is incomplete");
     }
+    const contractAddress = "contractAddress" in census ? census.contractAddress : void 0;
     return {
       type: census.censusOrigin,
       root: census.censusRoot,
-      uri: census.censusURI
+      uri: census.censusURI,
+      contractAddress
     };
   }
 }
@@ -1002,7 +1007,9 @@ class ProcessRegistryService extends SmartContractService {
     const contractCensus = {
       censusOrigin: BigInt(census.censusOrigin),
       censusRoot: census.censusRoot,
-      censusURI: census.censusURI
+      contractAddress: census.contractAddress ?? "0x0000000000000000000000000000000000000000",
+      censusURI: census.censusURI,
+      onchainAllowAnyValidRoot: census.onchainAllowAnyValidRoot ?? false
     };
     return this.sendTx(
       this.contract.newProcess(
@@ -1033,7 +1040,9 @@ class ProcessRegistryService extends SmartContractService {
     const contractCensus = {
       censusOrigin: BigInt(census.censusOrigin),
       censusRoot: census.censusRoot,
-      censusURI: census.censusURI
+      contractAddress: census.contractAddress ?? "0x0000000000000000000000000000000000000000",
+      censusURI: census.censusURI,
+      onchainAllowAnyValidRoot: census.onchainAllowAnyValidRoot ?? false
     };
     return this.sendTx(
       this.contract.setProcessCensus(processID, contractCensus).catch((e) => {
@@ -1165,12 +1174,7 @@ class ProcessOrchestrationService {
         }
         await this.censusOrchestrator.publish(census);
       }
-      const censusData = this.censusOrchestrator.getCensusData(census);
-      return {
-        type: censusData.type,
-        root: censusData.root,
-        uri: censusData.uri
-      };
+      return this.censusOrchestrator.getCensusData(census);
     }
     const { size, ...censusWithoutSize } = census;
     return censusWithoutSize;
@@ -1400,7 +1404,12 @@ class ProcessOrchestrationService {
     const census = {
       censusOrigin: censusConfig.type,
       censusRoot,
-      censusURI: censusConfig.uri
+      contractAddress: censusConfig.contractAddress,
+      // Only set for onchain censuses
+      censusURI: censusConfig.uri,
+      // For onchain censuses (ERC20 token snapshots), allow any valid merkle root
+      // For other census types, require the specific censusRoot
+      onchainAllowAnyValidRoot: censusConfig.type === CensusOrigin.Onchain
     };
     return {
       processId,