The core product — social login + gasless transactions via session keys — works beautifully. These are all setup and developer experience issues we hit along the way that could be improved.
// Issues
No peer dependency on starknet.js
We installed @cartridge/controller@0.5.9 with starknet@6.24.1. No install warnings. At runtime: "Timeout waiting for keychain" and "externalDetectWallets is not a function". Took significant debugging to discover that @cartridge/controller@0.13.9 requires starknet@>=8.
Add "starknet": ">=8" as a peer dependency so npm warns on install. The old Controller class should log a deprecation warning pointing to ControllerConnector.
Chain ID format mismatch crashes silently
sepolia.id from @starknet-react/chains returns a BigInt decimal (393402133025997798000961). Passing this to ControllerConnector({ defaultChainId }) white-screens the app with:
Uncaught Error: Chain not found: SN_SEPOLIA.
Available chains: SN_SEPOLIA, SN_MAINThe connector expects the hex string "0x534e5f5345504f4c4941". No helpful error message.
Accept both decimal and hex formats, or throw a descriptive error: "defaultChainId must be a hex string like '0x534e5f5345504f4c4941', got number 393402..."
Buffer polyfill requirement not documented
@cartridge/connector uses Node's Buffer internally. In Vite (which doesn't polyfill Node globals), this causes a white screen with Buffer is not defined.
Install vite-plugin-node-polyfills and add to vite.config.ts.
Bundle the polyfill inside @cartridge/connector, or add a prominent note to the quickstart: "Vite users: install vite-plugin-node-polyfills".
RPC v0_7 endpoint breaks with starknet.js v8
Most examples reference api.cartridge.gg/.../rpc/v0_7. Using this with starknet.js v8:
JSON-RPC error: code=-32602,
message="Invalid params",
data={"reason":"Invalid block id"}The versionless endpoint (api.cartridge.gg/x/starknet/sepolia) returns RPC v0.9 and works fine.
Update docs and examples to use the versionless endpoint by default.
No migration guide from v0.5 to v0.13
The API changed significantly between versions:
// v0.5 (old)
new Controller({ rpc: "...", policies: [{ target, method }] })
// v0.13 (new)
new ControllerConnector({
chains: [{ rpcUrl: "..." }],
defaultChainId: "0x...",
policies: { contracts: { [addr]: { methods: [...] } } }
})Also requires @starknet-react/core v5 wrapper (StarknetConfig). We had to piece this together from source code.
Publish a migration guide covering breaking changes between major versions.
CASM hash mismatch on contract declaration
starkli declare with its bundled Cairo compiler (v2.9.4) produced a different CASM hash than what Starknet Sepolia v0.14.1 expected. Had to use --casm-hash flag manually.
A unified scarb deploy command that handles declare + deploy with the correct compiler version for the target network.
// Summary
| Issue | Severity | Impact |
|---|---|---|
| No peer dep on starknet v8 | High | Silent runtime failures |
| Chain ID format mismatch | High | White-screens app |
| Buffer polyfill undocumented | Medium | Blocks all Vite users |
| RPC v0_7 in examples | Medium | Breaks with starknet.js v8 |
| No migration guide | Medium | Hours of debugging |
| CASM hash mismatch | Low | Workaround exists |
Cartridge Controller's core product is excellent. Social login and gasless transactions via session keys deliver a genuinely web2-like UX.
These are all DX improvements that would make the "getting started" experience match the quality of the product itself.