Skip to content

Commit d97ce12

Browse files
nhussein11nhussein11
committed
fix: llms
1 parent 9c30912 commit d97ce12

File tree

12 files changed

+615
-126
lines changed

12 files changed

+615
-126
lines changed

‎.ai/categories/basics.md‎

Lines changed: 65 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,26 @@ Begin New Bundle: Basics
33

44
---
55

6-
Page Title: Accounts in Asset Hub Smart Contracts
6+
Page Title: Accounts in Polkadot Hub Smart Contracts
77

88
- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-for-eth-devs-accounts.md
99
- Canonical (HTML): https://docs.polkadot.com/smart-contracts/for-eth-devs/accounts/
1010
- Summary: Bridges Ethereum's 20-byte addresses with Polkadot's 32-byte accounts, enabling seamless interaction while maintaining compatibility with Ethereum tooling.
1111

12-
# Accounts on Asset Hub Smart Contracts
12+
# Accounts on the Polkadot Hub Smart Contracts
1313

1414
## Introduction
1515

16-
Asset Hub natively utilizes Polkadot's 32-byte account system while providing interoperability with Ethereum's 20-byte addresses through an automatic conversion system. When interacting with smart contracts:
16+
The Polkadot Hub natively utilizes Polkadot's 32-byte account system while providing interoperability with Ethereum's 20-byte addresses through an automatic conversion system. When interacting with smart contracts:
1717

1818
- Ethereum-compatible wallets (like MetaMask) can use their familiar 20-byte addresses.
1919
- Polkadot accounts continue using their native 32-byte format.
20-
- The Asset Hub chain automatically handles conversion between the two formats behind the scenes:
20+
- The Polkadot Hub chain automatically handles conversion between the two formats behind the scenes:
2121

2222
- 20-byte Ethereum addresses are padded with `0xEE` bytes to create valid 32-byte Polkadot accounts.
2323
- 32-byte Polkadot accounts can optionally register a mapping to a 20-byte address for Ethereum compatibility.
2424

25-
This dual-format approach enables Asset Hub to maintain compatibility with Ethereum tooling while fully integrating with the Polkadot ecosystem.
25+
This dual-format approach enables the Polkadot Hub to maintain compatibility with Ethereum tooling while fully integrating with the Polkadot ecosystem.
2626

2727
## Address Types and Mappings
2828

@@ -59,20 +59,57 @@ The conversion process is implemented through the [`to_address`](https://parityt
5959
**Stateful Mapping for Reversibility** : Since the conversion from 32-byte to 20-byte addresses is inherently lossy, the system provides an optional stateful mapping through the [`OriginalAccount`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/pallet/storage_types/struct.OriginalAccount.html){target=\_blank} storage. When a Polkadot account registers a mapping (via the [`map`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/trait.AddressMapper.html#tymethod.map){target=\_blank} function), the system stores the original 32-byte account ID, enabling the [`to_account_id`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/trait.AddressMapper.html#tymethod.to_account_id){target=\_blank} function to recover the exact original account rather than falling back to a default conversion.
6060

6161

62+
### Interacting with Unmapped Substrate Accounts
63+
64+
Native Polkadot accounts (32-byte format) that haven't been explicitly mapped have limited interaction capabilities with the Ethereum-compatible smart contract layer. Understanding these limitations and when mapping is required is essential for developers working with the Polkadot Hub.
65+
66+
#### Limitations of Unmapped Accounts
67+
68+
Unmapped Substrate accounts (those created with Ed25519 or Sr25519 keypairs) face the following restrictions:
69+
70+
- **Cannot initiate transactions** through Ethereum-compatible interfaces (like MetaMask or other EVM-compatible wallets)
71+
- **Cannot directly call smart contracts** using Ethereum RPC methods
72+
- **Cannot transfer funds** to or from 20-byte Ethereum-compatible addresses without proper mapping
73+
- **Limited interoperability** with Ethereum tooling and existing EVM infrastructure
74+
75+
The system can *receive* funds at the hashed 20-byte address derived from the 32-byte account, but the original account owner cannot control or access those funds through Ethereum-compatible methods without first establishing a proper mapping.
76+
77+
#### When Mapping is Required
78+
79+
Account mapping is **required** when:
80+
81+
1. You want to interact with smart contracts using Ethereum-compatible tools (MetaMask, Web3.js, Ethers.js)
82+
2. You need to transfer funds using 20-byte address format
83+
3. You want your existing Polkadot account to be accessible through EVM-compatible interfaces
84+
4. You need bidirectional compatibility between Polkadot and Ethereum address formats
85+
86+
Account mapping is **not required** when:
87+
88+
- Using native Polkadot addresses (32-byte) exclusively with Substrate-native interfaces
89+
- Interacting with parachains that don't use the Ethereum-compatible layer
90+
- Using accounts that were originally created with secp256k1 keys (Ethereum-compatible from the start)
91+
6292
### Account Mapping for Native Polkadot Accounts
6393

6494
If you have a native Polkadot account (32-byte format) that was created with a Polkadot/Substrate keypair (Ed25519/Sr25519) rather than an Ethereum-compatible keypair (secp256k1), you'll need to map your account to enable Ethereum compatibility.
6595

6696
To map your account, call the [`map_account`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/pallet/dispatchables/fn.map_account.html){target=\_blank} extrinsic of the [`pallet_revive`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/index.html){target=\_blank} pallet using your original Substrate account. This creates a stateful mapping that allows your 32-byte account to interact with the Ethereum-compatible smart contract system.
6797

98+
**Mapping Process:**
99+
100+
1. **Call the extrinsic**: Use your Substrate wallet to call `pallet_revive.map_account()`
101+
2. **Pay the deposit**: A deposit is required and held while the mapping exists (refundable upon unmapping)
102+
3. **Receive confirmation**: Once mapped, your account can be used with both Polkadot and Ethereum interfaces
103+
68104
Once mapped, you'll be able to:
69105

70-
- Transfer funds between 20-byte format addresses.
71-
- Interact with smart contracts using Ethereum-compatible tools like MetaMask.
72-
- Maintain full reversibility to your original 32-byte account format.
106+
- Transfer funds between 20-byte format addresses
107+
- Interact with smart contracts using Ethereum-compatible tools like MetaMask
108+
- Maintain full reversibility to your original 32-byte account format
109+
- Access funds at both your 32-byte Polkadot address and the mapped 20-byte Ethereum address
73110

74111
!!! warning "Mapping Requirement"
75-
Without this mapping, native Polkadot accounts cannot transfer funds or interact with the Ethereum-compatible layer on the Hub.
112+
Without this mapping, native Polkadot accounts cannot transfer funds or interact with the Ethereum-compatible layer on the Hub. Attempting to send funds to an unmapped account's hashed Ethereum address may result in funds being inaccessible through standard Ethereum tools.
76113

77114
## Account Registration
78115

@@ -87,9 +124,25 @@ The registration process is implemented through the [`map`](https://paritytech.g
87124

88125
The fallback mechanism is integrated into the [`to_account_id`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/trait.AddressMapper.html#tymethod.to_account_id){target=\_blank} function. It provides a safety net for address conversion by:
89126

90-
- First, attempting to retrieve stored mapping data.
91-
- Falling back to the default conversion method if no mapping exists.
92-
- Maintaining consistency in address representation.
127+
- First, attempting to retrieve stored mapping data from [`OriginalAccount`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/pallet/storage_types/struct.OriginalAccount.html){target=\_blank} storage
128+
- Falling back to the default conversion method (Keccak-256 hash) if no explicit mapping exists
129+
- Maintaining consistency in address representation across the system
130+
131+
### How Fallback Works with Unmapped Accounts
132+
133+
When an unmapped 32-byte Polkadot account needs to be represented as a 20-byte Ethereum address, the system:
134+
135+
1. **Checks for explicit mapping**: First looks in the `OriginalAccount` storage to see if the account has been explicitly mapped via `map_account`
136+
2. **Applies fallback conversion**: If no mapping exists, automatically converts the 32-byte account to a 20-byte address by:
137+
- Hashing the full 32-byte account with Keccak-256
138+
- Taking the last 20 bytes of the resulting hash
139+
3. **Uses the derived address**: This fallback address can receive funds, but the account owner cannot spend those funds through Ethereum-compatible interfaces without explicit mapping
140+
141+
**Important Considerations:**
142+
143+
- The fallback mechanism is **one-way for unmapped accounts** - while you can derive the 20-byte address from a 32-byte account, you cannot recover the original 32-byte account from the 20-byte hash without the stored mapping
144+
- Funds sent to a fallback address of an unmapped account are not lost, but require explicit mapping to be accessible through Ethereum tools
145+
- For security and usability, it's recommended to establish explicit mappings rather than relying on fallback addresses for accounts that need Ethereum compatibility
93146

94147
## Contract Address Generation
95148

‎.ai/categories/dapps.md‎

Lines changed: 65 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,26 @@ Includes shared base categories: Basics, Reference
44

55
---
66

7-
Page Title: Accounts in Asset Hub Smart Contracts
7+
Page Title: Accounts in Polkadot Hub Smart Contracts
88

99
- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-for-eth-devs-accounts.md
1010
- Canonical (HTML): https://docs.polkadot.com/smart-contracts/for-eth-devs/accounts/
1111
- Summary: Bridges Ethereum's 20-byte addresses with Polkadot's 32-byte accounts, enabling seamless interaction while maintaining compatibility with Ethereum tooling.
1212

13-
# Accounts on Asset Hub Smart Contracts
13+
# Accounts on the Polkadot Hub Smart Contracts
1414

1515
## Introduction
1616

17-
Asset Hub natively utilizes Polkadot's 32-byte account system while providing interoperability with Ethereum's 20-byte addresses through an automatic conversion system. When interacting with smart contracts:
17+
The Polkadot Hub natively utilizes Polkadot's 32-byte account system while providing interoperability with Ethereum's 20-byte addresses through an automatic conversion system. When interacting with smart contracts:
1818

1919
- Ethereum-compatible wallets (like MetaMask) can use their familiar 20-byte addresses.
2020
- Polkadot accounts continue using their native 32-byte format.
21-
- The Asset Hub chain automatically handles conversion between the two formats behind the scenes:
21+
- The Polkadot Hub chain automatically handles conversion between the two formats behind the scenes:
2222

2323
- 20-byte Ethereum addresses are padded with `0xEE` bytes to create valid 32-byte Polkadot accounts.
2424
- 32-byte Polkadot accounts can optionally register a mapping to a 20-byte address for Ethereum compatibility.
2525

26-
This dual-format approach enables Asset Hub to maintain compatibility with Ethereum tooling while fully integrating with the Polkadot ecosystem.
26+
This dual-format approach enables the Polkadot Hub to maintain compatibility with Ethereum tooling while fully integrating with the Polkadot ecosystem.
2727

2828
## Address Types and Mappings
2929

@@ -60,20 +60,57 @@ The conversion process is implemented through the [`to_address`](https://parityt
6060
**Stateful Mapping for Reversibility** : Since the conversion from 32-byte to 20-byte addresses is inherently lossy, the system provides an optional stateful mapping through the [`OriginalAccount`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/pallet/storage_types/struct.OriginalAccount.html){target=\_blank} storage. When a Polkadot account registers a mapping (via the [`map`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/trait.AddressMapper.html#tymethod.map){target=\_blank} function), the system stores the original 32-byte account ID, enabling the [`to_account_id`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/trait.AddressMapper.html#tymethod.to_account_id){target=\_blank} function to recover the exact original account rather than falling back to a default conversion.
6161

6262

63+
### Interacting with Unmapped Substrate Accounts
64+
65+
Native Polkadot accounts (32-byte format) that haven't been explicitly mapped have limited interaction capabilities with the Ethereum-compatible smart contract layer. Understanding these limitations and when mapping is required is essential for developers working with the Polkadot Hub.
66+
67+
#### Limitations of Unmapped Accounts
68+
69+
Unmapped Substrate accounts (those created with Ed25519 or Sr25519 keypairs) face the following restrictions:
70+
71+
- **Cannot initiate transactions** through Ethereum-compatible interfaces (like MetaMask or other EVM-compatible wallets)
72+
- **Cannot directly call smart contracts** using Ethereum RPC methods
73+
- **Cannot transfer funds** to or from 20-byte Ethereum-compatible addresses without proper mapping
74+
- **Limited interoperability** with Ethereum tooling and existing EVM infrastructure
75+
76+
The system can *receive* funds at the hashed 20-byte address derived from the 32-byte account, but the original account owner cannot control or access those funds through Ethereum-compatible methods without first establishing a proper mapping.
77+
78+
#### When Mapping is Required
79+
80+
Account mapping is **required** when:
81+
82+
1. You want to interact with smart contracts using Ethereum-compatible tools (MetaMask, Web3.js, Ethers.js)
83+
2. You need to transfer funds using 20-byte address format
84+
3. You want your existing Polkadot account to be accessible through EVM-compatible interfaces
85+
4. You need bidirectional compatibility between Polkadot and Ethereum address formats
86+
87+
Account mapping is **not required** when:
88+
89+
- Using native Polkadot addresses (32-byte) exclusively with Substrate-native interfaces
90+
- Interacting with parachains that don't use the Ethereum-compatible layer
91+
- Using accounts that were originally created with secp256k1 keys (Ethereum-compatible from the start)
92+
6393
### Account Mapping for Native Polkadot Accounts
6494

6595
If you have a native Polkadot account (32-byte format) that was created with a Polkadot/Substrate keypair (Ed25519/Sr25519) rather than an Ethereum-compatible keypair (secp256k1), you'll need to map your account to enable Ethereum compatibility.
6696

6797
To map your account, call the [`map_account`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/pallet/dispatchables/fn.map_account.html){target=\_blank} extrinsic of the [`pallet_revive`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/index.html){target=\_blank} pallet using your original Substrate account. This creates a stateful mapping that allows your 32-byte account to interact with the Ethereum-compatible smart contract system.
6898

99+
**Mapping Process:**
100+
101+
1. **Call the extrinsic**: Use your Substrate wallet to call `pallet_revive.map_account()`
102+
2. **Pay the deposit**: A deposit is required and held while the mapping exists (refundable upon unmapping)
103+
3. **Receive confirmation**: Once mapped, your account can be used with both Polkadot and Ethereum interfaces
104+
69105
Once mapped, you'll be able to:
70106

71-
- Transfer funds between 20-byte format addresses.
72-
- Interact with smart contracts using Ethereum-compatible tools like MetaMask.
73-
- Maintain full reversibility to your original 32-byte account format.
107+
- Transfer funds between 20-byte format addresses
108+
- Interact with smart contracts using Ethereum-compatible tools like MetaMask
109+
- Maintain full reversibility to your original 32-byte account format
110+
- Access funds at both your 32-byte Polkadot address and the mapped 20-byte Ethereum address
74111

75112
!!! warning "Mapping Requirement"
76-
Without this mapping, native Polkadot accounts cannot transfer funds or interact with the Ethereum-compatible layer on the Hub.
113+
Without this mapping, native Polkadot accounts cannot transfer funds or interact with the Ethereum-compatible layer on the Hub. Attempting to send funds to an unmapped account's hashed Ethereum address may result in funds being inaccessible through standard Ethereum tools.
77114

78115
## Account Registration
79116

@@ -88,9 +125,25 @@ The registration process is implemented through the [`map`](https://paritytech.g
88125

89126
The fallback mechanism is integrated into the [`to_account_id`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/trait.AddressMapper.html#tymethod.to_account_id){target=\_blank} function. It provides a safety net for address conversion by:
90127

91-
- First, attempting to retrieve stored mapping data.
92-
- Falling back to the default conversion method if no mapping exists.
93-
- Maintaining consistency in address representation.
128+
- First, attempting to retrieve stored mapping data from [`OriginalAccount`](https://paritytech.github.io/polkadot-sdk/master/pallet_revive/pallet/storage_types/struct.OriginalAccount.html){target=\_blank} storage
129+
- Falling back to the default conversion method (Keccak-256 hash) if no explicit mapping exists
130+
- Maintaining consistency in address representation across the system
131+
132+
### How Fallback Works with Unmapped Accounts
133+
134+
When an unmapped 32-byte Polkadot account needs to be represented as a 20-byte Ethereum address, the system:
135+
136+
1. **Checks for explicit mapping**: First looks in the `OriginalAccount` storage to see if the account has been explicitly mapped via `map_account`
137+
2. **Applies fallback conversion**: If no mapping exists, automatically converts the 32-byte account to a 20-byte address by:
138+
- Hashing the full 32-byte account with Keccak-256
139+
- Taking the last 20 bytes of the resulting hash
140+
3. **Uses the derived address**: This fallback address can receive funds, but the account owner cannot spend those funds through Ethereum-compatible interfaces without explicit mapping
141+
142+
**Important Considerations:**
143+
144+
- The fallback mechanism is **one-way for unmapped accounts** - while you can derive the 20-byte address from a 32-byte account, you cannot recover the original 32-byte account from the 20-byte hash without the stored mapping
145+
- Funds sent to a fallback address of an unmapped account are not lost, but require explicit mapping to be accessible through Ethereum tools
146+
- For security and usability, it's recommended to establish explicit mappings rather than relying on fallback addresses for accounts that need Ethereum compatibility
94147

95148
## Contract Address Generation
96149

0 commit comments

Comments
 (0)