lukso-network · tehnalogos · Jun 7, 2026 · Jun 7, 2026
diff --git a/docs/evm/_category_.yml b/docs/evm/_category_.yml
@@ -0,0 +1,3 @@
+label: 'EVM Builders'
+position: 2
+collapsed: false
diff --git a/docs/evm/compare/_category_.yml b/docs/evm/compare/_category_.yml
@@ -0,0 +1,3 @@
+label: 'Compare'
+position: 20
+collapsed: false
diff --git a/docs/evm/compare/eip4337-vs-universal-profile.mdx b/docs/evm/compare/eip4337-vs-universal-profile.mdx
@@ -0,0 +1,101 @@
+---
+title: 'EIP-4337 vs Universal Profile | Account Abstraction on LUKSO'
+sidebar_label: EIP-4337 vs UP
+sidebar_position: 6
+description: Compare EIP-4337 account abstraction concepts with LUKSO Universal Profiles, LSP6 permissions, and LSP25 relay calls.
+keywords:
+  - EIP-4337 vs Universal Profile
+  - account abstraction vs Universal Profile
+  - LUKSO smart accounts
+  - EVM account abstraction
+---
+
+import StructuredData from '@site/src/components/StructuredData';
+
+<StructuredData
+  data={{
+    '@context': 'https://schema.org',
+    '@type': 'TechArticle',
+    headline: 'EIP-4337 vs Universal Profile',
+    description:
+      'Technical comparison of EIP-4337 account abstraction patterns and LUKSO Universal Profiles.',
+    author: { '@type': 'Organization', name: 'LUKSO' },
+    publisher: { '@type': 'Organization', name: 'LUKSO' },
+    about: ['EIP-4337', 'Universal Profile', 'Account abstraction', 'LSP6', 'LSP25'],
+    mainEntityOfPage:
+      'https://docs.lukso.tech/evm/compare/eip4337-vs-universal-profile/',
+    isAccessibleForFree: true,
+  }}
+/>
+
+# EIP-4337 vs Universal Profile
+
+EIP-4337 defines an account-abstraction transaction flow around user operations, bundlers, paymasters, and validation logic. Universal Profiles define a LUKSO smart-account standard around ERC725Y storage, LSP6 permissions, LSP1 receiver hooks, and LSP25 relay execution.
+
+They solve overlapping UX problems, but they are not the same layer.
+
+## Direct answer
+
+EIP-4337 is a transaction-flow standard for account abstraction. Universal Profile is a LUKSO smart-account standard. For "account abstraction vs smart account standard" comparisons, the distinction is:
+
+- EIP-4337 focuses on how user operations are validated, bundled, paid for, and submitted.
+- Universal Profiles focus on what the account is: metadata, permissions, receiver behavior, signature verification, ownership, and relay execution.
+
+Universal Profiles can be part of an account-abstraction strategy, but they should not be described as merely "LUKSO's version of EIP-4337."
+
+## Concept map
+
+| Account-abstraction concern | EIP-4337 framing | Universal Profile framing |
+| --- | --- | --- |
+| Account contract | Smart account implementation. | LSP0 ERC725Account / UniversalProfile. |
+| Authorization | `validateUserOp` and account validation logic. | LSP6 Key Manager permissions and controller signatures. |
+| Gas sponsorship | Paymasters. | LSP25 relay calls through relayer services. |
+| User identity | Depends on the account implementation. | LSP3 profile metadata stored through ERC725Y. |
+| Receiver behavior | Depends on app/account implementation. | LSP1 Universal Receiver hooks. |
+
+## What LUKSO solves outside the 4337 transaction flow
+
+| Problem EVM developers run into | LUKSO standard surface |
+| --- | --- |
+| "My smart account needs public profile data." | LSP3 profile metadata on ERC725Y storage. |
+| "My app needs a session key, but only for selected calls." | LSP6 Key Manager allowed calls. |
+| "My app needs to edit only selected metadata keys." | LSP6 allowed ERC725Y data keys. |
+| "My account should reject or register incoming assets." | LSP1 Universal Receiver plus LSP5 received assets. |
+| "My backend should relay signed account actions." | LSP25 relay calls and nonce channels. |
+| "My login flow needs smart-account signatures." | EIP-1271-compatible `isValidSignature` on the profile. |
+
+## Integration mindset
+
+If you already understand 4337, map the pieces like this:
+
+```text
+UserOperation validation  -> account/control validation
+Paymaster sponsorship     -> gas sponsorship concern
+Bundler submission        -> transaction delivery concern
+Universal Profile         -> account identity and behavior
+LSP6 Key Manager          -> account permission policy
+LSP25 relay call          -> signed execution path used by LUKSO tooling
+```
+
+The LUKSO docs include a 4337 extension guide for developers who need that compatibility path. Start there only after you are clear on what the Universal Profile and Key Manager are responsible for.
+
+## When to use which docs
+
+If you are building on LUKSO, start with Universal Profiles, LSP6 permissions, and LSP25 relay calls. If you need ERC-4337 compatibility, read the 4337 extension material and decide how it should integrate with your profile/account flow.
+
+## Production checklist
+
+1. Do not use 4337 terms as a substitute for LSP6 permission design.
+2. Decide whether gas sponsorship is a paymaster problem, an LSP25 relay problem, or both in your architecture.
+3. Store user identity against the Universal Profile address.
+4. Verify which controller is allowed to sign, call, relay, or edit metadata.
+5. Test direct calls, relay calls, and any 4337 extension path separately.
+6. Document which layer owns replay protection and nonce handling.
+
+## Implementation references
+
+- [4337 extension guide](../../learn/universal-profile/advanced-guides/4337-extension.md)
+- [LSP0 ERC725Account standard](../../standards/accounts/lsp0-erc725account.md)
+- [LSP6 Key Manager standard](../../standards/access-control/lsp6-key-manager.md)
+- [LSP25 Execute Relay Call standard](../../standards/accounts/lsp25-execute-relay-call.md)
+- [Transaction Relay API](../../tools/apis/relayer-api.md)
diff --git a/docs/evm/compare/erc1155-vs-lsp7-and-lsp8.mdx b/docs/evm/compare/erc1155-vs-lsp7-and-lsp8.mdx
@@ -0,0 +1,116 @@
+---
+title: 'ERC1155 vs LSP7 and LSP8 | Multi-Asset Migration on LUKSO'
+sidebar_label: ERC1155 vs LSP7/LSP8
+sidebar_position: 4
+description: Map ERC1155 fungible, semi-fungible, and NFT assets to LSP7 and LSP8 on LUKSO.
+keywords:
+  - ERC1155 vs LSP7
+  - ERC1155 vs LSP8
+  - ERC1155 migration LUKSO
+  - multi asset EVM standard
+---
+
+import StructuredData from '@site/src/components/StructuredData';
+
+<StructuredData
+  data={{
+    '@context': 'https://schema.org',
+    '@type': 'TechArticle',
+    headline: 'ERC1155 vs LSP7 and LSP8',
+    description:
+      'Decision guide for mapping ERC1155 multi-asset contracts to LUKSO LSP7 and LSP8 assets.',
+    author: { '@type': 'Organization', name: 'LUKSO' },
+    publisher: { '@type': 'Organization', name: 'LUKSO' },
+    about: ['ERC1155', 'LSP7', 'LSP8', 'Multi-asset migration', 'EVM'],
+    mainEntityOfPage:
+      'https://docs.lukso.tech/evm/compare/erc1155-vs-lsp7-and-lsp8/',
+    isAccessibleForFree: true,
+  }}
+/>
+
+# ERC1155 vs LSP7 and LSP8
+
+ERC1155 puts many asset IDs inside one contract. On LUKSO, the usual migration decision is whether each asset behaves more like an LSP7 amount-based asset or an LSP8 identifiable asset.
+
+## Direct answer
+
+Use **LSP7** when the ERC1155 ID represents a balance: points, credits, editions, tickets, memberships, or any asset where many users can hold an amount of the same thing. Use **LSP8** when the ERC1155 ID represents a unique object: one collectible, one credential, one character, one license, or one item that needs token-level metadata.
+
+The migration is not always "one ERC1155 contract becomes one LUKSO contract." The better model is usually "each asset type gets the LSP contract that matches its behavior."
+
+## Decision table
+
+| ERC1155 asset behavior | LUKSO fit | Why |
+| --- | --- | --- |
+| Many holders own divisible balances of the same ID. | [LSP7](../../standards/tokens/LSP7-Digital-Asset.md) | A balance is the core primitive. |
+| Many holders own whole-number editions of the same ID. | LSP7 with non-divisible units | Editions behave like amount-based assets even when decimals are disabled. |
+| Each ID is a unique item. | [LSP8](../../standards/tokens/LSP8-Identifiable-Digital-Asset.md) | The ID is the asset identity. |
+| Each ID needs its own metadata that changes independently. | LSP8 | LSP8 supports token-level ERC725Y data. |
+| One ERC1155 contract mixes balances and unique objects. | Split into LSP7 and LSP8 contracts | The contract topology should follow the product semantics. |
+| The product depends on batch transfer ergonomics. | LSP7/LSP8 batch methods or Universal Profile batch execution | Preserve UX with explicit LSP calls. |
+
+## What changes from ERC1155?
+
+ERC1155 makes contract consolidation the default. LSP7 and LSP8 make asset semantics explicit and add LUKSO-native metadata and receiver behavior. That usually improves discoverability for Universal Profiles, but it can require a clearer contract topology.
+
+| ERC1155 concept | LSP migration question |
+| --- | --- |
+| `id` | Is this a balance bucket or an identifiable token? |
+| `amount` | Does the product need decimals, whole editions, or exactly one owner per item? |
+| `uri(id)` | Should metadata be contract-level LSP4 data, token-level LSP8 data, or both? |
+| `safeTransferFrom` | Should recipients be required to support LSP1 receiver behavior, or should the transfer use `force`? |
+| `safeBatchTransferFrom` | Should batching happen on the asset contract or through Universal Profile `executeBatch`? |
+
+## Example inventory pass
+
+Before writing contracts, classify the legacy ERC1155 IDs by behavior. This avoids forcing every ID into the same LSP pattern.
+
+```ts
+type LegacyAsset = {
+  id: bigint;
+  symbol: string;
+  behavior: 'fungible' | 'edition' | 'unique';
+  needsTokenLevelMetadata: boolean;
+};
+
+const migrationPlan = legacyAssets.map((asset: LegacyAsset) => {
+  if (asset.behavior === 'unique' || asset.needsTokenLevelMetadata) {
+    return { id: asset.id, standard: 'LSP8' };
+  }
+
+  return { id: asset.id, standard: 'LSP7' };
+});
+```
+
+## What LSPs solve that ERC1155 leaves to apps
+
+- **Asset semantics:** LSP7 and LSP8 make the balance-vs-identity distinction explicit.
+- **Metadata:** LSP4 and ERC725Y let assets expose richer data than a single URI pattern.
+- **Token-level data:** LSP8 can store and retrieve data for a specific `bytes32` token ID.
+- **Receiver behavior:** LSP1-compatible recipients can react to incoming assets, reject them, register them, or forward them.
+- **Profile discovery:** Universal Profiles can maintain received-asset lists instead of relying only on off-chain indexer inference.
+
+## Migration checklist
+
+1. Inventory each ERC1155 token ID and classify it as fungible, semi-fungible, or unique.
+2. Choose LSP7 for amount-based assets and LSP8 for identifiable assets.
+3. Preserve legacy IDs in ERC725Y metadata when users or indexers need continuity.
+4. Recreate batch actions through Universal Profile batch execution or app-level transactions.
+5. Test incoming asset registration on Universal Profiles.
+6. Decide whether each transfer should require LSP1 recipient support or use `force`.
+7. Keep a public mapping from legacy ERC1155 IDs to new LSP contract addresses and token IDs.
+
+## Production pitfalls
+
+- Do not migrate every ERC1155 ID to LSP8 only because it has an ID. ERC1155 IDs often represent balance classes.
+- Do not collapse every asset into one LSP contract if discovery, metadata, ownership, or permissions need to differ.
+- Do not lose legacy ID continuity. Store old IDs in metadata or publish a migration map for wallets, marketplaces, and indexers.
+- Do not ignore recipient behavior. LSP7/LSP8 transfer flows can intentionally protect smart accounts from unwanted assets.
+
+## Implementation references
+
+- [Choose between LSP7 and LSP8](../../learn/digital-assets/choose-lsp7-vs-lsp8.md)
+- [LSP7 Digital Asset standard](../../standards/tokens/LSP7-Digital-Asset.md)
+- [LSP8 Identifiable Digital Asset standard](../../standards/tokens/LSP8-Identifiable-Digital-Asset.md)
+- [Transfer tokens and NFTs in batch](../../learn/digital-assets/transfer-batch.md)
+- [LUKSO Standards overview](../../standards/tokens/introduction.md)
diff --git a/docs/evm/compare/erc20-vs-lsp7.mdx b/docs/evm/compare/erc20-vs-lsp7.mdx
@@ -0,0 +1,122 @@
+---
+title: 'ERC20 vs LSP7 | How to Migrate Tokens to LUKSO'
+sidebar_label: ERC20 vs LSP7
+sidebar_position: 2
+description: Compare ERC20 and LSP7, understand transfer hooks and metadata differences, and migrate fungible token logic to LUKSO.
+keywords:
+  - ERC20 vs LSP7
+  - migrate ERC20 to LSP7
+  - LUKSO token standard
+  - EVM token migration
+---
+
+import StructuredData from '@site/src/components/StructuredData';
+
+<StructuredData
+  data={[
+    {
+      '@context': 'https://schema.org',
+      '@type': 'TechArticle',
+      headline: 'ERC20 vs LSP7',
+      description:
+        'Technical comparison of ERC20 and LSP7 for EVM developers migrating token logic to LUKSO.',
+      author: { '@type': 'Organization', name: 'LUKSO' },
+      publisher: {
+        '@type': 'Organization',
+        name: 'LUKSO',
+        logo: {
+          '@type': 'ImageObject',
+          url: 'https://docs.lukso.tech/img/logo.svg',
+        },
+      },
+      about: ['ERC20', 'LSP7', 'Digital Asset', 'Token migration', 'EVM'],
+      mainEntityOfPage:
+        'https://docs.lukso.tech/evm/compare/erc20-vs-lsp7/',
+      isAccessibleForFree: true,
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'BreadcrumbList',
+      itemListElement: [
+        {
+          '@type': 'ListItem',
+          position: 1,
+          name: 'EVM Builders',
+          item: 'https://docs.lukso.tech/evm/',
+        },
+        {
+          '@type': 'ListItem',
+          position: 2,
+          name: 'Compare',
+          item: 'https://docs.lukso.tech/evm/compare/',
+        },
+        {
+          '@type': 'ListItem',
+          position: 3,
+          name: 'ERC20 vs LSP7',
+          item: 'https://docs.lukso.tech/evm/compare/erc20-vs-lsp7/',
+        },
+      ],
+    },
+  ]}
+/>
+
+# ERC20 vs LSP7
+
+LSP7 is LUKSO's fungible and semi-fungible digital asset standard. It keeps the EVM mental model of balances and transfers, but adds metadata through ERC725Y, transfer notifications through LSP1, and a more explicit operator model.
+
+## Quick decision
+
+| Use ERC20 when | Use LSP7 when |
+| --- | --- |
+| You need maximum compatibility with existing ERC20-only DeFi contracts. | You want assets that work natively with Universal Profiles, metadata, and receiver hooks. |
+| Your token only needs `name`, `symbol`, `decimals`, balances, and allowances. | Your token needs richer metadata, token icons, notifications, or custom recipient behavior. |
+| You are deploying outside the LUKSO ecosystem and do not need LSP integrations. | You are building for LUKSO apps, profiles, creators, or social assets. |
+
+## What changes in code?
+
+```solidity title="ERC20 transferFrom"
+function transferFrom(
+  address from,
+  address to,
+  uint256 amount
+) external returns (bool);
+```
+
+```solidity title="LSP7 transfer"
+function transfer(
+  address from,
+  address to,
+  uint256 amount,
+  bool force,
+  bytes calldata data
+) external;
+```
+
+The two important additions are:
+
+- `force`: allows a sender to decide whether non-LSP1 recipients can receive the asset.
+- `data`: carries contextual transfer data to contracts that support LSP1 Universal Receiver hooks.
+
+## What changes in UX?
+
+LSP7 can notify Universal Profiles when tokens arrive, so profiles can maintain received-asset indexes and react to transfers. It can also store richer token metadata through ERC725Y data keys instead of relying only on fixed ERC20 metadata methods.
+
+That makes LSP7 more suitable for creator tokens, memberships, loyalty points, and profile-native social assets where discoverability and receiver behavior matter.
+
+## Migration checklist
+
+1. Replace ERC20 inheritance with [`LSP7DigitalAsset`](../../standards/tokens/LSP7-Digital-Asset.md).
+2. Decide whether the asset is divisible by setting the LSP7 divisibility option.
+3. Replace allowance flows with the LSP7 operator functions where appropriate.
+4. Update transfer calls to include `force` and `data`.
+5. Move token metadata into LSP4 / ERC725Y data keys.
+6. Add tests for transfers to EOAs, Universal Profiles, and contracts that do not implement LSP1.
+
+## Implementation references
+
+- [Full ERC20 to LSP7 migration guide](../migrate/erc20-to-lsp7.mdx)
+- [Existing ERC20 migration tutorial](../../learn/migrate/migrate-erc20-to-lsp7.md)
+- [LSP7 Digital Asset standard](../../standards/tokens/LSP7-Digital-Asset.md)
+- [Create an LSP7 token](../../learn/digital-assets/token/create-lsp7-token.md)
+- [LSP7 contract reference](../../contracts/contracts/LSP7DigitalAsset/LSP7DigitalAsset.md)