diff --git a/docs/LP-0013-README.md b/docs/LP-0013-README.md index b7c6d2d..7fa1c8d 100644 --- a/docs/LP-0013-README.md +++ b/docs/LP-0013-README.md @@ -48,167 +48,11 @@ The `lez-authority` crate provides a reusable, program-agnostic authority librar - `programs/token/src/mint.rs` — Authority-gated minting - `programs/token/src/set_authority.rs` — Rotation and revocation handler - `programs/token/src/new_definition.rs` — NewFungibleDefinitionWithAuthority handler -- `program_methods/guest/src/bin/token.rs` — Guest binary dispatch -- `wallet/src/program_facades/token.rs` — SDK facade methods - -## Deployment Steps - -### Prerequisites - -```bash -git clone https://github.com/bristinWild/logos-execution-zone -cd logos-execution-zone -cargo install logos-scaffold -lgs new my-project && cd my-project -lgs setup -``` - -### Start local sequencer - -```bash -lgs localnet start -lgs wallet topup -``` - -### Create accounts - -```bash -lgs wallet -- account new public # definition account -lgs wallet -- account new public # supply account -``` - -### Create token - -```bash -lgs wallet -- token new \ - --definition-account-id \ - --supply-account-id \ - --name "MyCoin" \ - --total-supply 1000000 -``` - -### Mint additional tokens - -```bash -lgs wallet -- token mint \ - --definition \ - --holder \ - --amount 500000 -``` - -### Verify on-chain - -```bash -lgs wallet -- account get --account-id -``` - -## Running Tests - -```bash -# Unit tests -cargo test -p lez-authority --lib -cargo test -p token_program --lib - -# All LP-0013 tests -RISC0_DEV_MODE=1 cargo test -p lez-authority -p token_program --lib -``` - -## Example Scripts - -```bash -# Fixed supply token -bash scripts/examples/fixed_supply_token.sh - -# Variable supply token with authority rotation -bash scripts/examples/variable_supply_token.sh -``` - -## End-to-End Demo - -```bash -RISC0_DEV_MODE=0 bash scripts/demo-full-flow.sh -``` - -## Compute Unit Costs - -| Operation | CU Cost | -|---|---| -| NewFungibleDefinitionWithAuthority | TBD | -| Mint (with authority check) | TBD | -| SetAuthority (rotate) | TBD | -| SetAuthority (revoke) | TBD | - -## References - -- [lez-authority crate](../lez-authority/src/lib.rs) -- [SetAuthority handler](../programs/token/src/set_authority.rs) -- [Mint handler](../programs/token/src/mint.rs) -- [Solana SPL Token - Set Authority](https://solana.com/docs/tokens/basics/set-authority) - -## Deployment - -### Program ID (LEZ localnet/testnet) -efdf86b1127c57c4653903e78bd2174b539fd688054331618c48f98c8fc057bd - -### Deploy -```bash -lgs deploy --program-path target/riscv-guest/token-methods/token-guest/riscv32im-risc0-zkvm-elf/release/token.bin -``` - -## Compute Unit (CU) Costs - -Measured on LEZ localnet with RISC0_DEV_MODE=1 (execution only, no proof): - -| Operation | Execution Time | Notes | -|---|---|---| -| `NewFungibleDefinitionWithAuthority` | ~11ms | Creates token with mint authority | -| `Mint` (with authority) | ~10ms | Authority-gated mint | -| `SetAuthority` (rotate) | ~8ms | Rotates to new key | -| `SetAuthority` (revoke) | ~8ms | Permanently revokes, sets None | - -Note: With `RISC0_DEV_MODE=0`, full ZK proof generation takes 3-10 minutes per transaction on Apple M-series hardware. LEZ's per-transaction compute budget may change during testnet. - -## CLI Usage - -### Create token with mint authority -```bash -spel --idl token-idl.json --program token.bin \ - -- NewFungibleDefinitionWithAuthority \ - --definition-account \ - --holding-account \ - --name "MyToken" \ - --initial-supply 1000000 \ - --mint-authority -``` - -### Mint tokens -```bash -spel --idl token-idl.json --program token.bin \ - -- Mint \ - --definition-account \ - --holding-account \ - --amount-to-mint 500000 -``` - -### Rotate authority -```bash -spel --idl token-idl.json --program token.bin \ - -- SetAuthority \ - --definition-account \ - --new-authority -``` - -### Revoke authority (fix supply permanently) -```bash -spel --idl token-idl.json --program token.bin \ - -- SetAuthority \ - --definition-account \ - --new-authority none -``` +- `programs/token/methods/guest/src/bin/token.rs` — Guest binary dispatch ## Module/SDK -`token_core` provides the reusable types and instructions for building Logos modules: +`token_core` provides the reusable types and instructions for building Logos modules. It is already consumed by `amm`, `ata`, `stablecoin`, and `integration_tests` in this workspace: ```toml [dependencies] @@ -219,3 +63,131 @@ Key types: - `TokenDefinition::Fungible { mint_authority, .. }` — token definition with authority - `Instruction::NewFungibleDefinitionWithAuthority` — create with authority - `Instruction::SetAuthority` — rotate or revoke + +## Deployment + +### Program ID (LEZ localnet) +efdf86b1127c57c4653903e78bd2174b539fd688054331618c48f98c8fc057bd + +### Build the guest binary + +```bash +cargo risczero build --manifest-path programs/token/methods/guest/Cargo.toml +``` + +### Deploy to the sequencer + +```bash +wallet deploy-program target/riscv-guest/token-methods/token-guest/riscv32im-risc0-zkvm-elf/release/token.bin +``` + +## Running Tests + +```bash +# Authority unit tests +cargo test -p lez-authority --lib +cargo test -p token_program --lib + +# Authority integration tests (zkVM, dev mode) +RISC0_DEV_MODE=1 cargo test -p integration_tests --test token -- token_new_fungible_definition_with_authority token_set_authority_revoke +``` + +## CLI Usage (via `spel`) + +### Create token with mint authority + +```bash +spel --idl artifacts/token-idl.json --program \ + -- new-fungible-definition-with-authority \ + --definition-target-account \ + --holding-target-account \ + --name "MyToken" \ + --initial-supply 1000000 \ + --mint-authority +``` + +### Mint tokens + +```bash +spel --idl artifacts/token-idl.json --program \ + -- mint \ + --definition-account \ + --user-holding-account \ + --amount-to-mint 500000 +``` + +### Rotate authority + +```bash +spel --idl artifacts/token-idl.json --program \ + -- set-authority \ + --definition-account \ + --new-authority +``` + +### Revoke authority (fix supply permanently) + +```bash +spel --idl artifacts/token-idl.json --program \ + -- set-authority \ + --definition-account \ + --new-authority none +``` + +## Example Scripts + +```bash +# Fixed supply token (creates with authority, then revokes) +bash scripts/examples/fixed_supply_token.sh + +# Variable supply token (creates with authority, mints more, optionally rotates) +bash scripts/examples/variable_supply_token.sh +``` + +## End-to-End Demo + +The demo script must be run from inside an `lgs` scaffold project directory (where the localnet and wallet live): + +```bash +# 1. Set up an lgs scaffold (if you don't have one): +cargo install logos-scaffold +lgs new my-scaffold && cd my-scaffold +lgs setup +lgs localnet start +lgs wallet topup + +# 2. Deploy the token program: +lgs deploy --program-path /path/to/lez-programs/target/riscv-guest/token-methods/token-guest/riscv32im-risc0-zkvm-elf/release/token.bin + +# 3. Run the demo: +RISC0_DEV_MODE=0 bash /path/to/lez-programs/scripts/demo-full-flow.sh +``` + +The script will: +1. Verify the localnet is running +2. Fund the wallet +3. Create 3 token accounts (definition, supply holder, recipient) +4. Submit `NewFungibleDefinitionWithAuthority` (creates "DemoCoin" with 1M supply) +5. Submit `Mint` (mints 500K to recipient → total supply 1.5M) +6. Submit `SetAuthority` with `None` (permanently revokes minting) +7. Run unit tests to verify authority logic (60 tests) + +## Compute Unit (CU) Costs + +Measured on LEZ localnet with `RISC0_DEV_MODE=1` (execution only, no proof): + +| Operation | Execution Time | Notes | +|---|---|---| +| `NewFungibleDefinitionWithAuthority` | ~11ms | Creates token with mint authority | +| `Mint` (with authority) | ~10ms | Authority-gated mint | +| `SetAuthority` (rotate) | ~8ms | Rotates to new key | +| `SetAuthority` (revoke) | ~8ms | Permanently revokes, sets None | + +Note: With `RISC0_DEV_MODE=0`, full ZK proof generation takes 3–10 minutes per transaction on Apple M-series hardware. LEZ's per-transaction compute budget may change during testnet. + +## References + +- [lez-authority crate](../lez-authority/src/lib.rs) +- [SetAuthority handler](../programs/token/src/set_authority.rs) +- [Mint handler](../programs/token/src/mint.rs) +- [Solana SPL Token - Set Authority](https://solana.com/docs/tokens/basics/set-authority)