🐛 Challenges I Ran Into

Building Verida, a decentralized document management system integrated with Aptos and IPFS, came with its fair share of technical and architectural hurdles. Some of the most significant challenges I faced were:

🔐 1. Environment Variable Misconfiguration

Early in development, I struggled with environment variables not being recognized in the frontend. I had mistakenly placed the

.env

file in the root directory instead of the

frontend/

directory, which caused

process.env

variables like the Aptos node URL and smart contract address to return

undefined

.

Solution:
I reorganized the folder structure and ensured all environment-specific values were correctly scoped within the React frontend. I also added

.env.local

support for dev environments and used

VITE_

prefixed variables to align with Vite's environment variable convention.

---

📤 2. Smart Contract Upload & Address Confusion

Deploying the Move smart contract to the Aptos blockchain was not as straightforward as expected. I ran into issues understanding how to correctly derive the contract object address and reference it from the frontend.

Solution:
After reviewing Aptos documentation and several test deployments using the Aptos CLI and Faucet, I mapped out the account and module addresses properly. I also integrated proper feedback and logging mechanisms in the frontend to detect missing contracts or misaligned addresses early.

---

🧾 3. File Uploading to IPFS (Pinata)

Another tricky area was uploading documents to IPFS using Pinata. The authentication flow occasionally failed due to expired JWTs or misconfigured API keys, and files were inconsistently being pinned.

Solution:
I implemented error handling and retry logic around the upload process. I also made sure the API keys were securely stored and rotated when needed. For better UX, I added loading states and progress indicators so users wouldn't assume uploads were frozen.

---

🌓 4. Theming and UI Consistency

Designing a clean dark-themed UI that worked well with blockchain loading states, popups, and transaction modals took a lot of iteration. I also faced issues with Tailwind styling conflicting across components.

Solution:
I switched to a component-based design system using Tailwind with utility classes scoped through custom components. I enforced consistent spacing, padding, and color rules across the app to maintain visual harmony.

---

🧪 5. Debugging Cross-Chain Integration (Future Scope)

While Aptos was the primary chain, I initially explored Ethereum-based integration too. Managing dual contracts, metadata synchronization, and user authentication across two chains was highly complex.

Solution:
For now, I scoped down to a single chain (Aptos) with modular architecture so Ethereum can be integrated cleanly in the future without breaking the current setup.

---

Despite all these issues, tackling them helped me deeply understand Web3 tooling, frontend-backend syncing, and blockchain-based data flows. Each hurdle pushed me closer to building a more robust and scalable version of Verida.

---