meivan/socosi repository overview

⁠Solidity Sandbox API

Containerized REST API for spinning up isolated Hardhat development sessions, compiling Solidity contracts, and deploying/interacting with them — no local Hardhat setup required.

⁠Features

• Isolated sessions: each session runs its own Hardhat node on a dedicated local port (8545–8600)
• Contract upload: upload .sol files as plain text via HTTP
• Compile on demand: triggers hardhat compile inside the session sandbox
• ABI/artifact retrieval: fetch compiled artifacts (ABI + bytecode) per contract
• Deploy: deploy contracts with constructor arguments via JSON
• Execute: call contract methods (read or write) in batch, with automatic tx receipt handling
• Auto-cleanup: sessions expire after 30 minutes of inactivity (configurable in code); folders and ports are released automatically, and any leftover session data is cleaned on container restart

⁠Quick start

docker run -d -p 3000:3000 -p 8545-8600:8545-8600 meivan/socosi:latest

⁠API overview

⁠Example flow

# 1. Start a session
curl -X POST http://localhost:3000/api/start

# 2. Upload a contract
curl -X POST http://localhost:3000/api/upload/<sessionId> \
  -H "Content-Type: application/json" \
  -d '{"fileName": "Counter.sol", "content": "..."}'

# 3. Compile
curl -X POST http://localhost:3000/api/compile/<sessionId>

# 4. Deploy
curl -X POST http://localhost:3000/api/deploy/<sessionId>/Counter/Counter \
  -H "Content-Type: application/json" \
  -d '{"args": []}'

# 5. Execute methods
curl -X POST http://localhost:3000/api/execute/<sessionId>/Counter/Counter/<address> \
  -H "Content-Type: application/json" \
  -d '{"calls": [{"method": "increment", "args": []}]}'

⁠Notes

• Intended for development/testing environments, not production blockchain networks.
• Each session uses a local Hardhat node — state is ephemeral and lost on session close/timeout.
• This API has no authentication layer built in; deploy behind a gateway or add auth before exposing publicly.