ZeWIF is Ready for Testing

Community Collaborations
1

I just posted this out to the Community Grants category, but wanted to more generally let people know that the ZeWIF, the Zcash extensible Wallet Interchange Format has advanced sufficiently that you can test it out if you’d like to start importing or exporting the format.

Zmigrate & ZeWIF Crates. The ZeWIF (in-memory representation) and Zmigrate (CLI utility) crates have been released. They currently support full parsing of zcashd files (but without decryption of encrypted data) and Zingo files. Additional details are in the Zmigrate repo.

ZeWIF: GitHub - BlockchainCommons/zewif: ZeWIF: The Zcash Wallet Interchange Format
Zmigrate: GitHub - BlockchainCommons/zmigrate: ZCash wallet migration framework

These are fully accessible by developers who want to start experimenting with importing from their wallet to ZeWIF or exporting from ZeWIF to their wallet. We extend to continue advancing them over the course of April and would love your feedback on what else is needed.

ZCashd Test Suite. The Zcashd test suite was the core that we built ZeWIF from. The adapter can now be found in zewif-zcashd.

ZeWIF-Zcashd: GitHub - BlockchainCommons/zewif-zcashd: ZeWIF adapter for zcashd wallets

Zecwallet Test Suite. Zingo Labs created the first third-party test of our work with a Zecwallet conversion. We’re still coordinating the integration, but the full work & testing can be found in a PR.

ZeWIF-ZecWallet PR: Add ZWL support by dorianvp · Pull Request #3 · BlockchainCommons/zmigrate · GitHub

ZeWIF Documentation. The files in the repos have all been extensively documented to detail the ZeWIF API and data structures and offer usage examples. These docs are currently available as parts of all the src files and will be extracted into Cargo docs upon release of the crates.

Best Practices. The first draft of the best-practices for migration doc has been released. Any comments or thoughts on additional best practices are welcome. (There are also a few holes to fill as the whole specification settles out over the course of April.)

Best Practices: zmigrate/docs/bestpractices.md at master · BlockchainCommons/zmigrate · GitHub

Attachments. Similarly, the attachments draft includes a strong overview of Gordian Envelope and its attachments, with the final few HOW-TOs awaiting the hood being shut on the ZeWIF crate. If you’d like additional clarification or documentation on anything here, just let me know.

Attachments: zmigrate/docs/attachments.md at master · BlockchainCommons/zmigrate · GitHub

That’s it for the moment. Thanks for the continue support and faith in this project.

12 Likes
2

I just posted the following update to the ZCG board. Here’s what we’ve been doing with ZeWIF in the last week:

Wolf has been making good progress on the updated milestone #3.5. The main goal here is to produce the Gordian Envelope file format to allow easy interchange of data between machines.

Since the ZeWIF in-memory format was already closed out (in current draft) with milestone #3, the Envelope format just requires round-tripping from the in-memory format to the file format and back. Wolf is attacking the data structures one at a time. Once everything round trips, writing out to the file, then reading back into the file, with the data structures looking the same, we’re set. At that point, all wallet developers need to do is read their data into the in-memory format or convert the in-memory format back to their wallet, all using the API docs already in the source files.

Here’s a sneak peak at what the Envelope file format looks like. (This is “Envelope notation” so it presents everything as human-readable as possible, with the actual CBOR representation one layer lower.)

45839946 [
    'isA': "SaplingOutputDescription"
    "commitment": Bytes(32)
    "enc_ciphertext": Bytes(580)
    "ephemeral_key": Bytes(32)
    "memo": Bytes(64)
    "note_commitment_tree_position": 522950011
    "witness": Bytes(32) [
        'isA': "SaplingAnchorWitness"
        "witness": [Bytes(32), null] [
            'isA': "IncrementalMerkleTree"
            'isA': "SaplingWitness"
            "cursor": [Bytes(32), null] [
                'isA': "IncrementalMerkleTree"
                "right": Bytes(32)
            ]
            "filled": [Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32)]
        ]
    ]
]
1106195738 [
    'isA': "SaplingOutputDescription"
    "commitment": Bytes(32)
    "enc_ciphertext": Bytes(580)
    "ephemeral_key": Bytes(32)
    "note_commitment_tree_position": 597373669
    "witness": Bytes(32) [
        'isA': "SaplingAnchorWitness"
        "witness": [Bytes(32), null] [
            'isA': "IncrementalMerkleTree"
            'isA': "SaplingWitness"
            "filled": [Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32), Bytes(32)]
            "left": Bytes(32)
            "right": Bytes(32)
        ]
    ]
]

Obviously, this is for Sapling output descriptors, but there will be similar outputs/storage for everything.

As you can see, Wolf has also settled on our internal type system (using isA) to define the various structures, basically because of their quantity and the specificity of many of them for Zcash. (Our other options were CBOR tags and our own Known Value tags, but he settled on this one as the best for extensibility rather than burdening the structure with the need to define everything in an external registry.)

Some upcoming notes:

  1. We’re basically past any technical risks implicit to the project at this point, and just grinding through the final iterations of the work.

  2. I think we’re going to have new releases of the zewif and other repos, with this work, toward the end of this week.

  3. We will be holding a demo on August 16th, likely at 11am PT of using zmigrate and round-tripping data through the file format. I need to double-check the exact time with the principals and then I’ll post the specifics. You’re welcome if you want to joing, but we’ll also have a video available afterward.

4 ) Wolf and I will still be closing out documentation at that point, but in the couple of weeks that close out the month, we’ll be very happy to work with wallet developers to make sure ZeWIF is suiting your needs, so I encourage wallet folks to start looking at what we have so far so that you can take advantage of Wolf’s availability for the last couple of weeks of the month.

As a reminder, here’s the zewif repo that’s the heart of the project: GitHub - BlockchainCommons/zewif: ZeWIF: The Zcash Wallet Interchange Format

Here’s the zmigrate repo that makes use of that for a CLI: GitHub - BlockchainCommons/zmigrate: ZCash wallet migration framework

4 Likes
3

sure its August?
seems very far away :sweat_smile:

4

Thanks. We’ll be holding the demo on APRIL 16th. I should have full details tomorrow.

2 Likes
5

Here’s those full details for the meeting next Wednesday. See you then!

Topic: ZeWIF Envelope Data File Demos
Time: Apr 16, 2025 11:00 AM Pacific Time (US and Canada)

You’ll be able to join through the following link:

1 Like