> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genlabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

> ABI validation surprises, dependency-resolution failures after a fresh init, and CLI signer-missing errors.

<Accordion title="ABI validation failure: `'X' is referenced but has no definition`">
  Symptom while building or generating a typed client:

  ```text theme={null}
  ABI validation error: 'usize' is referenced but has no definition
  ```

  Cause: a type used in a contract method (parameter, return type, struct
  field) isn't part of the ABI-visible surface, usually because the `use`
  statement is missing or the type is a primitive Genie doesn't model directly.

  Fix: import the type explicitly from the appropriate crate, or replace
  generic primitives with Genie's wrappers (e.g. `AmountInSubunits` instead of
  `u128` for balances, the genesis `Holder` type instead of a raw component id).
</Accordion>

<Accordion title="`unresolved module or unlinked crate monoio` after a fresh `gen genie init-contract`">
  The scaffolded `Cargo.toml` references workspace dependencies that haven't
  fully resolved yet. Run a full clean fetch first:

  ```bash theme={null}
  cargo clean
  cargo fetch
  gen genie build <contract>
  ```

  If the error persists, you're hitting the
  [GitHub auth issue](/reference/troubleshooting/devcontainer) — Cargo can't
  reach `gen-bc/gen-framework-preview` to fetch `monoio`'s upstream.
</Accordion>

<Accordion title="`Failed to deserialize deploy` on a fresh `init-contract` + first test">
  Cause: the scaffolded `#[deploy]` signature doesn't match what the test crate
  expects (often because the test was generated against a different framework
  version). Either:

  * Regenerate the contract with `gen genie init-contract` against your current
    framework version, **or**
  * Update the test's `deploy_contract(...)` call site to match the deploy
    signature in your `my_token_contract.rs`.
</Accordion>

<Accordion title="Duplicate-dependency failure when depending on a local gen project">
  Symptom: Cargo complains about `genie` (or another framework crate) being
  declared twice, once via the local path and once transitively through the
  framework. Cause: you've added a workspace dependency on a local-path crate
  that itself depends on the framework via git, while your top-level workspace
  also pulls the framework via git.

  Fix: use a single source of truth — either all-local (via path overrides in
  `Cargo.toml` `[patch]`) or all-git.
</Accordion>

<Accordion title="Mutating CLI command rejected with `ERROR: Mutating client commands require --private-key-hex`">
  `push`, `deploy`, `install`, `build-activation`, and `sign-and-submit-activation`
  all need a signer. The CLI normally pulls one from the active wallet, but if
  no wallet is configured (or you're in an automation context with no
  keystore) it errors out as above.

  Fix: pass `--wallet <name>` (the CLI then signs with that wallet) or
  `--private-key-hex 0x...` explicitly. The latter is the right pattern for
  CI / agentic scripts where the key lives in a secret manager.
</Accordion>

<Note>
  Hit something not on this page? Send the failing command and the full error
  output to your Gen Labs contact — the page grows from real reports.
</Note>