Skip to content

Commit

Permalink
feat: add general cross messages docs (#1252)
Browse files Browse the repository at this point in the history
  • Loading branch information
@karlem
karlem authored Jan 15, 2025
1 parent 967829f commit 18f32ca
Show file tree
Hide file tree
Showing 8 changed files with 280 additions and 126 deletions.
50 changes: 25 additions & 25 deletions contracts/.storage-layouts/GatewayActorModifiers.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -607,55 +607,55 @@
"type": "t_enum(IpcMsgKind)21376"
},
{
"astId": 21385,
"astId": 21384,
"contract": "contracts/lib/LibGatewayActorStorage.sol:GatewayActorModifiers",
"label": "to",
"offset": 0,
"slot": "1",
"type": "t_struct(IPCAddress)21658_storage"
"label": "localNonce",
"offset": 1,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21389,
"astId": 21387,
"contract": "contracts/lib/LibGatewayActorStorage.sol:GatewayActorModifiers",
"label": "from",
"offset": 0,
"slot": "5",
"type": "t_struct(IPCAddress)21658_storage"
"label": "originalNonce",
"offset": 9,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21392,
"astId": 21390,
"contract": "contracts/lib/LibGatewayActorStorage.sol:GatewayActorModifiers",
"label": "localNonce",
"label": "value",
"offset": 0,
"slot": "9",
"type": "t_uint64"
"slot": "1",
"type": "t_uint256"
},
{
"astId": 21395,
"astId": 21394,
"contract": "contracts/lib/LibGatewayActorStorage.sol:GatewayActorModifiers",
"label": "value",
"label": "to",
"offset": 0,
"slot": "10",
"type": "t_uint256"
"slot": "2",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21398,
"contract": "contracts/lib/LibGatewayActorStorage.sol:GatewayActorModifiers",
"label": "message",
"label": "from",
"offset": 0,
"slot": "11",
"type": "t_bytes_storage"
"slot": "6",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21401,
"contract": "contracts/lib/LibGatewayActorStorage.sol:GatewayActorModifiers",
"label": "originalNonce",
"label": "message",
"offset": 0,
"slot": "12",
"type": "t_uint64"
"slot": "10",
"type": "t_bytes_storage"
}
],
"numberOfBytes": "416"
"numberOfBytes": "352"
},
"t_struct(MaxPQ)19752_storage": {
"encoding": "inplace",
Expand Down
50 changes: 25 additions & 25 deletions contracts/.storage-layouts/GatewayDiamond.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -607,55 +607,55 @@
"type": "t_enum(IpcMsgKind)21376"
},
{
"astId": 21385,
"astId": 21384,
"contract": "contracts/GatewayDiamond.sol:GatewayDiamond",
"label": "to",
"offset": 0,
"slot": "1",
"type": "t_struct(IPCAddress)21658_storage"
"label": "localNonce",
"offset": 1,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21389,
"astId": 21387,
"contract": "contracts/GatewayDiamond.sol:GatewayDiamond",
"label": "from",
"offset": 0,
"slot": "5",
"type": "t_struct(IPCAddress)21658_storage"
"label": "originalNonce",
"offset": 9,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21392,
"astId": 21390,
"contract": "contracts/GatewayDiamond.sol:GatewayDiamond",
"label": "localNonce",
"label": "value",
"offset": 0,
"slot": "9",
"type": "t_uint64"
"slot": "1",
"type": "t_uint256"
},
{
"astId": 21395,
"astId": 21394,
"contract": "contracts/GatewayDiamond.sol:GatewayDiamond",
"label": "value",
"label": "to",
"offset": 0,
"slot": "10",
"type": "t_uint256"
"slot": "2",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21398,
"contract": "contracts/GatewayDiamond.sol:GatewayDiamond",
"label": "message",
"label": "from",
"offset": 0,
"slot": "11",
"type": "t_bytes_storage"
"slot": "6",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21401,
"contract": "contracts/GatewayDiamond.sol:GatewayDiamond",
"label": "originalNonce",
"label": "message",
"offset": 0,
"slot": "12",
"type": "t_uint64"
"slot": "10",
"type": "t_bytes_storage"
}
],
"numberOfBytes": "416"
"numberOfBytes": "352"
},
"t_struct(MaxPQ)19752_storage": {
"encoding": "inplace",
Expand Down
50 changes: 25 additions & 25 deletions contracts/.storage-layouts/SubnetActorDiamond.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -403,55 +403,55 @@
"type": "t_enum(IpcMsgKind)21376"
},
{
"astId": 21385,
"astId": 21384,
"contract": "contracts/SubnetActorDiamond.sol:SubnetActorDiamond",
"label": "to",
"offset": 0,
"slot": "1",
"type": "t_struct(IPCAddress)21658_storage"
"label": "localNonce",
"offset": 1,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21389,
"astId": 21387,
"contract": "contracts/SubnetActorDiamond.sol:SubnetActorDiamond",
"label": "from",
"offset": 0,
"slot": "5",
"type": "t_struct(IPCAddress)21658_storage"
"label": "originalNonce",
"offset": 9,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21392,
"astId": 21390,
"contract": "contracts/SubnetActorDiamond.sol:SubnetActorDiamond",
"label": "localNonce",
"label": "value",
"offset": 0,
"slot": "9",
"type": "t_uint64"
"slot": "1",
"type": "t_uint256"
},
{
"astId": 21395,
"astId": 21394,
"contract": "contracts/SubnetActorDiamond.sol:SubnetActorDiamond",
"label": "value",
"label": "to",
"offset": 0,
"slot": "10",
"type": "t_uint256"
"slot": "2",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21398,
"contract": "contracts/SubnetActorDiamond.sol:SubnetActorDiamond",
"label": "message",
"label": "from",
"offset": 0,
"slot": "11",
"type": "t_bytes_storage"
"slot": "6",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21401,
"contract": "contracts/SubnetActorDiamond.sol:SubnetActorDiamond",
"label": "originalNonce",
"label": "message",
"offset": 0,
"slot": "12",
"type": "t_uint64"
"slot": "10",
"type": "t_bytes_storage"
}
],
"numberOfBytes": "416"
"numberOfBytes": "352"
},
"t_struct(MaxPQ)19752_storage": {
"encoding": "inplace",
Expand Down
50 changes: 25 additions & 25 deletions contracts/.storage-layouts/SubnetActorModifiers.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -403,55 +403,55 @@
"type": "t_enum(IpcMsgKind)21376"
},
{
"astId": 21385,
"astId": 21384,
"contract": "contracts/lib/LibSubnetActorStorage.sol:SubnetActorModifiers",
"label": "to",
"offset": 0,
"slot": "1",
"type": "t_struct(IPCAddress)21658_storage"
"label": "localNonce",
"offset": 1,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21389,
"astId": 21387,
"contract": "contracts/lib/LibSubnetActorStorage.sol:SubnetActorModifiers",
"label": "from",
"offset": 0,
"slot": "5",
"type": "t_struct(IPCAddress)21658_storage"
"label": "originalNonce",
"offset": 9,
"slot": "0",
"type": "t_uint64"
},
{
"astId": 21392,
"astId": 21390,
"contract": "contracts/lib/LibSubnetActorStorage.sol:SubnetActorModifiers",
"label": "localNonce",
"label": "value",
"offset": 0,
"slot": "9",
"type": "t_uint64"
"slot": "1",
"type": "t_uint256"
},
{
"astId": 21395,
"astId": 21394,
"contract": "contracts/lib/LibSubnetActorStorage.sol:SubnetActorModifiers",
"label": "value",
"label": "to",
"offset": 0,
"slot": "10",
"type": "t_uint256"
"slot": "2",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21398,
"contract": "contracts/lib/LibSubnetActorStorage.sol:SubnetActorModifiers",
"label": "message",
"label": "from",
"offset": 0,
"slot": "11",
"type": "t_bytes_storage"
"slot": "6",
"type": "t_struct(IPCAddress)21658_storage"
},
{
"astId": 21401,
"contract": "contracts/lib/LibSubnetActorStorage.sol:SubnetActorModifiers",
"label": "originalNonce",
"label": "message",
"offset": 0,
"slot": "12",
"type": "t_uint64"
"slot": "10",
"type": "t_bytes_storage"
}
],
"numberOfBytes": "416"
"numberOfBytes": "352"
},
"t_struct(MaxPQ)19752_storage": {
"encoding": "inplace",
Expand Down
31 changes: 11 additions & 20 deletions contracts/contracts/structs/CrossNet.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,42 +58,33 @@ enum IpcMsgKind {
/// @dev general-purpose cross-net transaction that call smart contracts.
Call,
/// @dev receipt from the execution of cross-net messages
/// (currently limited to `Transfer` messages)
Result
}

/// @notice Envelope used to propagate IPC cross-net messages
struct IpcEnvelope {
/// @dev type of message being propagated.
IpcMsgKind kind;
/// @dev destination of the message
/// It makes sense to extract from the encoded message
/// all shared fields required by all message, so they
/// can be inspected without having to decode the message.
IPCAddress to;
/// @dev address sending the message
IPCAddress from;
/// @dev outgoing nonce for the envelope.
/// This nonce is set by the gateway when committing the message for propagation.
/// This nonce is changed on each network when the message is propagated,
/// so it is unique for each network and prevents replay attacks.
uint64 localNonce;
/// @dev Value being sent in the message.
/// For `Call` and `Result` kinds, the `value` field is synthetic and does not represent an actual token or native currency transfer.
/// Instead, it serves as metadata or an abstract representation of value to be interpreted by the target contract or receipt handler.
///
/// For example, in a `Call` message, `value` might represent the intended payment amount for a service in a cross-network dApp,
/// allowing the receiving contract to process it as part of its logic, regardless of the actual token transfer mechanics.
/// Similarly, in a `Result` message, `value` might represent the outcome of a transaction, such as the total tokens minted or refunded.
///
/// For `Transfer` messages, `value` represents the actual amount of native tokens being transferred across networks.
uint256 value;
/// @dev abi.encoded message
bytes message;
/// @dev original nonce of the message from the source network.
/// It is set once at the source network and remains unchanged during propagation.
/// It is used to generate a unique tracing ID across networks, which is useful for debugging and auditing purposes.
uint64 originalNonce;
/// @dev Value being sent in the message.
uint256 value;
/// @dev destination of the message
/// It makes sense to extract from the encoded message
/// all shared fields required by all message, so they
/// can be inspected without having to decode the message.
IPCAddress to;
/// @dev address sending the message
IPCAddress from;
/// @dev abi.encoded message
bytes message;
/// @dev the gas limit is currently not used.
// FIXME: currently not used.
// uint256 gasLimit;
Expand Down
Loading

0 comments on commit 18f32ca

Please sign in to comment.