From 504d8c494fc0c963d6256244b9b3f46d61eeae07 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 8 Dec 2022 23:34:06 +0100 Subject: [PATCH 1/3] editorial pass Signed-off-by: bumblefudge --- eip155/caip168.md | 89 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 21 deletions(-) diff --git a/eip155/caip168.md b/eip155/caip168.md index 0ac25ef1..5681edef 100644 --- a/eip155/caip168.md +++ b/eip155/caip168.md @@ -12,19 +12,28 @@ requires: ["CAIP-168"] ## CAIP-168 -For context, see the [CAIP-168 IPLD Timestamp Proof]() specification. +For context, see the [CAIP-168][] IPLD Timestamp Proof specification. ## Rationale -[CAIP-168 IPLD Timestamp Proof]() specification describes the general construction and verification of IPLD based blockchain timestamp proofs. Transaction verification for these IPLD timestamp proofs are independent to the chain they are published on and the `txType` parameter allows multiple verification methods per blockchain to be supported. This specification describes transaction verification for the `eip-155` namespace. +[CAIP-168][] IPLD Timestamp Proof specification describes the general +construction and verification of IPLD based blockchain timestamp proofs. +Transaction verification for these IPLD timestamp proofs are independent of the +chain on which they are published and the `txType` parameter allows multiple +verification methods per namespace to be supported. This specification +describes transaction verification for the `eip-155` namespace. ## Specification ### `raw` Transaction Type Verification -This section describes transaction verification when a timestamp anchor proof references a `chainId` in the `eip155` namespace and `txType` is `raw`. Type `raw` refers to the simplest transaction type where a merkle root CID is simply encoded into the data payload of a transaction. +This section describes transaction verification when a timestamp anchor proof +references a `chainId` in the `eip155` namespace and `txType` is `raw`. Type +`raw` refers to the simplest transaction type where a merkle root CID is simply +encoded into the data payload of a transaction. + +#### Example anchor proof -Example 1 ```tsx { root: CID(bafyreiaxdhr5jbabn7enmbb5wpmnm3dwpncbqjcnoneoj22f3sii5vfg74) @@ -34,19 +43,36 @@ Example 1 } ``` -**Verification Steps** +#### Verification Steps -1) Resolve blockchain transaction payload by `txHash` CID and `chainId`. CID is expected to be DAG-ETH encoded block. -2) Get the `data` paramater of the transaction payload, it is expected to be a hex encoded CID. The data value is a byte friendly string and may be prepended with a '0' for a resulting even length hex string. -3) Verify that the `root` CID of the timestamp anchor proof is equivalent to the `transaction.data` CID. Equivalence should be checked using a CIDs library, rather than string equivalence, as the CIDs may be encoded in different bases. If they are not equivalent, an error MUST be raised. -4) Determine that the transaction has been included in a valid block on the blockchain referenced by the `chainId`. Number of block confirmations for acceptance is up to an implementation. +1) Resolve blockchain transaction payload by `txHash` CID and `chainId`. CID is + expected to be a [DAG-ETH][]-encoded block, and `chainId` MUST be a valid + [CAIP-2][] identifier. +2) Get the `data` paramater of the transaction payload, it is expected to be a + hex-encoded CID. The data value is a byte-friendly string, and if its length + is odd, a single '0' may be prepended to make its length even. +3) Verify that the `root` CID of the timestamp anchor proof is equivalent to the + `transaction.data` CID. Note: as the CIDs MAY be encoded in different bases, + their equivalence should be checked using a CID parsing library, rather than + simple string equivalence. If they are not equivalent, verification MUST fail. +4) Determine that the transaction has been included in a valid block on the + blockchain referenced by the `chainId`. Number of block confirmations for + acceptance is up to an implementation. ### `f(bytes32)` Transaction Type Verification -This section describes transaction verification when a timestamp anchor proof references a `chainId` in the `eip155` namespace and `txType` is `f(bytes32)`. Type `f(bytes32)` refers to a transaction which makes a function call on a contract with the function signature including a single 32 bytes argument. The 32 byte argument is the merkle root CID. A CID is more than bytes32, and a partial CID is used to allow the argument to be efficiently packed in the transaction. Function name or contract does not matter, and is up to an implementation. +This section describes transaction verification when a timestamp anchor proof +references a `chainId` in the `eip155` namespace and `txType` is `f(bytes32)`. +Type `f(bytes32)` refers to a transaction which makes a function call on a +contract with the function signature including a single 32 bytes argument. The +32 byte argument is the merkle-root CID. A CID is more than 32 bytes, and a +partial CID is used to allow the argument to be efficiently packed in the +transaction. Function name or contract does not matter, and is up to the +implementation. Use of a root CID encoded in [DAG-CBOR][] is recommended. + +#### Example anchor proof -Example 2 ```tsx { root: CID(bafyreiaxdhr5jbabn7enmbb5wpmnm3dwpncbqjcnoneoj22f3sii5vfg74) @@ -55,17 +81,38 @@ Example 2 txType: 'f(bytes32)' } ``` -**Verification Steps** - -1) Resolve blockchain transaction payload by `txHash` CID and `chainId`. CID is expected to be dag-eth encoded block. -2) Get the `data` paramater of the transaction payload, it is expected to be a hex encoded 64 byte string. -3) The first 4 bytes are the function signature and can be discarded, the next 32 bytes is the first argument of the function, which is expected to be a 32 byte hex encoded partial CID. -4) The partial CID is the multihash portion of the original CID. It does not include the multibase, the CID version or the IPLD codec. It is assumed that the IPLD codec is dag-cbor. Verify that the `root` CID of the timestamp anchor proof is equivalent to the transaction partial CID. Equivalence should be checked using a CIDs library, multihash portions encoded in bytes can be compared. If they are not equivalent, an error MUST be raised. -5) Determine that the transaction has been included in a valid block on the blockchain referenced by the `chainId`. Number of block confirmations for acceptance is up to an implementation. +#### Verification Steps + +1) Resolve blockchain transaction payload by `txHash` CID and `chainId`. CID is + expected to be [DAG-ETH][]-encoded block, and `chainId` MUST be a valid + [CAIP-2][] identifier. +2) Get the `data` paramater of the transaction payload, it is expected to be a + hex encoded 64 byte string. +3) The first 4 bytes are the function signature and can be discarded, the next + 32 bytes is the first argument of the function, which is expected to be a 32 + byte hex encoded partial CID. +4) The partial CID is the **multihash portion** of the original CIDv1 (refer the + section [How does it + work?](https://github.com/multiformats/cid#how-does-it-work) in the + [Multiformats CID][] specification for context). It does not include the + multibase, the CID version or the IPLD codec segments. It is assumed that the + IPLD codec is dag-cbor. Verify that the first 32bytes of the `root` CID of + the timestamp anchor proof is equivalent to the 32-byte partial CID extracted + from the transaction data. Equivalence should be checked using a CIDs + library, which can compare oprtions of multihashes encoded in bytes. If the two partial multihashes are not equivalent, verification MUST fail. +5) Determine that the transaction has been included in a valid block on the + blockchain referenced by the `chainId`. Number of block confirmations for + acceptance is up to an implementation. ## References -- [CAIP-168](CAIP-168): IPLD Timestamp Proof -- [Multiformats CID](https://github.com/multiformats/cid) -- [DAG-ETH](https://ipld.io/specs/codecs/dag-eth/) \ No newline at end of file +- [CAIP-168][]: IPLD Timestamp Proof +- [Multiformats CID][] Specification +- [DAG-ETH][] Codec Specification at IPLD.io +- [DAG-CBOR][] Codec Specification on Github + +[CAIP-168]: https://chainagnostic.org/CAIPs/CAIP-168 +[DAG-ETH]: https://ipld.io/specs/codecs/dag-eth/ +[DAG-CBOR]: https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-cbor.md +[Multiformats CID]: https://github.com/multiformats/cid \ No newline at end of file From fde6eb4a35e683ea8460763a7421ec685cc609bd Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 8 Dec 2022 23:38:07 +0100 Subject: [PATCH 2/3] typo Signed-off-by: bumblefudge --- eip155/caip168.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/eip155/caip168.md b/eip155/caip168.md index 5681edef..ae41a467 100644 --- a/eip155/caip168.md +++ b/eip155/caip168.md @@ -100,7 +100,8 @@ implementation. Use of a root CID encoded in [DAG-CBOR][] is recommended. IPLD codec is dag-cbor. Verify that the first 32bytes of the `root` CID of the timestamp anchor proof is equivalent to the 32-byte partial CID extracted from the transaction data. Equivalence should be checked using a CIDs - library, which can compare oprtions of multihashes encoded in bytes. If the two partial multihashes are not equivalent, verification MUST fail. + library, which can compare oprtions of multihashes encoded in bytes. If the + two partial multihashes are not equivalent, verification MUST fail. 5) Determine that the transaction has been included in a valid block on the blockchain referenced by the `chainId`. Number of block confirmations for acceptance is up to an implementation. From 2d2584899f197a03bdae4583cbec8748992ee3f6 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Wed, 14 Dec 2022 08:49:53 -0800 Subject: [PATCH 3/3] Update eip155/caip168.md Co-authored-by: Zach Ferland --- eip155/caip168.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/eip155/caip168.md b/eip155/caip168.md index ae41a467..72e670b5 100644 --- a/eip155/caip168.md +++ b/eip155/caip168.md @@ -97,11 +97,11 @@ implementation. Use of a root CID encoded in [DAG-CBOR][] is recommended. work?](https://github.com/multiformats/cid#how-does-it-work) in the [Multiformats CID][] specification for context). It does not include the multibase, the CID version or the IPLD codec segments. It is assumed that the - IPLD codec is dag-cbor. Verify that the first 32bytes of the `root` CID of - the timestamp anchor proof is equivalent to the 32-byte partial CID extracted + IPLD codec is dag-cbor. Verify that the multihash portion of the `root` CID of + the timestamp proof is equivalent to the multihash extracted from the transaction data. Equivalence should be checked using a CIDs - library, which can compare oprtions of multihashes encoded in bytes. If the - two partial multihashes are not equivalent, verification MUST fail. + library, which can compare multihash portions encoded in bytes. If the + two multihashes are not equivalent, verification MUST fail. 5) Determine that the transaction has been included in a valid block on the blockchain referenced by the `chainId`. Number of block confirmations for acceptance is up to an implementation.