{"id":32544071,"url":"https://github.com/lokapal-xyz/plexus-archive","last_synced_at":"2026-05-15T18:04:22.782Z","repository":{"id":317076572,"uuid":"1065882304","full_name":"lokapal-xyz/plexus-archive","owner":"lokapal-xyz","description":"A repository to create web3 components for Lit3 projects (Literature in Web3)","archived":false,"fork":false,"pushed_at":"2025-09-28T16:27:46.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-28T18:24:06.994Z","etag":null,"topics":["cryptocurrency","graphql","lit3","subgraph","web3"],"latest_commit_sha":null,"homepage":"https://www.lokapal.xyz/","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lokapal-xyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T16:08:03.000Z","updated_at":"2025-09-28T16:35:05.000Z","dependencies_parsed_at":"2025-10-01T06:47:50.825Z","dependency_job_id":null,"html_url":"https://github.com/lokapal-xyz/plexus-archive","commit_stats":null,"previous_names":["lokapal-xyz/plexus-archive"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lokapal-xyz/plexus-archive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokapal-xyz%2Fplexus-archive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokapal-xyz%2Fplexus-archive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokapal-xyz%2Fplexus-archive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokapal-xyz%2Fplexus-archive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lokapal-xyz","download_url":"https://codeload.github.com/lokapal-xyz/plexus-archive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokapal-xyz%2Fplexus-archive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33074416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptocurrency","graphql","lit3","subgraph","web3"],"created_at":"2025-10-28T17:22:46.656Z","updated_at":"2026-05-15T18:04:22.777Z","avatar_url":"https://github.com/lokapal-xyz.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plexus Archive\n\nA Solidity smart contract for archiving metadata of micro-stories and narrative fragments on Base blockchain networks. Only designated Archivists can add new entries, making it perfect for curated storytelling projects, digital literature archives, or any content that requires immutable timestamping and provenance.\n\n---\n\n## Features\n\n- **Archivist-Only Access**: Only the designated archivist can archive new shards\n- **Immutable Metadata Storage**: Each shard contains title, source, timestamps, and observations\n- **Fast Timestamping**: Python script to calculate UTC and Lanka time timestamps\n- **Multi-Network Support**: Deploy to Base Sepolia (testnet) and Base Mainnet\n- **Contract Verification**: Automatic source code verification on BaseScan\n- **Query Functions**: Retrieve shards by index, batch, latest, or by echo source\n\n---\n\n## Project Structure\n\n```\n├── src/\n│   └── PlexusArchive.sol           # Main contract\n├── script/\n│   ├── DeployPlexusArchive.s.sol   # Deployment script\n│   └── InteractWithPlexus.s.sol    # Interaction script for queries/archiving\n├── test/\n│   └── PlexusArchiveTest.t.sol     # Comprehensive test suite\n├── deployments/                    # Network-specific deployment info\n├── .env.example                    # Environment variables framework\n├── deploy-archive.sh               # Multi-network deployment script\n├── archive-shard.sh                # Archive new shards\n├── query-plexus.sh                 # Query existing shards\n├── foundry.toml                    # Foundry settings\n└── shard-time.sh                   # Calculate UTC and Lanka time\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Foundry](https://book.getfoundry.sh/getting-started/installation)\n- Base Sepolia ETH ([faucet](https://faucet.quicknode.com/base))\n- BaseScan API key ([sign up](https://etherscan.io/apis?id=8453))\n\n### Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/lokapal-xyz/plexus-archive\ncd plexus-archive\n```\n\n2. **Install Foundry dependencies:**\n```bash\nforge install\n```\n\n3. **Create environment file:**\n```bash\ncp .env.example .env\n# Edit .env with your private key and API key\n```\n\n4. **Make scripts executable:**\n```bash\nchmod +x deploy-archive.sh archive-shard.sh query-plexus.sh\n```\n\n5. **Run tests:**\n```bash\nforge test\n```\n\n### Environment Configuration\n\nComplete the `.env` file with the following content:\n\n```bash\n# Private Key (create a dedicated wallet for this project)\nPRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE\n\n# API Keys\nBASESCAN_API_KEY=your_basescan_api_key_here\n\n# RPC URLs (optional - uses public endpoints by default)\nBASE_SEPOLIA_RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_KEY\nBASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY\n\n# Contract Addresses (auto-populated after deployment)\nCONTRACT_ADDRESS_BASE_SEPOLIA=\nCONTRACT_ADDRESS_BASE=\n\n## Active Contract Address (auto-populated after deployment)\nCONTRACT_ADDRESS=\n\n```\n\n### Deployment\n\nDeploy to Base Sepolia (testnet) first:\n\n```bash\n./deploy-archive.sh base-sepolia\n```\n\nFor mainnet deployment (uses real ETH):\n\n```bash\n./deploy-archive.sh base\n```\n\nThe script will:\n- Deploy and verify the contract\n- Create deployment JSON files\n- Update your `.env` with contract addresses\n- Provide BaseScan links\n\n---\n\n## Usage\n\n### Archive New Shard\n\nCalculate UTC and Lanka Time:\n\n```bash\npython3 shard-time.py\n```\n\nTemplate command (edit values before running):\n\n```bash\n./archive-shard.sh base-sepolia \"SHARD_TITLE\" \"ECHO_SOURCE\" \"UTC_TIME\" \"LANKA_TIME\" \"ARCHIVIST_LOG\"\n```\n\nExample:\n```bash\n./archive-shard.sh base-sepolia \"Lighting a Cigar\" \"Lobha Exchange Train Network\" \"2025-09-27 00:51:53 UTC\" \"Varsam 7E9, Dinam 10E, Kala 040\" \"Honor is not fitting in a fool\"\n```\n\n### Query Shards\n\nGet contract status:\n```bash\n./query-plexus.sh base-sepolia status\n```\n\nGet latest shards:\n```bash\n./query-plexus.sh base-sepolia get-latest 5\n```\n\nGet specific shard by index:\n```bash\n./query-plexus.sh base-sepolia get-shard 0\n```\n\nGet shards by echo source:\n```bash\n./query-plexus.sh base-sepolia get-by-source \"Lobha Exchange Train Network\"\n```\n\nAll available query commands:\n- `status` - Contract information and stats\n- `get-total` - Total number of archived shards\n- `get-shard \u003cindex\u003e` - Specific shard by index\n- `get-latest [count]` - Latest shards (default: 5)\n- `get-batch \u003cstart\u003e \u003ccount\u003e` - Batch of shards\n- `get-by-source \"\u003csource\u003e\"` - Find shards by echo source\n\n---\n\n## Contract API\n\n### Shard Structure\n\n```solidity\nstruct Shard {\n    string shardTag;        // Shard title\n    string echoSource;      // Exact location of the transmition\n    uint256 earthTime;      // Real-world reception timestamp\n    string lankaTime;       // Lanka transmition timestamp\n    string archivistLog;    // Observations from the Archivist\n}\n```\n\n### Main Functions\n\n- `archiveShard()` - Add new shard (archivist only)\n- `getShard(uint256 index)` - Get shard by index\n- `getTotalShards()` - Get total number of shards\n- `getLatestShards(uint256 count)` - Get latest shards\n- `getShardsBatch(uint256 start, uint256 count)` - Get batch of shards\n- `getShardsByEchoSource(string source)` - Find shards by source\n- `transferArchivist(address newArchivist)` - Transfer archivist role\n\n---\n\n## Integration with Frontend Applications\n\n### The Graph Integration\n\nFor production applications, integrate with The Graph for efficient querying:\n\n1. Create a subgraph indexing the `ShardArchived` events\n2. Use GraphQL queries for complex filtering and pagination\n3. Implement real-time updates with subscriptions\n\n- To view the full Subgraph implementation, [**click here**](subgraph-deployment-guide.md)\n\n### Next.js Integration\n\nKeep contracts and frontend in separate repositories:\n\n```\nmy-website/           # Next.js app\n├── lib/\n│   └── contracts/    # Copy deployment JSONs here\n└── components/\n\nplexus-contracts/     # This repository\n```\n\nCopy deployment files when needed:\n```bash\ncp deployments/base.json ../my-website/lib/contracts/\n```\n\n---\n\n## Network Information\n\n### Base Sepolia (Testnet)\n- Chain ID: 84532\n- RPC: https://sepolia.base.org\n- Explorer: https://sepolia.basescan.org\n- Faucet: https://faucet.quicknode.com/base\n\n### Base Mainnet\n- Chain ID: 8453\n- RPC: https://mainnet.base.org\n- Explorer: https://basescan.org\n\n---\n\n## Security Considerations\n\n- **Archivist Role**: Only the archivist can add shards. Transfer this role carefully\n- **Private Key**: Use a dedicated wallet for contract operations\n- **Testnet First**: Always test on Base Sepolia before mainnet deployment\n- **Gas Optimization**: Contract uses efficient storage patterns and batch operations\n\n---\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nforge test\n\n# Run with gas reporting\nforge test --gas-report\n\n# Run specific test\nforge test --match-test testArchiveShard\n\n# Run with verbose output\nforge test -vvv\n```\n\nTests cover:\n- Contract deployment and initialization\n- Shard archiving with various inputs\n- Access control (archivist-only functions)\n- Retrieval functions and edge cases\n- Batch operations and pagination\n- Event emission\n- Fuzz testing for edge cases\n\n---\n\n## Misc\n\n### Gas Costs\n\nTypical gas usage:\n- Contract deployment: ~1.25M gas\n- Archive shard: ~100K gas\n- Query functions: \u003c50K gas (read-only)\n\n---\n\n### Use Cases\n\nThis contract pattern is suitable for:\n- Digital literature and storytelling projects\n- Content archiving with provenance\n- Timestamped metadata storage\n- Curated digital art projects\n- Academic research with immutable records\n- Creative writing communities\n- Interactive fiction projects\n\n### License\n\nMIT License - see LICENSE file for details\n\n### Support\n\n- Create an issue for bugs or feature requests\n- Check existing issues before creating new ones\n- Provide detailed information including network, transaction hashes, and error messages\n\n---\n\nBuilt with Foundry by lokapal.eth","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flokapal-xyz%2Fplexus-archive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flokapal-xyz%2Fplexus-archive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flokapal-xyz%2Fplexus-archive/lists"}