Metadata-Version: 2.4
Name: 2n20
Version: 0.2.0
Summary: Local trading-key setup and public connection checks for 2n20 creators
Author: 2n20
License-Expression: MIT
Project-URL: Homepage, https://2n20.org
Project-URL: Documentation, https://2n20.org/docs/quickstart
Project-URL: Repository, https://github.com/2n20/2n20
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotated-types==0.8.0
Requires-Dist: bitarray==3.11.0
Requires-Dist: ckzg==2.1.8
Requires-Dist: cytoolz==1.1.0
Requires-Dist: eth-account==0.13.7
Requires-Dist: eth-hash==0.8.0
Requires-Dist: eth-keyfile==0.8.1
Requires-Dist: eth-keys==0.8.0
Requires-Dist: eth-rlp==3.0.0
Requires-Dist: eth-typing==6.0.0
Requires-Dist: eth-utils==6.0.0
Requires-Dist: eth_abi==6.0.0
Requires-Dist: hexbytes==2.0.0
Requires-Dist: parsimonious==0.10.0
Requires-Dist: pycryptodome==3.23.0
Requires-Dist: pydantic==2.13.5
Requires-Dist: pydantic_core==2.46.5
Requires-Dist: regex==2026.9.10
Requires-Dist: rlp==5.0.0
Requires-Dist: toolz==1.1.0
Requires-Dist: typing-inspection==0.4.4
Requires-Dist: typing_extensions==4.16.0
Dynamic: license-file

# 2n20 creator setup

The official 2n20 CLI prepares trading-key consent on the computer or server
where your existing strategy runs. It supplies public account configuration
and read-only checks. You supply and run your own strategy in any language.

Requires Python 3.10 or later on Linux, macOS or WSL. Run commands in your
strategy's working directory with its Python environment activated.

Confirm the strategy host and project directory first. Check the prerequisites
and installed release with `python3 --version` and `2n20 --version`. Use the
installation instructions for a release available on the official
[PyPI project](https://pypi.org/project/2n20/); resumable onboarding requires
version 0.2.0 or later. Never install a version that has not been published.

Copy the onboarding command from Step 2 of your vault page:

```sh
2n20 onboard --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet'
```

The CLI verifies the chain, factory, deployed contract code, vault bindings,
trading-account bindings, consent capability and next approval nonce from
public contract reads. This release bundles the currently supported HyperEVM
mainnet deployment. Other networks and unsupported deployments fail closed.
Vault URLs can select only a vault address and network. They cannot override
RPC endpoints or supply an approval contract, trading account or nonce.

Onboard creates one vault-scoped directory with mode `700` under your current
working directory. Repeating the same command resumes the exact retained key
and active approval handoff. Use `--directory <directory>` to choose a new or
existing setup explicitly, including a 0.1.0 setup. Its parent must exist.
If an older matching setup exists here, the CLI returns public directory
choices and waits for you to select one. It never silently chooses another
key or replaces a missing recorded key.

Inside a Git checkout, the CLI confirms the key path is ignored before
creating or loading it. It preserves existing ignore patterns and adds only
the exact key path if needed. A tracked key destination stops onboarding
before private access; resolve that Git conflict yourself. Generated files
use exclusive creation and private permissions. Public checkpoints update
atomically, and concurrent commands cannot own the same setup.

- `strategy.key`: your new private trading key, mode `600`. Keep it only on
  your strategy machine. Never paste, import, upload, commit or log this file.
- `consent.public.json`: a public signature, trading-key address, vault,
  approval contract, nonce and expiry. Onboard submits only this public object
  and verified public owner/account bindings to obtain an approval link.
  If that service is unavailable, import or paste only this public file into
  Step 2 and approve it with your creator wallet.
- `setup.public.json`, `key-reservation.public.json` and
  `onboarding.public.json`: public recovery metadata. Keep them alongside
  the private key so interruption and ambiguous responses resume safely.
- `config.public.json` and `status.public.json`: public strategy settings
  and the last verification result. Readiness must be freshly verified before
  starting your strategy; an old public file does not establish current access.

Open the returned approval URL and approve with your creator wallet. CLI
setup itself never submits a transaction. Then resume on the strategy host:

```sh
2n20 onboard --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet' --wait 60 --json
```

`--wait` accepts 0 to 300 seconds and uses bounded polling with backoff;
individual public requests also have timeouts. The default returns immediately
after one verification pass. JSON includes the stable stage, exit code,
`requiredHumanAction`, `publicEvidence`, `publicArtifacts` and an exact
`resumeCommand`. Public service state or a wallet nomination alone never
counts as verified trading access.

| Stage | Exit | Next action |
| --- | --- | --- |
| `approval_required` | 2 | Creator approves the URL or imports the indicated public file. |
| `approval_pending`, `funding_pending` | 2 | Wait for verified public state, then resume. |
| `selection_required` | 2 | Select the existing directory returned by the CLI. |
| `consent_expired` | 2 | Run the returned `renewCommand`, then resume. |
| `ready` | 0 | Configure the existing strategy and run its connection check. |
| `retry_required` | 3 | Resolve the temporary read or persistence failure, then resume. |
| `conflict` | 4 | Resolve the reported binding, key or directory conflict. |
| `interrupted` | 130 | Resume the same command and directory. |

Keep the directory and key when a network read fails. If consent expires
(after one hour), or another approval changes its nonce, run on that same
strategy machine:

```sh
2n20 renew --directory ./<your-setup-directory>
```

Renew retains the existing private key and writes a new uniquely named
`consent.<time>-<random>.public.json`. Resume onboard to use that file, or
import it into Step 2. An expired approval link with otherwise valid consent
can be renewed automatically only after the same unused key passes fresh
contract checks. Older public consent files remain intact. A missing key,
another requested key or changed creator/account bindings stops the workflow
for explicit resolution. The app and contract recheck nonce and expiry when
you approve.

After Step 2 confirms trading access, get the public settings for Step 3:

```sh
2n20 config --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet'
2n20 status --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet'
```

Use `tradingAccount` as your strategy's Hyperliquid account address. It is
separate from the `vault` holding shares and the `approvalContract` your
creator wallet calls. Load the private key locally using your strategy's own
key configuration. The CLI does not load your existing strategy's secrets.

Status checks the current public key approval, account binding and funding.
Missing or inconsistent public evidence never counts as trading readiness.
Exit code `0` means public trading access was verified, `2` means it is
pending or unverified, and `1` means verification could not complete. This
check does not prove your strategy is running. Run its own connection check
before starting it. These commands submit no transactions, move no collateral
and place no orders. Setup does not depend on temporary Hyperliquid balance or
funding API availability.

To check a public consent before importing it:

```sh
2n20 check-consent --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet' --consent ./<your-setup-directory>/consent.public.json
```

The original manual import workflow remains available with
`2n20 setup --vault '<vault link>'`. It creates a fresh unique directory,
or accepts `--output <new-directory>`, and produces the public consent file
without an approval-service request. Resume incomplete setup through
`onboard --vault '<vault link>' --directory '<retained directory>'`.

## Portable agent guidance

The release bundles the portable `2n20-setup` skill. Export is explicit and
writes only `SKILL.md` into the new directory you select:

```sh
mkdir -p .agents/skills
2n20 skill export --directory .agents/skills/2n20-setup
```

Choose your harness's skill directory explicitly, such as `.claude/skills`
for Claude Code. Existing export folders are never overwritten; no harness
configuration changes happen automatically. The skill guides host selection,
same-directory resume, human wallet approval and public access verification.
It asks an agent to inspect only safe strategy source and secret-loading
interfaces, make scoped reviewable configuration changes, and use the
strategy's existing connection check. Agents must never inspect private key
files or enable orders, restart a live bot or invent a strategy.

## Reproducible development and release

`requirements-release.txt` contains the reviewed, fully pinned build and
runtime graph with registry SHA-256 hashes. `dependency-review.json` records
its registry publication dates. All third-party release files were at least
14 days old when reviewed on October 3, 2026. The wheel also pins the complete
runtime graph to retain these reviewed versions for ordinary installs.
The only underlying runtime library is `eth-account` and its dependencies;
Hyperliquid's SDK is not required.

```sh
python3 -m venv .venv
.venv/bin/python -m pip install --require-hashes -r requirements-release.txt
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
SOURCE_DATE_EPOCH=1790985600 .venv/bin/python scripts/build_release.py
```

The release script calls standard `python -m build --no-isolation`, verifies
archive paths, and normalizes the source archive ownership, timestamps and
gzip header. Keep `SOURCE_DATE_EPOCH` fixed for a release. Repeated builds from
the same source and reviewed environment produce identical wheel and source
archive bytes. Use `--outdir <directory>` to compare independent builds.

Release trust anchors are copied from the repository's reviewed active
`deployments/development.json`, never fetched as authority from a website.
A supported deployment change requires reviewing and releasing the package.
Publishing uses GitHub Actions OIDC Trusted Publishing with dedicated PyPI
and TestPyPI environments, not stored API tokens. Maintainer release steps
and publisher identities are in the repository operations runbook.
