feat: buckets wrapper #26

dtbuchholz · 2024-10-23T21:21:15Z

Summary

Buckets wrapper with read-only calls (list buckets or objects) and bucket creation. ~~Part of #22, but the remaining object-related commands (add, get, delete) will come in a separate PR since this is a bit more involved with offchain processing.~~ Edit: Accompanying PR for object-related add/delete/remove: #27. Closes #22.

Details

Adds new LibBucket.sol library and BucketManager.sol wrapper, similar to how Credit.sol and LibCredit.sol work.
- The rationale on naming convention: we can split out some of the LibBucket.sol logic into LibMachine.sol (or something representing the ADM actor), which handles the CREATE_EXTERNAL calls. Then, we could maybe have a factory pattern where a new Bucket.sol is created, which stores some internal state and uses LibBucket.sol calls for object-related activities. Although, idk if this is necessary with the (eventual) t2<>0x mapping feature.
Adds utils for base32 encoding and Blake2 hashing.
- Ideally, these are handled offchain. Particularly, the Blake2 impl, which is very costly but was needed to decode a t2 address to a string. However, these were required to allow for the Studio to launch.
Fixed linting issues wrt errors—i.e., we use explicitly errors over require(...) where necessary.
Unified the SPDX license (MIT or Apache) and solc version (^0.8.26) so all contracts match.
Docs cleanups and additions for the Bucket Manager.

Testing

See the README for integration tests; all of the bucket methods are shown with cast. Unit tests are also added, albeit, likely not fully comprehensive.

dtbuchholz · 2024-10-23T21:21:44Z

LICENSE

@@ -1,4 +1,6 @@
-The MIT License (MIT)
+MIT License


i just wanted to use the same licenses from rust-hoku

dtbuchholz · 2024-10-23T21:22:36Z

src/BucketManager.sol

+
+/// @title Bucket Manager Contract
+/// @dev Implementation of the Hoku Bucket actor EVM interface. See {IBucketManager} for details.
+contract BucketManager is IBucketManager {


bucket manager, wrapping all LibBucket.sol methods with overloads

dtbuchholz · 2024-10-23T21:23:12Z

src/errors/WasmErrors.sol

+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity ^0.8.26;
+
+error InvalidValue(string);


for simplicity, these also get used by LibCredit and LibBucket since they only come up a couple of times.

dtbuchholz · 2024-10-23T21:24:46Z

src/interfaces/IBucketManager.sol

+/// https://github.com/hokunet/ipc/blob/develop/fendermint/actors/objectstore/src/actor.rs
+interface IBucketManager {
+    /// @dev Emitted when a bucket is created.
+    // TODO: It'd be nice to emit the bucket t2 address, but decoding the CBOR is too expensive.


the Blake2 hashing (below) allows us to parse raw bytes into a t2 address. however, it's very expensive and not worth paying for that execution in a mutating tx. with the 0x<>t2 mapping, this should emit the 0x address and eventually be possible.

nice, makes sense.

dtbuchholz · 2024-10-23T21:26:33Z

src/types/CommonTypes.sol

@@ -12,3 +12,9 @@ enum Environment {
    Mainnet,
    Foundry
 }
+
+/// @dev A key-value pair.
+struct KeyValue {


figured this would be a common type since it could be eventually used in other places, besides for object or machine metadata

dtbuchholz · 2024-10-23T21:27:01Z

src/util/Base32.sol

+pragma solidity ^0.8.26;
+
+/// @dev Base32 encoding and decoding library.
+library Base32 {


praise Claude + Cursor for the assembly, cutting costs by 50%+

dtbuchholz · 2024-10-23T21:29:39Z

src/util/Blake2b.sol

+/// @dev Implementation of the BLAKE2b hashing algorithm.
+/// See Rust implementation: https://github.com/oconnor663/blake2_simd/blob/master/blake2b/src/lib.rs
+/// TODO: this is very costly and must be optimized, handled by WASM, or fully offchain.
+library Blake2b {


also praise Claude + Cursor for figuring this out. again, ideally not something we do in contracts, but at least it works.

once we have t2<>0x mapping, we don't necessarily need this. but, i wonder if there's some advantage in creating a "utils" Wasm actor that exposes these types of operations? i.e., things that are useful in a Solidity contract, but much more efficient if we called a Wasm actor to do it for us.

good idea. worth considering if something else comes up.

wild stuff here 💪

dtbuchholz · 2024-10-23T21:31:35Z

src/util/LibBucket.sol

+    using LibWasm for *;
+
+    // Constants for the actor and method IDs of the Hoku ADM actor
+    uint64 internal constant ADM_ACTOR_ID = 17;


these constants and logic in create below could be split into some LibMachine.sol contract, which will let us interface the ADM actor and create the Timehub or other contracts. for now, I figured we could keep it simple and do that once the feature is needed.

dtbuchholz · 2024-10-23T21:34:33Z

src/util/LibWasm.sol

+    function decodeCborActorAddress(bytes memory encoded) internal pure returns (string memory) {
+        if (encoded.length != 21 || encoded[0] != 0x02) revert InvalidValue("Invalid address length or protocol");
+
+        bytes memory checksum = Blake2b.hash(encoded, 4);


the only reason why Blake2 is needed, and main reason why base32 is needed too

dtbuchholz · 2024-10-23T21:38:53Z

README.md

@@ -56,67 +85,22 @@ forge install
 forge build
 ```

-## Clean


some legacy readme stuff got merged back into main...cleaned these up into the sections

dtbuchholz · 2024-10-23T21:39:22Z

README.md

+
+Creating a bucket will cost native HOKU tokens, and writing to it will cost credit.
+
+##### List buckets


"integration" tests

dtbuchholz · 2024-10-23T23:48:10Z

src/util/solidity-cbor/ByteParser.sol

-//SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity ^0.8.26;


figured i'd just include the "hidden" linting errors showing up in the PR wrt solidity-cbor files...and just update these to use the same license/solc as everything else too

dtbuchholz · 2024-10-24T16:42:03Z

i ended up figuring out the remaining bucket methods. I have it over on this branch but feel free to merge it into here, if that's easier for a review #27

sanderpick

Awesome work @dtbuchholz. Exciting to see this stuff working!

sanderpick · 2024-10-24T23:57:37Z

src/interfaces/IBucketManager.sol

+/// https://github.com/hokunet/ipc/blob/develop/fendermint/actors/objectstore/src/actor.rs
+interface IBucketManager {
+    /// @dev Emitted when a bucket is created.
+    // TODO: It'd be nice to emit the bucket t2 address, but decoding the CBOR is too expensive.


nice, makes sense.

sanderpick · 2024-10-24T23:59:24Z

src/util/Blake2b.sol

+/// @dev Implementation of the BLAKE2b hashing algorithm.
+/// See Rust implementation: https://github.com/oconnor663/blake2_simd/blob/master/blake2b/src/lib.rs
+/// TODO: this is very costly and must be optimized, handled by WASM, or fully offchain.
+library Blake2b {


good idea. worth considering if something else comes up.

sanderpick · 2024-10-25T00:00:31Z

src/util/Blake2b.sol

+/// @dev Implementation of the BLAKE2b hashing algorithm.
+/// See Rust implementation: https://github.com/oconnor663/blake2_simd/blob/master/blake2b/src/lib.rs
+/// TODO: this is very costly and must be optimized, handled by WASM, or fully offchain.
+library Blake2b {


wild stuff here 💪

feat: bucket object operations

dtbuchholz added 6 commits October 23, 2024 14:23

chore: match license files with rust-hoku

f6ab7e0

feat: read-only buckets wrapper

7e4b4ae

refactor: buckets -> lib, mgr

efeec7d

refactor: create bucket metadata | cleanups | docs

69c6e18

chore: unify license, solc version

f3652fe

feat: add errors | fmt fixes | docs cleanups

101cb52

dtbuchholz requested review from sanderpick and avichalp October 23, 2024 21:21

dtbuchholz commented Oct 23, 2024

View reviewed changes

LICENSE

@@ -1,4 +1,6 @@

The MIT License (MIT)

MIT License

Copy link

Contributor Author

dtbuchholz Oct 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i just wanted to use the same licenses from rust-hoku

dtbuchholz commented Oct 23, 2024

View reviewed changes

dtbuchholz added 2 commits October 23, 2024 17:48

chore: linting fixes | package scripts

24951a7

chore: more linting fixes | fix package lint script glob

ccd3325

dtbuchholz force-pushed the dtb/buckets-wrapper branch from 0e4dba0 to ccd3325 Compare October 23, 2024 23:45

dtbuchholz commented Oct 23, 2024

View reviewed changes

dtbuchholz added 3 commits October 23, 2024 22:52

feat: add object to bucket

4b94031

feat: get, delete object | docs | alter method ordering

cbe7dc7

feat: include overloaded 'add' with defaults

4a406d1

sanderpick approved these changes Oct 25, 2024

View reviewed changes

Merge pull request #27 from hokunet/dtb/buckets-ops

00a650b

feat: bucket object operations

dtbuchholz merged commit 9394706 into main Oct 25, 2024
7 checks passed

dtbuchholz deleted the dtb/buckets-wrapper branch October 25, 2024 00:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: buckets wrapper #26

feat: buckets wrapper #26

dtbuchholz commented Oct 23, 2024 •

edited

Loading

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

sanderpick Oct 24, 2024

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

sanderpick Oct 24, 2024

sanderpick Oct 25, 2024

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024 •

edited

Loading

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

dtbuchholz Oct 23, 2024

dtbuchholz commented Oct 24, 2024 •

edited

Loading

sanderpick left a comment

sanderpick Oct 24, 2024

sanderpick Oct 24, 2024

sanderpick Oct 25, 2024


		Creating a bucket will cost native HOKU tokens, and writing to it will cost credit.

		##### List buckets

feat: buckets wrapper #26

feat: buckets wrapper #26

Conversation

dtbuchholz commented Oct 23, 2024 • edited Loading

Summary

Details

Testing

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dtbuchholz Oct 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dtbuchholz commented Oct 24, 2024 • edited Loading

sanderpick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dtbuchholz commented Oct 23, 2024 •

edited

Loading

dtbuchholz Oct 23, 2024 •

edited

Loading

dtbuchholz commented Oct 24, 2024 •

edited

Loading